Govforms API
Govforms provides API endpoints that can be called by applications owned by your organisation to fetch customer-submitted data and control your services.
Note this is different from where you want a page in a Govforms service to call out to an API during the customer journey. To do that, use API Actions, found under Page Actions.
API units: Every 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 Business Cloud account's API allowance. 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 trials and 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.
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. Govforms does not automatically charge for overage.
Getting started
Before you can use Govforms API, you need to create an API key. Govforms API keys are specific to each Govforms 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 Govforms API endpoints, and will provide your API key in the HTTP Authorization request header when making these calls.
Managing your API keys
Govforms 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 Govforms 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 Govforms 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 Govforms API management page, create a replacement, update the calling application and review recent use.
Permissions
When creating a Govforms 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 Govforms support before introducing sustained high-volume polling.
Base URL
This section provides details of the API endpoints your application can call.
API endpoints are hosted at the URLs listed below under your environment's base URL. For services hosted on Govforms Cloud, the base URL is:
QA environment:
https://qa.cloud.govforms.uk
Production environment:
https://cloud.govforms.uk
If your organisation is running its own Govforms 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 For security reasons no detail is provided in the 403 error response. Reasons why you might receive this error:
- No API key provided in Authorization header.
- The API key given is not known to Govforms.
- 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 Govforms 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 Govforms 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 Govforms support for help in diagnosing API authorization issues.
Available endpoints
- Fetch submitted form data
- Fetch analytics events
- Fetch journey analytics records
- Trigger a service deployment
- Get the deployed service version
- Delete submitted form data
- List and download uploaded files and signatures
- Set submitted form status
These pages cover the public Govforms 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