API units: Response Hub pages are capped at 100 records and use 5 units. Roster and export data operations use 25 units.

API units by operation

Only successful calls and accepted asynchronous jobs consume monthly units.

Use the Response Hub API to automate recurring data collections, manage respondent assignments and work with submitted responses and reviews.

The API is hosted by Govforms Builder. It securely routes each request to the collection environment specified in the path.

Before you start

Create an API key from Library settings → Govforms API keys. Grant only the permissions the integration needs:

• apiResponseHubRead — read services, collections, respondent organisations and contacts, assignments, submitted answer versions, reviews, communications and audit events.
• apiResponseHubWrite — create and update services and collections; manage lifecycle, cohorts, assignments, rosters and reviews. Write permission also permits reads.
• apiFormWrite — additionally required when creating a collection because Govforms creates its managed form from a saved form version.
• apiFormDeploy — additionally required to prepare the latest collection form for QA, Staging or Production.

Form-design permissions and Response Hub data permissions are independent. A key can work with forms without seeing live Response Hub data, or work with Response Hub without seeing unrelated form designs.

Base URL and authentication

All paths use the Builder base URL:

https://govforms.uk/builder/libraries/{libraryId}/api/response-hub

Send Authorization: GovformsApiKey KEY_ID:SECRET_VALUE and Content-Type: application/json. HMAC authentication is recommended. An optional X-On-Behalf-Of header can identify the responsible user or integration in audit records.

Every request is restricted to the library in the path. Environments are qa, staging where enabled, and production. List operations accept page and pageSize, capped at 100; relevant operations also accept search, sort and assignment filters.

Data collection services

• GET /services — list data collection services.
• POST /services — create a data collection service.
• GET /services/{serviceId} — get service defaults and message templates.
• PATCH /services/{serviceId} — update the service name, defaults and templates used by future collections.

Collections and form application

• GET /services/{serviceId}/collections/{environment} — list collections.
• POST /services/{serviceId}/collections — create a collection and managed form from a saved source form version.
• GET /services/{serviceId}/collections/{environment}/{collectionId} — get one collection.
• PATCH /services/{serviceId}/collections/{environment}/{collectionId} — update a draft collection.
• POST /services/{serviceId}/collections/{environment}/{collectionId}/transition/{action} — open, close or reopen a collection. Reopening requires a reason.
• POST /services/{serviceId}/collections/{environment}/{collectionId}/apply-form — apply the latest saved collection form.
• GET /services/{serviceId}/collections/{environment}/{collectionId}/form-revisions — list applied revision metadata. Form definitions are intentionally omitted.

Applying a form in QA, Staging or Production prepares a deployment and returns an approvalUrl. An authorised person must open that link to confirm the change. This keeps the existing human deployment boundary.

Cohorts, assignments and rosters

• 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 in merge or replace mode.

Roster staging does not change respondents. It returns a preview of creates, updates, unchanged assignments and omissions so the result can be checked before applying it.

Responses, reviews, communications and audit

• GET .../{collectionId}/responses/{responseId} — get a response, immutable submitted answer versions, active review and issues.
• GET .../{collectionId}/reviews — list available and claimed review work.
• GET .../{collectionId}/reviews/{workItemId} — get one review and its submitted answer version.
• POST .../{collectionId}/reviews/{workItemId}/{action} — claim, accept, return, release, reassign or add an issue.
• 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. Submitted versions are immutable: the API returns the answer snapshot associated with the selected version, not a later form design.

Example

Create a data collection service:

POST /builder/libraries/demo-library/api/response-hub/services
Authorization: GovformsApiKey KEY_ID:SECRET_VALUE
Content-Type: application/json

{
 "collectionServiceId": "annual-returns",
 "name": "Annual returns",
 "defaults": {
   "retentionDays": 2555
 }
}

Errors and safe retries

Errors return JSON with an error.message. Typical statuses are 400 for invalid input, 403 for an invalid key or missing permission, 404 when a scoped record is not found, and 409 for an invalid lifecycle transition.

Read operations are safe to retry. Reuse a review command's commandId. Roster import is deliberately staged and applied in two calls. Collection IDs, response versions and audit history are never replaced by update requests.

‍

Bulk Data evidence and integrations

The validated CSV includes respondent corrections; the untouched upload is retained separately. Use Upload files to send a selected Bulk Data evidence version to a configured file store. API actions can send up to 25 MiB of combined raw files as Base64; larger files can be streamed through the Bulk Data download API. Submitted revision selection requires retained Response history.

Bulk Data files, submitted revisions and integration examples