Collection programme API

Use the Collection programme API to coordinate expected, time-bounded Collections, manage respondent assignments and work with submitted responses and reviews.

The API is hosted by Govform Builder. It is separate from the APIs hosted by QA and Production services because Builder securely routes each request to the collection environment you specify.

Before you start

Create an API key from Library settings → Govform API keys. Give the key only the permissions it needs:

Permission	Capability
`apiCollectionProgrammeRead`	Read collection programmes, collections, respondent organisations and contacts, assignments, submitted answer versions, reviews, communications and audit events.
`apiCollectionProgrammeWrite`	Create and update collection programmes and collections; manage lifecycle, cohorts, assignments, rosters and reviews. Write permission also permits reads.
`apiFormRead`	Additionally required to read saved Collection review settings; apiFormWrite also permits this read.
`apiFormWrite`	Additionally required to create a Collection or save its managed form review settings.
`apiFormDeploy`	Additionally required to prepare the latest saved collection form for use in QA, Staging or Production.

This separation lets you create one integration that works with form designs and another that works with Collection programme data. A key with form permissions does not receive Collection programme data unless it also has apiCollectionProgrammeRead or apiCollectionProgrammeWrite.

Collection programme response data can contain personal or otherwise sensitive information. Use IP allowlists, store the key in a secrets manager and grant the narrowest permission possible.

Base URL and authentication

All Collection programme API paths use this Builder base URL:

https://app.govform.com/builder/libraries/{libraryId}/api/response-hub

Send the API key in the Authorization header. HMAC authentication is recommended; the legacy raw-key form is also supported:

Authorization: GovformsApiKey KEY_ID:SECRET_VALUE
Content-Type: application/json

You may send X-On-Behalf-Of with a user or integration identity to make audit records more descriptive. If it is omitted, the API key ID is used.

Common identifiers

Name	Meaning
`libraryId`	The Govform library ID. Every operation is restricted to this tenant.
`collectionProgrammeId`	The stable ID of a collection programme.
`environment`	`qa`, `staging` where enabled, or `production`.
`collectionId`	The immutable ID of one collection period in one environment.
`assignmentId`	A respondent organisation's assignment in a collection.
`responseId`	The response linked to an assignment.
`workItemId`	A review item for one immutable submitted response version.

Dates are ISO 8601 strings. Collection timetable dates may be supplied as YYYY-MM-DD. Opening and scheduled review dates resolve to the start of that day in the library's service time zone; response deadlines (including assignment and CSV deadlines) include the whole day in that zone. Datetimes without an offset also use service time. Explicit timestamps with Z or an offset retain their supplied instant. Values are stored as absolute timestamps; saving region settings does not rewrite existing programme dates.

List endpoints accept page and pageSize; page size is capped at 100. Relevant endpoints also accept search, sort, direction=asc|desc, and assignment filters. These endpoints retain their page-based defaults and response wrappers. The response-summary, response-version, review-comment and export-operation lists use cursor pagination by default.

For integrations that need a reliable traversal of a larger dataset, snapshot cursor access is available to every API key with the relevant existing Response Hub permission. For lists with an existing page-based contract, only pagination=cursor selects snapshot cursor access. A cursor parameter alone or another pagination value retains page-based behaviour. Response-summary, response-version, review-comment and export-operation lists are cursor-first.

Snapshot cursor lists

Start a traversal with pagination=cursor. Cursor mode accepts pageSize from 1 to 100 and defaults to 100. It returns a fixed point-in-time view and does not calculate an exact total:

{
  "items": [],
  "pageSize": 100,
  "hasMore": true,
  "nextCursor": "opaque-value",
  "snapshotAt": "2026-08-08T10:15:30.000Z",
  "snapshotExpiresAt": "2026-08-08T10:17:30.000Z"
}

Pass only pagination=cursor&cursor=opaque-value for the next page. You may repeat pageSize, the canonical sort, direction or expand, but repeated values must match the cursor. Do not use page, search or filters in cursor mode. Cursors are bound to the key, library, environment, collection and normalized query, and cannot be transferred to another scope.

A completed traversal returns every matching record from one fixed snapshot exactly once. Process a page durably before committing its nextCursor. Retrying the same cursor can return the same page. Snapshot cursors are intentionally short-lived; if a cursor expires, the API returns 410 CURSOR_EXPIRED with restartRequired: true and the traversal must restart.

Assignments support expand=organisation,memberships,response,activeReview; reviews support expand=organisation,memberships,response,assignment. Without expand, assignment items contain only { "assignment": ... } and review items contain only { "workItem": ... }; selected relations are added beside that base record. Original page-mode enrichment is unchanged.

Endpoints

All paths below follow /builder/libraries/{libraryId}/api/response-hub.

Collection programmes

Method and path	Capability
`GET /collection-programmes`	List collection programmes.
`POST /collection-programmes`	Create a collection programme.
`GET /collection-programmes/{collectionProgrammeId}`	Get programme defaults and message templates.
`PATCH /collection-programmes/{collectionProgrammeId}`	Update the programme name, Purpose (`description`), defaults and message templates used by future collections.

Create a Collection programme:

{
  "collectionProgrammeId": "annual-returns",
  "name": "Annual returns",
  "description": "Collect annual assurance evidence from partner organisations.",
  "defaults": {
    "retentionDays": 2555,
    "defaultPolicy": {
      "openingDate": "2026-09-01",
      "effectiveDeadline": "2026-10-01",
      "reminderOffsetDays": 7,
      "reviewStartMode": "onSubmission",
      "amendmentWindow": "never",
      "reopeningReasonPolicy": "required"
    }
  }
}

The optional description is the programme's Purpose, limited to 500 characters. Omit it on update to preserve the current purpose; send an empty string to clear it. Partial defaults.messages updates preserve unspecified templates. Programme defaults apply to future Collections; they do not rewrite existing Collection settings.

Collections and form application

Method and path	Capability
`GET /collection-programmes/{collectionProgrammeId}/collections/{environment}`	List collections in an environment.
`POST /collection-programmes/{collectionProgrammeId}/collections`	Create a Collection and its dedicated form from a saved source form version.
`GET /collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}`	Get one collection.
`PATCH /collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}`	Update a draft collection's name, timetable, policy and retention.
`POST /collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/transition/{action}`	`open`, `close` or `reopen` a collection. Reopening requires a reason.
`GET /collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/review-settings`	Read saved review settings and revision metadata; also requires form-read or form-write access.
`PATCH /collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/review-settings`	Save supported review and answer-history settings on a draft/open Collection form; also requires form-write access.
`POST /collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/apply-form`	Apply the latest saved collection form.
`GET /collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/form-revisions`	List applied revision metadata. Form definitions are intentionally omitted.

Create a collection:

{
  "environment": "qa",
  "sourceFormId": "my-library-source-return",
  "sourceSsId": "saved-version-id",
  "name": "2026 annual return",
  "policy": {
    "openingDate": "2026-09-01",
    "effectiveDeadline": "2026-10-01"
  }
}

Applying a form in a remote environment prepares a deployment and returns an approvalUrl. Open that URL as an authorised user to confirm the change. This preserves the existing human deployment boundary. If the saved form is already active, the API returns status: "upToDate".

Renaming through PATCH .../{collectionId} changes Collection.name only. It does not rename the managed Collection form (Form.formName), save a new form revision or rename an applied/deployed form. Clients should treat the Collection name and form name as separate values. The same behaviour applies to MCP update_programme_collection.

Collection review settings

Ordinary form APIs still exclude managed Collection forms. Use the Collection-specific review-settings endpoint to read and change Require review in Response Hub, Require claiming before review, Allow changes during review and Answer change history. The read returns no answers, pages, actions or credentials. It requires Collection-read (or write) and form-read (or write) permissions; saving requires both Collection-write and form-write.

GET .../{collectionId}/review-settings returns formSsId, formVersion, the saved review and answer-history settings, appliedFormSsId, appliedReviewClaimRequired and hasUnappliedChanges.
PATCH .../{collectionId}/review-settings requires that formSsId as expectedSsId and at least one setting. Omitted settings are preserved; unrelated form properties are rejected. A stale revision or a closed/purged Collection returns 409.
Saving returns status: "saved" and the new settings/revision metadata. It does not apply the form or change the runtime requirement. Apply the saved form separately with apply-form, completing its normal deployment confirmation.

{
  "expectedSsId": "saved-version-id-from-get",
  "responseHubReviewRequired": "true",
  "responseHubReviewClaimRequired": "false"
}

MCP uses get_programme_review_settings and update_programme_review_settings with the same inputs and results, then apply_programme_form. OAuth requires form-design and Collection data access in the same library. Writes respect approval requirements from both grants. These operations do not grant general editing access to managed forms or change ownership.

Cohorts, assignments and roster imports

Method and path	Capability
`GET .../{collectionId}/cohorts`	List cohorts.
`POST .../{collectionId}/cohorts`	Create a cohort with optional policy overrides.
`PATCH .../{collectionId}/cohorts/{cohortId}`	Update a non-default cohort before opening.
`GET .../{collectionId}/assignments`	List assignments with organisation, contact, response and review context.
`POST .../{collectionId}/assignments`	Create or update an assignment using a stable external organisation ID.
`POST .../{collectionId}/assignments/{assignmentId}/cancel`	Cancel an assignment while preserving response history.
`POST .../{collectionId}/roster`	Stage and validate a base64-encoded CSV roster.
`POST .../{collectionId}/roster/{rosterJobId}/apply`	Apply a staged roster with `mode` set to `merge` or `replace`.

Upsert an assignment:

{
  "externalOrganisationId": "ORG-1042",
  "organisationName": "Example authority",
  "userEmail": "returns@example.gov.uk",
  "userDisplayName": "Returns team",
  "cohortId": "optional-cohort-id",
  "dueAt": "2026-10-01T23:59:59Z"
}

Roster staging does not change respondents. It returns a preview containing creates, updates, unchanged assignments and omissions. Apply that preview separately after checking it.

Responses, reviews, communications and audit

Method and path	Capability
`GET .../{collectionId}/responses/{responseId}`	Get a response, immutable submitted answer versions, active review and comments.
`GET .../{collectionId}/responses`	Cursor-first list of response summaries.
`GET .../{collectionId}/responses/{responseId}/versions`	Cursor-first list of immutable response versions.
`GET .../{collectionId}/reviews`	List available and claimed review work.
`GET .../{collectionId}/reviews/{workItemId}`	Get one review and its submitted answer version.
`GET .../{collectionId}/reviews/{workItemId}/issues`	Cursor-first list of review comments.
`POST .../{collectionId}/reviews/{workItemId}/{action}`	`claim`, `accept`, `return`, `release`, `reassign` or `addIssue`.
`GET .../{collectionId}/communications`	List queued, sent, failed and cancelled respondent messages.
`GET .../{collectionId}/audit`	List append-only collection audit events.

Review commands accept an optional commandId for safe retry. Returning, releasing and reassigning require a reason. addIssue accepts a target for a field, bulk-data source row or exact bulk-data cell.

Review and claiming are separate managed-form settings. Form.responseHubReviewRequired is a string boolean, default "false", controlling reviews for new submissions. Form.responseHubReviewClaimRequired is a string boolean, default "true". Collection read results expose the applied reviewClaimRequired boolean (missing means true). When it is false, accept, return and addIssue work on available reviews without a claim. Claims remain optional and reserve the review for that reviewer. Other reviewers' claims, held-review eligibility and normal access checks still apply. Changing the claiming requirement also affects existing available reviews after form application.

{
  "commandId": "integration-command-2026-00042",
  "reason": "The totals do not reconcile with the uploaded schedule."
}

Submitted versions are immutable. The API returns the answer snapshot associated with that version, rather than regenerating it from a later form design.

Bulk exports

Use an asynchronous export to download selected collection data in compressed parts, for example after a collection has finished. Export operations require Response Hub read access and do not change collection business data.

Each batch reads the data available when that batch is processed. An export does not represent a single point in time: changes during processing may be reflected in later batches, and additions/deletions may affect which records appear. Related records can therefore reflect different moments. Export after collection work has settled when a stable dataset is wanted. Stored response versions remain immutable.

The manifest declares consistency: "read-as-processed" and records startedAt and completedAt; it does not return snapshotAt. Batches use stable ordering so edits to names, review state or schedules do not move existing records between pages. Exports do not depend on MongoDB retaining a historical view for the job's duration.

Method and path	Capability
`POST .../{collectionId}/exports`	Start or safely retry an export; returns `202`, `Location` and `Retry-After`.
`GET .../{collectionId}/exports`	Cursor-first list of export operation metadata.
`GET .../{collectionId}/exports/{exportId}`	Poll status and progress; supports `ETag` and `If-None-Match`.
`DELETE .../{collectionId}/exports/{exportId}`	Request cancellation. Read-only access can cancel only an export started by the same API key.
`GET .../{collectionId}/exports/{exportId}/manifest`	Get the manifest after successful completion.
`GET .../{collectionId}/exports/{exportId}/parts/{partId}`	Download one authenticated gzip-compressed result part.

Start an export with a caller-chosen requestId and the normalized resources you need:

{
  "requestId": "warehouse-annual-2026-08-08",
  "resourceTypes": ["cohorts", "assignments", "responses", "responseVersions", "reviewWorkItems", "reviewIssues"],
  "format": "ndjson",
  "compression": "gzip",
  "includeBulkArtifacts": false,
  "includeAnswerFiles": false
}

Retrying the same authorized request returns the original operation. Reusing requestId with a different selection returns 409 EXPORT_CONFLICT. Resources are normalized into independent parts. Organisation and membership output contains only records reached through the collection's respondents. Form revision output contains metadata, never form definitions.

The manifest is published only after every part is complete. Each entry includes its record count, compressed and uncompressed byte sizes, SHA-256 checksum and authenticated download URL. Data-resource parts are NDJSON. includeBulkArtifacts and includeAnswerFiles are deprecated compatibility properties and do not create copied artifact parts. Response-version values contain allowlisted metadata and authorised Govform download links instead; uploaded files and bulk datasets are never placed inside an export. Internal storage references are never returned. Downloads include ETag and Repr-Digest; verify the exact compressed representation and manifest totals before committing an import.

Exports expire no later than 24 hours or collection retention, whichever is earlier. Retention and purge always win: expired or purging results return 410 and their artifacts are removed.

Errors and safe retries

Errors use an HTTP status and JSON body:

{
  "error": {
    "message": "Collection not found"
  }
}

Typical statuses are:

400 for missing or invalid input;
403 for an invalid key, IP restriction or missing permission;
404 when a tenant- and collection-scoped record is not found;
409 when the requested lifecycle change is not valid in the current state.

Cursor and export errors keep the same outer shape and add a stable code. Cursor expiry also includes restartRequired; a temporarily unavailable snapshot or not-yet-ready export may include Retry-After. Cursor and export operations return these additional fields. Other errors use { "error": { "message": "..." } }.

Read operations are safe to retry. Review commands should reuse their commandId. Roster import is deliberately staged and applied in two calls. Collection IDs, response versions and audit history are never replaced by update requests.

Download submitted evidence

Use the same Builder host and Collection programme read or write permission. These are authenticated byte streams, not Base64 JSON responses. Start from a submitted response version's returned download links, which identify the retained evidence.

All paths below follow /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}.

Method and path	Capability
GET /responses/{responseId}/versions/{versionNumber}/files/{fieldId}/{fileIndex}	Stream one ordinary uploaded file from a submitted version.
GET /responses/{responseId}/versions/{versionNumber}/bulk/{fieldId}/{artifact}	Stream a retained Bulk Data artifact from a submitted version.

versionNumber is a positive submitted-response version number; fileIndex is zero-based. For repeating fields, supply iteration as a zero-based query parameter. Bulk artifact values are canonical (confirmed CSV), source (untouched upload) or errors (retained validation-errors CSV). These Collection programme values differ from the ordinary submitted-data endpoint's current artifact selector.

Downloads remain subject to the response's retention and availability. They never fall back to a different submitted version. Invalid path selectors or unavailable evidence return 404. Responses include the content type and an attachment filename where available, and may include content length. Stream files in the client.

Collection programme list and ordinary change calls generally use 5 API units, single status or manifest reads use 1, and exports, roster operations and Bulk Data downloads use 25. Ordinary response-file download paths follow the 5-unit class. Consult the API-unit response headers for the charged class and follow API units and limits.

See the endpoint index, service discovery and schemas and ordinary submission file downloads.

Live review and answer change history

Managed-form review settings also accept responseHubReviewAllowChanges (string true/false, default false) and responseHubAnswerChangeHistory (off, fromStart, afterSubmission, default off). Supply expectedSsId from the settings read. Saving requires form-design write access as well as Collection programme access; apply the form separately. Both options apply to new response identities.

For live reviews, the review read includes currentAnswers (confirmed spreadsheets carry authenticated sourceDownloadUrl and currentCsvDownloadUrl links under reviews/{workItemId}/bulk/{fieldId}/{source|canonical}), currentAnswersComplete, latestSavedAt, acceptanceFailure and expectedAnswers. Pass that expectedAnswers object, containing answersHash, unchanged in an accept request. Refresh after a conflicting save. Acceptance validates current answers, closes editing and starts configured closure workflows. If the response needs a caseworker form, accept is refused until it has been submitted; during live review one submission before acceptance is enough. Acceptance retains separate accepted evidence without changing submitted-version numbers. return is unavailable in live mode.

Use review action editIssue with issueId, expectedUpdatedAt (the comment’s updatedAt, or createdAt if never edited), respondentMessage and optional internalNote. Existing claim rules apply. Additions and edits are audited. Public feedback appears on the next respondent request; no feedback email is sent.

Under the same Collection API base path, GET /responses/{responseId}/changes returns at most 25 newest-first entries. Omit page for the newest page and request page-1 for older entries. GET /responses/{responseId}/changes/{changeId}?page=N reads one committed checkpoint. Follow its authenticated file links at /responses/{responseId}/changes/{changeId}/files/{fileIndex}?page=N. These reads use existing Collection programme read/write permissions and retention. Internal storage keys are not download links.

For live or accepted-review files, follow the authenticated links returned by the review read at GET /reviews/{workItemId}/files/{fieldId}/{fileIndex}?iteration=N. The optional zero-based iteration selects a repeated answer. Accepted-file links use retained evidence; initial submitted files keep their submitted-version URLs.

Comment on the whole form or an individual field

On the review screen, use Comment on the whole form for the overall comment sent with Return for changes. It is required when returning a response, but not when accepting it. The rich editor opens in Text mode by default. Use its toolbar for formatted text; the comment is stored as Markdown and displayed with formatting to staff and the respondent.

For a particular answer, go to Field comments, expand Comment on an individual field, choose the Answer, write your comment and select Add field comment. Repeat for other fields. Field comments are plain text and appear beside the relevant answers and in the summary.

The whole-form return comment and field comments are shared with the respondent. Internal notes are visible only to staff. In standard review, the respondent sees the comments when you return the response. Ordinary Form responses send no automatic return email; Collections send their return email.

With Allow changes during review, staff can add or edit field comments and respondents see them on their next visit, without an email. Return for changes and its whole-form comment are unavailable in this mode. Ordinary live-review field comments also support replies. Standard reviews and Collection programmes have no replies.

Existing REST/MCP names remain unchanged for compatibility: addIssue, editIssue, issueId, issues, list_programme_review_issues and the /issues endpoint refer to comments. Use reason for the whole-form return comment in Markdown (up to 5,000 characters); target and respondentMessage identify a plain-text field, bulk-data row or cell comment. internalNote stays private. Each respondentMessage and internalNote can be up to 5,000 characters. These Collection tools do not operate ordinary Form responses; ordinary casework uses the browser.

Ordinary response comment conversations

Ordinary Form responses with Allow changes during review support field comment history and staff/respondent replies in the browser. Standard reviews and Collection programmes have no replies. Public REST, MCP and Darcy have no ordinary-response reply/history operation, and Collection review endpoints cannot operate ordinary responses. See field comment history and replies for the workflow, statuses and permissions. Review and answer-history settings still use their existing authoring APIs and separate save/deploy or save/apply steps.