Govform API

Govform provides API endpoints that can be called by applications owned by your organisation to discover services, read their definitions, fetch customer-submitted data and control deployments.

Note this is different from where you want a page in a Govform service to call out to an API during the customer journey. To do that, use API Actions, found under Page Actions.

Choose an API endpoint

Use the API endpoint index to find customer-callable REST operations, their hosts, permissions and detailed guides. It covers service definitions and deployment requests, submitted data and evidence, analytics, User portal settings, Collection programmes and Darcy tools.

Find service IDs and definitions

You do not need to know each Service ID in advance. Call GET https://app.govform.com/builder/libraries/{libraryId}/api/forms to list services, metadata and confirmed deployment status per environment in a library. Separate Builder endpoints return field summaries, full definitions and deployment history.

See List services, metadata and form schemas for permissions, request and response examples, identifier handling and how to build an inventory of deployed services. These are ordinary REST calls; no AI or MCP client is required.

API units: For Cloud accounts, each successful REST call and MCP tool call uses 1, 5 or 25 units from the account's monthly allowance. Operational hourly and daily limits also use these weighted units.

API units and limits

API keys and MCP access share the Cloud account's API allowance. Government Cloud accounts, including legacy accounts, and libraries without an assigned account are exempt from these Cloud quotas. Enabling Cloud on a shared environment does not change that exemption. Cloud Estate usage remains measured, but exceeding its limits does not stop calls. Builder, QA and Staging, and Production have separate requests-per-minute, concurrent-call and hourly pools. The daily and monthly allowances are shared across the account.

Plan	Requests a minute / calls at once	Units an hour	Units a day	Units a month
Launch	120 / 4	1,200	9,600	150,000
Portfolio	300 / 8	3,000	24,000	500,000
Scale	600 / 16	6,000	80,000	2,000,000
Estate 100	900 / 24	9,000	200,000	5,000,000
Estate 250	1,500 / 32	15,000	400,000	10,000,000
Estate 1000	3,000 / 50	30,000	800,000	20,000,000
Estate 2000	6,000 / 75	60,000	1,600,000	40,000,000

Requests-per-minute, concurrent-call and hourly limits apply separately to each environment group. Daily and monthly limits apply across all authorised libraries and environments on the account. Active Cloud trials and Cloud accounts without a plan use Launch limits.

Unit classes

Class	Units	Typical operations
Standard	1	Single metadata, summary, permission or status reads; deployment and export polling; Darcy calls
Data or change	5	Lists, searches, pages up to 100 records, full service reads and ordinary changes
Bulk	25	Pages over 100 records, full-definition saves, bulk changes, import/export work and roster operations

When units are used

A REST call uses monthly units only when it completes with a 2xx response, including an accepted 202 job. A successful MCP tool result is charged before it is returned. Validation errors, redirects, HTTP errors, MCP errors and aborted responses do not use monthly units, although authenticated attempts still count towards operational request limits.

Response headers

Header	Meaning
`Govforms-API-Units-Used`	Units used by this successful call
`Govforms-API-Units-Remaining`	Units left in the current UTC month
`Govforms-API-Units-Limit`	The account's monthly allowance, including purchased capacity
`Govforms-API-Units-Reset`	The next UTC monthly reset time

Limit errors

A limited request returns 429 with limit, remaining, resetAt and retryAfterSeconds. The Retry-After header identifies the earliest retry time. Error codes are API_RATE_LIMITED, API_CONCURRENCY_LIMITED, API_HOURLY_LIMITED, API_DAILY_LIMITED and API_MONTHLY_QUOTA_EXCEEDED.

If capacity cannot be checked, REST returns 503 API_ADMISSION_UNAVAILABLE with retryAfterSeconds and Retry-After. This is different from exceeding an allowance.

Additional capacity

Add 100,000 API units to the whole account for $33, €30 or £25 a month, excluding tax. Capacity is prepaid, renews monthly and does not roll over. Govform does not automatically charge for overage.

Legacy billing transaction totals

GET /api/billing-transactions/{libraryId}/{serviceId} retrieves legacy service transaction totals. The API key needs apiGetBillingTransactions. The response includes numTransactions and numPages. An optional period in YYYYMM form adds that period and numFormDatasAsOfPeriodEnd; optional billingStartDate and billingEndDate narrow that period. This existing compatibility endpoint has a 1-unit class where Cloud metering applies; Government Cloud calls are exempt.

Getting started

Before you can use Govform API, you need to create an API key. Govform API keys are specific to each Govform library, meaning you can use the key you create for a library to work with any service in that library. If your application needs to work with more than one library, create and use a separate key for each one.

Your application will make HTTPS REST/JSON calls to Govform API endpoints, and will provide your API key in the HTTP Authorization request header when making these calls.

Authentication headers

Send Authorization: GovformsApiKey <key-id>:<key-secret>, or use HMAC authentication so the secret is not included in each request.

The HMAC header is Authorization: GovformsApiHmac <key-id>:<timestamp>:<signature>. Compute the signature as hexadecimal HMAC-SHA256 using the key secret and the uppercase HTTP method, pathname and Unix timestamp in seconds, separated by newline characters:

GET
/builder/libraries/demo-library/api/forms
<timestamp>

Sign only the pathname, excluding the scheme, host, query string and request body. Timestamps must be within five minutes of the server’s time. The key’s library, endpoint permissions and source-IP restrictions apply to both authentication forms. OAuth MCP uses its bearer token instead.

Managing your API keys

Govform API keys provide access for your application to data from all services within a library. To manage API keys for a library, from the Home page select your library, then select the Govform API tab:

Creating an API key presents a new potential attack vector on the services in your library. Before creating a key, be aware of the main security considerations.

Security considerations

As with any application API integration, there are some very important security considerations to be aware of when creating Govform API keys. Without the proper controls being put in place, your key ID and secret value could be used by actors other than your intended application to retrieve potentially sensitive end-user data and/or alter your live services.

To keep your services and customer-submitted data secure:

Store keys in a secrets manager. Never send secrets by email or chat, commit them to a repository, or keep them in ordinary cloud storage or file shares.
Restrict source networks. Add the exact IPv4 or IPv6 addresses, or CIDR ranges, used by the calling application. An allowlist is strongly recommended, particularly for Production access.
Grant only the required endpoint permissions. A data-export process does not need deployment permissions, for example.
Review and rotate keys. Remove unused keys, review their last-used date and network restrictions, and replace any key that may have been compromised.

If a key may have leaked: delete it immediately on the Govform API management page, create a replacement, update the calling application and review recent use.

Permissions

When creating a Govform API key or modifying its settings, you select the endpoints that it is able to be used with. You should select only those endpoints that your application needs to access.

API rate limits

API usage is monitored under the responsible-use terms. Contact Govform support before introducing sustained high-volume polling.

Base URL

This section provides details of the API endpoints your application can call.

Choose the host for the operation. Service discovery, field summaries, full Builder definitions and deployment history use the Builder base URL https://app.govform.com, with paths under /builder/libraries/{libraryId}/api. Use your own Builder URL if your organisation runs a private Builder.

Submitted data, analytics and current deployed-version checks use the relevant service environment’s base URL. For services hosted on Govform Cloud:

QA environment:

https://qa.cloud.govforms.uk

Production environment:

https://cloud.govforms.uk

If your organisation is running its own Govform environments then you can find the QA and Production base URLs for them in the Environments tab of Digital Service Builder.

Errors

All endpoints can return the following errors:

400 Bad Request

{ 
 "error": { 
  "message": "fromDate is mandatory"
 }
}

Example reasons for receiving this error:

Mandatory query parameters not provided
Invalid query parameter values provided

403 Forbidden No body Response bodies vary by API family. Ordinary Builder endpoints return an error.message JSON object; some existing service and compatibility endpoints return no body. Reasons why you might receive this error:

No API key provided in Authorization header.
The API key given is not known to Govform.
The API key given is not for the requested library.
The API key given has not been granted permission to access this endpoint. Check the key's permissions on the Govform API settings page.
The request has been made from an IP address that is not on this API key's IP allowlist. Check which IPs are on the key's IP allowlist on the Govform API settings page. Check the public IP of the infrastructure your application is making the call via. E.g. for AWS or Azure hosted applications this might be the Elastic/Public IP attached to your NAT Gateway, or if your application is hosted on VMs with direct internet access it may be the public IP attached to the VM.
You can contact Govform support for help in diagnosing API authorization issues.

Available endpoints

These pages cover the public Govform API used for data retrieval and deployment automation. MCP endpoints are intentionally not included.

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

Data Rooms

Retained rooms and files have dedicated REST and MCP operations, with Data Rooms consent separate from form designs and Collection programmes. Current casework rights and room assignment still apply. Room changes save immediately in the selected environment; Library settings retain their normal apply/deploy lifecycle. Binary transfer uses authenticated browser or REST streams. See the Data Rooms API.

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.