# Govform API Source: https://govform.com/resources/documentation/article/33-govforms-api Topic: Govform API & MCP 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 :`, or use HMAC authentication so the secret is not included in each request. The HMAC header is `Authorization: GovformsApiHmac ::`. 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 ``` 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 - [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 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.