Govform.com
Skip to article
DocumentationGuides & reference

Search across guides and reference articles. Try “email”, “API” or “conditions”.

Govform API & MCP

Govform API endpoint index

Find the customer REST endpoints for services, definitions, submitted data, files, analytics, Collection programmes, User portal settings and data source discovery, and Darcy tools. Each entry links to its request, response and permission guidance.

API hosts and authentication

Builder: https://app.govform.com, or your private Builder host. QA: https://qa.cloud.govforms.uk. Production: https://cloud.govforms.uk. Use the configured host for your organisation's other environments.

Library REST calls use a library API key through Authorization: GovformsApiKey <key-id>:<key-secret>, or GovformsApiHmac. Only grant the permissions your integration needs. JSON writes use Content-Type: application/json. API usage follows the shared units and limits.

Use service discovery when you know the library ID but need its Service IDs. Builder definitions can differ from deployed versions; use the target environment's status endpoint to verify what is running.

Builder service, portal and Darcy endpoints

Call these paths on the Builder host. Permission alternatives mean either named permission is sufficient; individual tools may impose additional checks described in their guide.

Method and path API-key permission Guide
GET /builder/libraries/{libraryId}/api/caseworker-portalapiCaseworkerPortalReadCaseworker portal settings
PATCH /builder/libraries/{libraryId}/api/caseworker-portalapiCaseworkerPortalWriteCaseworker portal settings
GET /builder/libraries/{libraryId}/api/user-portal apiPortalRead Read, update and deploy User portal settings
PATCH /builder/libraries/{libraryId}/api/user-portal apiPortalWrite Read, update and deploy User portal settings
POST /builder/libraries/{libraryId}/api/user-portal/deployments apiPortalDeploy Read, update and deploy User portal settings
GET /builder/libraries/{libraryId}/api/forms apiOrgRead List services, metadata and form schemas
POST /builder/libraries/{libraryId}/api/forms/{formId} apiFormWrite Create, update and delete services through the API
DELETE /builder/libraries/{libraryId}/api/forms/{formId} apiFormWrite Create, update and delete services through the API
GET /builder/libraries/{libraryId}/api/form/{formId} apiFormRead List services, metadata and form schemas
GET /builder/libraries/{libraryId}/api/form/{formId}/summary apiFormRead List services, metadata and form schemas
PUT /builder/libraries/{libraryId}/api/save-form-version/{formId} apiFormWrite Create, update and delete services through the API
POST /builder/libraries/{libraryId}/api/darcy/form-lock/{formId} apiFormWrite Create, update and delete services through the API
PUT /builder/libraries/{libraryId}/api/darcy/form-lock/{formId} apiFormWrite Create, update and delete services through the API
DELETE /builder/libraries/{libraryId}/api/darcy/form-lock/{formId} apiFormWrite Create, update and delete services through the API
GET /builder/libraries/{libraryId}/api/deployments/{formId} apiFormRead List services, metadata and form schemas
POST /builder/libraries/{libraryId}/api/deployments apiFormDeploy Create, update and delete services through the API
GET /builder/libraries/{libraryId}/api/darcy/tools/catalog apiDarcyToolRead or apiDarcyToolWrite Discover and run Darcy REST tools
POST /builder/libraries/{libraryId}/api/darcy/tools/{toolName} Tool-specific permission Discover and run Darcy REST tools
POST /builder/libraries/{libraryId}/api/darcy/ask apiDarcyAsk Discover and run Darcy REST tools
POST /builder/libraries/{libraryId}/api/darcy/agent apiDarcyAgent Discover and run Darcy REST tools
PUT /builder/libraries/{libraryId}/api/upsert-service-definition/{formId} upsertServiceDefinition Create, update and delete services through the API
PUT /builder/libraries/{libraryId}/api/start-deployment/{formId}/{version}/{env} triggerServiceDeployment Create, update and delete services through the API

QA and Production data and deployment endpoints

Call these paths on the relevant service environment's host. serviceId is the Service ID without its library prefix.

Method and path API-key permission Guide
GET /api/submitted-data/{libraryId}/{serviceId} fetchCustomerData Fetch submitted form data
POST /api/submitted-data/{libraryId}/{serviceId}/delete deleteSubmittedData Delete submitted form data
PUT /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/status setFormStatus Set submitted form status
GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/files fetchCustomerData List and download uploaded files and signatures
GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/files/{fieldId} fetchCustomerData List and download uploaded files and signatures
GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/bulk/{fieldId}/{artifact} fetchCustomerData Bulk Data files and submitted revisions
GET /api/analytics-events/{libraryId}/{serviceId} fetchAnalyticsEvents Fetch analytics events
GET /api/analytics-journeys/{libraryId}/{serviceId} fetchAnalyticsJourneys Fetch journey analytics records
GET /api/billing-transactions/{libraryId}/{serviceId} apiGetBillingTransactions Legacy billing transaction totals (1-unit class)
GET /api/service-deployments/{libraryId}/{serviceId} getDeployedServiceVersion Get deployed service version
PUT /api/service-deployments/{libraryId}/{serviceId}/{version} triggerServiceDeployment Trigger service deployment

Collection programme endpoints

Call these paths on the Builder host. environment selects the Collection's environment. Creating a Collection additionally requires apiFormWrite; applying its form additionally requires apiFormDeploy. Response Hub must be enabled for the library.

Method and path API-key permission Guide
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId} apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId} apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/review-settings (apiCollectionProgrammeRead or apiCollectionProgrammeWrite) and (apiFormRead or apiFormWrite) Collection review settings
PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/review-settings apiCollectionProgrammeWrite and apiFormWrite Collection review settings
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/transition/{action} apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/apply-form apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/cohorts apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/cohorts apiCollectionProgrammeWrite Collection programme API
PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/cohorts/{cohortId} apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/assignments apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/assignments apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/assignments/{assignmentId}/cancel apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions/{versionNumber}/files/{fieldId}/{fileIndex} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions/{versionNumber}/bulk/{fieldId}/{artifact} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews/{workItemId}/issues apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews/{workItemId} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews/{workItemId}/{action} apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/communications apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/audit apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/form-revisions apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
DELETE /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}/manifest apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}/parts/{partId} apiCollectionProgrammeRead or apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/roster apiCollectionProgrammeWrite Collection programme API
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/roster/{rosterJobId}/apply apiCollectionProgrammeWrite Collection programme API

MCP connections and OAuth endpoints

These are Builder endpoints. OAuth discovery and registration prepare the connection; the consent page uses an authenticated browser session. OAuth MCP and its evidence-download links require the connection's bearer token and selected library permissions. Library API-key MCP uses the same library key as REST. Follow the MCP connection guide rather than manually posting to the consent page.

Method and path Purpose
GET /builder/.well-known/oauth-protected-resource MCP resource metadata
GET /builder/.well-known/oauth-authorization-server OAuth server metadata
GET /builder/.well-known/openid-configuration Discovery metadata alias
POST /builder/oauth/register Register an OAuth client
GET /builder/oauth/authorize Interactive consent page
POST /builder/oauth/authorize Submit consent from the authenticated browser
POST /builder/oauth/token Exchange or refresh OAuth tokens
POST /builder/oauth/revoke Revoke an OAuth token
GET /builder/mcp OAuth MCP transport; requires bearer authentication
POST /builder/mcp OAuth MCP protocol requests; requires bearer authentication
POST /builder/libraries/{libraryId}/mcp Library API-key MCP protocol requests
GET /builder/libraries/{libraryId}/mcp/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}/parts/{partId} OAuth-authorised export-part download
GET /builder/libraries/{libraryId}/mcp/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions/{versionNumber}/files/{fieldId}/{fileIndex} OAuth-authorised submitted file download
GET /builder/libraries/{libraryId}/mcp/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions/{versionNumber}/bulk/{fieldId}/{artifact} OAuth-authorised submitted Bulk Data download

Use the connection URL supplied for the release you intend to use; browser release cookies do not select an MCP release. Evidence links returned by a connection already identify the appropriate download host and path. Never substitute a library API key for the OAuth bearer token on those MCP download links.

Choose a guide

See authentication headers for raw-key and HMAC formats.

Disposable journey testing

POST /builder/mcp and POST /builder/libraries/{libraryId}/mcp expose testJourney when advertised by the connection. The REST equivalent is POST /builder/libraries/{libraryId}/api/darcy/tools/testJourney. See test journeys through MCP and the API for access, request examples and result interpretation.

Answer change checkpoints

Collection response Change log reads and retained-file downloads are documented in the Collection programme API. They share its read permissions, environment scope and retention. Live acceptance uses the expected answer state returned by the review read.

Temporary demos without an account

The separate POST /builder/try/mcp connection creates browser demos that expire after 14 days, using a private management token for later changes. It grants no access to existing libraries or deployment. See Create a temporary demo with an AI client for the tools, settings and limits.

Approved admin submission investigations

Govform staff and configured platform administrators can investigate a specific library’s submissions through the interactive OAuth connection. Customer library administrators and library API keys cannot use these operations. Every search page and retrieval needs its own one-use Builder approval confirming permission from that customer’s GDPR data controller for the exact records and purpose.

MCP toolOAuth POST endpointResult
search_submission_user_data/builder/api/admin-submission-data/searchCurrent submission metadata; default 20, maximum 50 records.
get_submission_user_data/builder/api/admin-submission-data/getCurrent journey answers, action results, state and caseworker source linkage.
get_submission_version/builder/api/admin-submission-data/versionOne retained ordinary response version, submitted answers and captured caseworker source linkage.

All calls select org, formId and environment (qa, staging or production). Retrieval also requires submissionId. Version retrieval accepts optional positive versionNumber; omit it for the latest retained version. Missing evidence returns not found: it is never reconstructed or replaced by current answers. Collection response versions use the Collection programme operations. Files are metadata only; configured Secrets remain masked.

Supply approvalDescription naming the library/customer and purpose. On CONSENT_REQUIRED, present the returned approvalUrl, wait for the admin to approve in Builder and confirm, then retry the identical request with approvalToken. Early access OAuth uses /builder/early-access/api/admin-submission-data/{search,get,version}. These reads do not authorise actions, edits or deployment.

Darcy provides matching approved admin sidebar tools. Its Builder release check reports Main or Early access separately from the response data environment. A selected Staging environment does not establish that Early access Builder is switched on.

SharePoint upsert mapping checks

Saves of an existing service through REST, MCP and Darcy check linked SharePoint lookup and update column mappings. Each update value is written to the lookup list column with the same name, so an update may list only the columns it changes; unlisted columns are left unchanged. Saving an edited update adds new list columns to its lookup without removing any. Conflicting, ambiguous or unknown mappings and removal of non-empty mapped columns return HTTP 400 with SHAREPOINT_LIST_MAPPINGS_INCONSISTENT and a review message. Refresh and review the linked list settings in Builder before retrying. Authoring tools do not contact SharePoint to refresh columns or run Automap. Unrelated edits to older services remain possible; deployment checks the exact version selected. Saving and deploying remain separate operations, with existing permissions and approval requirements.

Data Rooms endpoints

Call room commands and file streams on the Builder host with dedicated room permissions. See Read and manage Data Rooms through the API for the three endpoint paths, command examples, revisions, limits and save behaviour.

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.

Retrieve and recreate public demos

Use retrieve_demo_service with the demoId (the d-… segment of the shared prototype URL). No management token is needed to retrieve a public design. This operation is available on the separate anonymous MCP connection, authenticated Builder MCP and Darcy. The result includes the latest form, settings, state (active or archived), expiresAt and retainUntil; it contains no answers, version history or private management metadata.

Working demos expire after 14 days. Their latest definition and branding, including inline images, remain retrievable for twelve calendar months after expiry. Archived designs do not count towards the 5,000 active-demo cap. Retrieval stops at the retention deadline even if physical deletion is delayed. A token-authorised deletion permanently removes active or archived data without retaining a recovery copy.

For another public demo, use the anonymous create_demo_service tool with the retrieved definition and settings. It receives a new ID, management token and fourteen-day lifetime under the existing creation limits. For an ordinary service, authenticated MCP create_form accepts demoId instead of form, together with the destination org and new formId. REST clients send the same optional source to POST /builder/libraries/{org}/api/forms/{formId} with the existing apiFormWrite permission. Do not supply both demoId and form. Existing library permissions, write approvals and capacity checks apply. Darcy uses createService with creationMethod: "blank", demoId and the desired name/ID. Creation saves a new service without deploying it.

{"demoId":"d-example123","formName":"Recovered service"}

Use destination-library branding by default. The AI should ask whether the user wants the demo branding applied to the library and explicitly explain: This changes the branding for every service/form in this library. Only apply agreed branding through the existing library-settings permissions, approvals and save/apply steps. Do not implicitly copy regional settings or deploy anything. See Create a temporary demo with an AI client for setup and recovery guidance.

More in developers