Using Govforms API

17 Mar 2023
18 Minutes to read

Print
Share
Dark
Light

Using Govforms API

Updated on 17 Mar 2023
18 Minutes to read

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

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.

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, you should ensure that Govforms API keys you create are:

Stored securely and kept secret

Keeping your API keys secret

You must ensure that API keys are stored in an appropriate system designed for the storage of secrets. Examples of this include Hashicorp Vault and Github Actions Secrets. Never send secret keys by email or using messaging apps. Do not store them on your laptop, in standard cloud storage, in a code repository (even if it is private) or in corporate file shares.

Restricted to the specific IP address(es) of the application that will use them

Associating your API keys with specific IP addresses

When creating a Govforms API key, you are required to enter the IP address(es) of the applications that will use it. Limiting access by IP address provides a crucial second layer of protection mitigating the impact of any key leakage incident you may suffer. While this IP allowlist can be disabled, doing so is strongly discouraged for Production environment access.

Limited in terms of their permissions

Restricting permissions

When creating an API key, you should select only those permissions that your application requires, in order to reduce the impact of any potential security incident.

Kept fresh and for active applications only

Checking key usage and age

You should ensure unused keys are removed, and check that every key has appropriate IP restrictions. You may also want to check the age of the key and when it was last used. The Govforms API management page provides this information. You may also want to rotate keys by creating new ones, updating your application and then removing old keys. If you suspect a key may have been comprimised, you should delete the key using the Govforms API management page immediately.

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

During the Govforms Beta period, API usage is unlimited but monitored under responsible use terms. If you want to call API endpoints very frequently, please contact Govforms support.

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 Unauthorized
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.

API endpoint: Fetch submitted form data

Retrieves form data submitted by end-users in a deployed Govforms service.
Submitted data is available for the duration of the user data retention period configured for your service on the Service settings->General settings page.

Data can be returned in JSON or CSV format. If using CSV format, by default the columns returned depend on the fields present in the fetched form data. You can retrieve a fixed set of columns using the csvHeaderFields parameter.

Use the query parameters to filter the results by submission date/time. Results are paginated, meaning the API endpoint will provide the first page of results along with the number of pages. Your application can then call the endpoint again to retrieve subsequent results pages.

URL specification

/api/submitted-data/{libraryId}/{serviceId}

Parameter	Description	Mandatory
libraryId	The ID of the library of the service from which to retrieve submitted data	yes
serviceId	The service ID of the service to retrieve submitted data from	yes

Query parameters

Parameter	Description	Mandatory
format	The output format to use in the response body, set to json or csv	yes
fromDate	The first user form submission date to return data for (inclusive), in the format yyyy-mm-dd	yes
toDate	The last user form submission date to return data for (inclusive), in the format yyyy-mm-dd	yes
hour	Optionally, the hour-of-day of the user form submission date to return data from, a number between 0-23. This can only be included where fromData and toDate are the same. This must be included if toDate is set to the current date. It must be prior to the current hour-of-day if toDate is set to the current date. Include an hour if you want to call this API endpoint multiple times per day to fetch near-real-time data.	no
page	The page of results to fetch. If omitted, page 1 is assumed. The response body will include the number of pages to fetch; if over 1 then the endpoint should be called again with this parameter set to each subsequent page number to retrieve all result pages.	no
submissionRef	If specified, only the data for the specified submission reference will be returned,	no
csvHeader	If format is set to csv, this parameter controls the header row to output. Set to csv to include field names in the header row. Set to fieldIds to include field IDs in the header row. Set to none to not include a header row in the output. Defaults to fieldIds.	no
csvHeaderFields	If format is set to csv, optionally set this to specify which fields should be included in the output, separated by commas. The provided values are compared against the CSV header titles for each field and so depend upon the csvHeader setting. The provided field columns will always be present in the order specified and no additional columns will be added.	no
choiceValues	Specifies whether to output choice labels or IDs as the value for choice components. Set to choiceText to use choice text. Set to choiceId to use choice IDs. Defaults to choiceId.	no
excelMode	If format is set to csv, set this to on to wrap all values that are under 200 characters in ="value" to prevent Excel from attempting to auto-transform numbers and dates. For raw CSV feeds not intended for display in Excel, set to off. Defaults to off.	no

Sending your API key

Your API key is sent in the Authorization header, whose value should be set to:
GovformsApiKey <space> Your key ID <colon> Your key secret value
As shown in the Request headers section below.

Examples

Request headers

Header name	value
Authorization	GovformsApiKey myApiKeyId:Mjg2NDY1M2MtZmE3OC00MzE5LThlYTUtYmJmODE4MDM0NDdiOmQwZjNjMjhhLTY1YzEtNDIxYS1iZjU1LTdkM2VmNzE3MzI1NDo2NjRkNzhhYi1hZjVlLTQ0NGUtYmY2My0xYTVlMTYzMGJlZTI6YzQ1MjNiMDUtYjZkYS00ZWRhLTk5YzQtYTg1ZmZlNTYyNDE5

Request body

https://qa.cloud.govforms.uk/api/submitted-data/demo-library/demo-service-1?format=json&fromDate=2023-03-18&toDate=2023-03-18

Response headers

Header name	value
Content-Type	application/json

Response body

{
  "totalResults": 2,
  "totalResultsPages": 1,
  "resultsPage": 1,
  "results": [
    {
      "userId": "john@govforms.co.uk",
      "submissionId": "426T-HBR7-PMB2",
      "createdTime": "2023-03-18T14:57:04.254+00:00",
      "updatedTime": "2023-03-18T15:02:25.777+00:00",
      "formData": {
        "doYouMeetTheRequirementsForThisForm": "yes",
        "dateOfBirth": {
          "day": "15",
          "month": "05",
          "year": "2001"
        },
        "firstName": "John",
        "gender": "male",
        "lastName": "Hopkins",
        "emailAddress": "john@govforms.co.uk",
        "reEnterEmailAddress": "john@govforms.co.uk"
      }
    }, {
      "userId": "jane@govforms.co.uk",
      "submissionId": "FJEU-R8SN-S2JN",
      "createdTime": "2023-03-18T16:40:54.665+00:00",
      "updatedTime": "2023-03-18T17:19:12.145+00:00",
      "formData": {
        "doYouMeetTheRequirementsForThisForm": "yes",
        "dateOfBirth": {
          "day": "20",
          "month": "03",
          "year": "1964"
        },
        "firstName": "Jane",
        "gender": "female",
        "lastName": "Smith",
        "emailAddress": "jane@govforms.co.uk",
        "reEnterEmailAddress": "jane@govforms.co.uk"
      }
    }
  ]
}

CSV mode example:
Request body

https://qa.cloud.govforms.uk/api/submitted-data/demo-library/demo-service-1?format=csv&fromDate=2023-03-18&toDate=2023-03-18

Response headers

Header name	value
Content-Type	text/csv
Govforms-Total-Results	2
Govforms-Total-Results-Pages	1
Govforms-Results-Page	1

Response body

"_userId","_submissionId","_createdTime","_updatedTime","doYouMeetTheRequirementsForThisForm","dateOfBirth-day","dateOfBirth-month","dateOfBirth-year","firstName","gender","lastName","emailAddress","reEnterEmailAddress"
"john@govforms.co.uk","426T-HBR7-PMB2","2023-03-18T14:57:04.254+00:00","2023-03-18T15:02:25.777+00:00","yes","15","05","2001","John","male","Hopkins","john@govforms.co.uk","john@govforms.co.uk"
"jane@govforms.co.uk","FJEU-R8SN-S2JN","2023-03-18T16:40:54.665+00:00","2023-03-18T17:19:12.145+00:00","yes","20","03","1964","Jane","female","Smith","jane@govforms.co.uk","jane@govforms.co.uk"

API endpoint: Fetch analytics events stream

Retrieves raw analytics events for the given service over the given timeframe. There are several types of analytics event, identified via the type property in each event:

Event type	type property	description
Page view event	pageView	Written on every page hit. Includes properties identifying the page that has been hit.
Journey complete event	isUserComplete	Written when the journey is completed, either because the user has hit an Acknowledgement Page or has completed all tasks on the Task List.
Page action execution event	pageAction	Written when a Page Action is executed. Includes the ID of the action and response code from the action exection.
Field tagging event	taggedFieldsSet	Written when a page is submitted by the user containing data for tagged fields. You can tag fields for analytics data collection using the Analytics tab in Service Settings. The event includes the ID and value of each tagged field that was set by the user on the page.

Data can be returned in JSON or CSV format. The columns in the CSV are fixed; not all values will be set for all events as some columns are specific to one event type.

Use the query parameters to filter the results by event date/time. Results are paginated, meaning the API endpoint will provide the first page of results along with the number of pages. Your application can then call the endpoint again to retrieve subsequent results pages.

URL specification

GET /api/analytics-events/{libraryId}/{serviceId}

Parameter	Description	Mandatory
libraryId	The ID of the library of the service from which to retrieve submitted data	yes
serviceId	The service ID of the service to retrieve submitted data from	yes

Query parameters

Parameter	Description	Mandatory
format	The output format to use in the response body, set to json or csv	yes
fromDate	The first event date to return data for (inclusive), in the format yyyy-mm-dd	yes
toDate	The last event date to return data for (inclusive), in the format yyyy-mm-dd	yes
hour	Optionally, the hour-of-day of the event date to return data from, a number between 0-23. This can only be included where fromData and toDate are the same. This must be included if toDate is set to the current date. It must be prior to the current hour-of-day if toDate is set to the current date. Include an hour if you want to call this API endpoint multiple times per day to fetch near-real-time data.	no
page	The page of results to fetch. If omitted, page 1 is assumed. The response body will include the number of pages to fetch; if over 1 then the endpoint should be called again with this parameter set to each subsequent page number to retrieve all result pages.	no
submissionRef	If specified, only events for the specified submission reference will be returned,	no
csvHeader	If format is set to csv, this parameter controls the header row to output. Set to on to include field names in the header row. Set to none to not include a header row in the output. Defaults to on.	no
csvHeaderFields	If format is set to csv, optionally set this to specify which fields should be included in the output, separated by commas. The provided values are compared against the CSV header titles for each field and so depend upon the csvHeader setting. The provided field columns will always be present in the order specified and no additional columns will be added.	no
excelMode	If format is set to csv, set this to on to wrap all values that are under 200 characters in ="value" to prevent Excel from attempting to auto-transform numbers and dates. For raw CSV feeds not intended for display in Excel, set to off. Defaults to off.	no

Sending your API key

Examples

Request headers

Header name	value
Authorization	GovformsApiKey myApiKeyId:Mjg2NDY1M2MtZmE3OC00MzE5LThlYTUtYmJmODE4MDM0NDdiOmQwZjNjMjhhLTY1YzEtNDIxYS1iZjU1LTdkM2VmNzE3MzI1NDo2NjRkNzhhYi1hZjVlLTQ0NGUtYmY2My0xYTVlMTYzMGJlZTI6YzQ1MjNiMDUtYjZkYS00ZWRhLTk5YzQtYTg1ZmZlNTYyNDE5

Request URL

GET https://qa.cloud.govforms.uk/api/analytics-events/demo-library/demo-service-1?format=json&fromDate=2023-03-18&toDate=2023-03-18

Response headers

Header name	value
Content-Type	application/json

Response body

{
  "totalResults": 2,
  "totalResultsPages": 1,
  "resultsPage": 1,
  "results": [
    {
      "submissionId": "X6GY-FDLJ-P8A2",
      "userId": "anon-ff607409-34f4-4562-8001-acd8de37c1ad",
      "userEmail": null,
      "timestamp": "2023-03-18T14:57:53.256+00:00",
      "type": "pageView",
      "pageId": "bfeee0d9-13ca-4c69-aafc-486d93722bh5",
      "pageIdx": 3,
      "pageTitle": "About you",
      "pageType": "contentPage",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Edg/110.0.1587.41"
    },
    {
      "submissionId": "X6GY-FDLJ-P8A2",
      "userId": "anon-ff607409-34f4-4562-8001-acd8de37c1ad",
      "userEmail": null,
      "timestamp": "2023-03-18T14:58:06.512+00:00",
      "type": "taggedFieldsSet",
      "taggedFieldData": {
        "firstName": "John",
        "gender": "male"
      },
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Edg/110.0.1587.41"
    }
  ]
}

CSV mode example:

Request URL

GET https://qa.cloud.govforms.uk/api/analytics-events/demo-library/demo-service-1?format=csv&fromDate=2023-03-18&toDate=2023-03-18

Response Headers

Header name	value
Content-Type	text/csv
Govforms-Total-Results	2
Govforms-Total-Results-Pages	1
Govforms-Results-Page	1

Response Body

"submissionId","userId","userEmail","timestamp","type","pageId","pageIdx","pageTitle","pageType","userAgent","taggedFieldData-fieldId","taggedFieldData-fieldValue","isUserComplete","actionId","isSuccess","responseCode","fieldFailure-fieldId","fieldFailure-fieldLabel","fieldFailure-iteration","fieldFailure-fieldPartId","fieldFailure-errorMsg","fieldFailure-fieldValue"
"X6GY-FDLJ-P8A2","anon-ff607409-34f4-4562-8001-acd8de37c1ad","","2023-03-18T14:57:53.256+00:00","pageView","bfeee0d9-13ca-4c69-aafc-486d93722bh5","3","About you","contentPage","Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Edg/110.0.1587.41","","","","","","","","","","","",""
"X6GY-FDLJ-P8A2","anon-ff607409-34f4-4562-8001-acd8de37c1ad","","2023-03-18T14:58:06.512+00:00","taggedFieldsSet","","","","","Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Edg/110.0.1587.41","firstName|gender","John|male","","","","","","","","","",""

API endpoint: Fetch journey analytics records

This endpoint fetches analytics data on a per-journey basis. One record is returned per user journey, each of which may or may not yet be complete.

Data can be returned in JSON or CSV format. The columns in the CSV are fixed; not all values will be set for all events as some columns are specific to one event type.

Use the query parameters to filter the results by journey end date/time. Note some journeys span multiple days, and journeys from previous days may change if the user continues them into the next day, thus causing them to appear in the next days journey data. This is more of a concern for large authenticated services supporting save & come back later, than it is for smaller anonymous services that must be completed in one sitting.

Results are paginated, meaning the API endpoint will provide the first page of results along with the number of pages. Your application can then call the endpoint again to retrieve subsequent results pages.

URL specification

GET /api/analytics-journeys/{libraryId}/{serviceId}

Parameter	Description	Mandatory
libraryId	The ID of the library of the service from which to retrieve submitted data	yes
serviceId	The service ID of the service to retrieve submitted data from	yes

Query parameters

Parameter	Description	Mandatory
format	The output format to use in the response body, set to json or csv	yes
fromDate	The first event date to return data for (inclusive), in the format yyyy-mm-dd	yes
toDate	The last event date to return data for (inclusive), in the format yyyy-mm-dd	yes
hour	Optionally, the hour-of-day of the event date to return data from, a number between 0-23. This can only be included where fromData and toDate are the same. This must be included if toDate is set to the current date. It must be prior to the current hour-of-day if toDate is set to the current date. Include an hour if you want to call this API endpoint multiple times per day to fetch near-real-time data.	no
page	The page of results to fetch. If omitted, page 1 is assumed. The response body will include the number of pages to fetch; if over 1 then the endpoint should be called again with this parameter set to each subsequent page number to retrieve all result pages.	no
submissionRef	If specified, only events for the specified submission reference will be returned,	no
csvHeader	If format is set to csv, this parameter controls the header row to output. Set to on to include field names in the header row. Set to none to not include a header row in the output. Defaults to on.	no
csvHeaderFields	If format is set to csv, optionally set this to specify which fields should be included in the output, separated by commas. The provided values are compared against the CSV header titles for each field and so depend upon the csvHeader setting. The provided field columns will always be present in the order specified and no additional columns will be added.	no
excelMode	If format is set to csv, set this to on to wrap all values that are under 200 characters in ="value" to prevent Excel from attempting to auto-transform numbers and dates. For raw CSV feeds not intended for display in Excel, set to off. Defaults to off.	no

Sending your API key

Examples

Request Headers

Header name	value
Authorization	GovformsApiKey myApiKeyId:Mjg2NDY1M2MtZmE3OC00MzE5LThlYTUtYmJmODE4MDM0NDdiOmQwZjNjMjhhLTY1YzEtNDIxYS1iZjU1LTdkM2VmNzE3MzI1NDo2NjRkNzhhYi1hZjVlLTQ0NGUtYmY2My0xYTVlMTYzMGJlZTI6YzQ1MjNiMDUtYjZkYS00ZWRhLTk5YzQtYTg1ZmZlNTYyNDE5

JSON mode example:

Request URL

GET https://qa.cloud.govforms.uk/api/analytics-journeys/demo-library/demo-service-1?format=json&fromDate=2023-03-18&toDate=2023-03-18

Response Headers

Header name	value
Content-Type	application/json

Response body

{
  "totalResults": 1,
  "totalResultsPages": 1,
  "resultsPage": 1,
  "results": [
    {
      "submissionId": "PGEE-EE2H-3Y67",
      "userId": "anon-c2305120-1a15-441d-90a8-b4246a9b8e71",
      "userEmail": null,
      "journeyStart": "2023-03-17T23:57:53.249+00:00",
      "journeyEnd": "2023-03-18T00:02:41.267+00:00",
      "journeyDayOfWeek": 6,
      "timeSpentOnPages": [
        {
          "pageNum": 1,
          "pageName": "About this service",
          "timeSpentSeconds": 0.909
        },
        {
          "pageNum": 2,
          "pageName": "Do you meet the requirements for this form?",
          "timeSpentSeconds": 35.86
        },
        {
          "pageNum": 3,
          "pageName": "You cannot continue if you do not meet the requirements",
          "timeSpentSeconds": 1200
        }
      ],
      "activeTimeInJourneySeconds": 1236.769,
      "isComplete": false,
      "numSuccessPageHits": 4,
      "numErrorPageHits": 0,
      "dropOutPageName": "You cannot continue if you do not meet the requirements",
      "dropOutPageNum": 3,
      "dropOutPageType": "exitPage",
      "validationErrors": [],
      "userAgentDetails": {
        "browser": {
          "name": "Microsoft Edge",
          "version": "110.0.1587.41"
        },
        "os": {
          "name": "Windows",
          "version": "NT 10.0",
          "versionName": "10"
        },
        "platform": {
          "type": "desktop"
        },
        "engine": {
          "name": "Blink"
        }
      },
      "taggedFieldData": {
        "doYouMeetTheRequirementsForThisForm": "No"
      }
    }
  ]
}

CSV mode example:
Request URL

GET https://qa.cloud.govforms.uk/api/analytics-journeys/demo-library/demo-service-1?format=csv&fromDate=2023-03-18&toDate=2023-03-18

Response headers

Header name	value
Content-Type	text/csv
Govforms-Total-Results	1
Govforms-Total-Results-Pages	1
Govforms-Results-Page	1

Response body

"submissionId","userId","userEmail","journeyStart","journeyEnd","journeyDayOfWeek","timeSpentOnPages-pageNum","timeSpentOnPages-pageName","timeSpentOnPages-timeSpentSeconds","activeTimeInJourneySeconds","isComplete","activeTimeInJourneySeconds", "isComplete", "numSuccessPageHits", "numErrorPageHits", "dropOutPageName", "dropOutPageNum", "dropOutPageType","validationErrors-timestamp","validationErrors-pageNum","userAgentDetails-browser-name","userAgentDetails-browser-version","userAgentDetails-os-name","userAgentDetails-os-version","userAgentDetails-os-versionName","userAgentDetails-platform-type","userAgentDetails-engine-name","taggedFieldData-fieldId","taggedFieldData-fieldValue"
"PGEE-EE2H-3Y67","anon-c2305120-1a15-441d-90a8-b4246a9b8e71",null,"2023-03-17T23:57:53.249+00:00","2023-03-18T00:02:41.267+00:00","6","1|2|3","About this service|Do you meet the requirements for this form?|You cannot continue if you do not meet the requirements","0.909|35.86|1200","1236.769","false","1236.769","false","4","0","You cannot continue if you do not meet the requirements","3","exitPage","","","Microsoft Edge","110.0.1587.41","Windows","NT 10.0","10","desktop","Blink","doYouMeetTheRequirementsForThisForm","No"

API endpoint: Trigger service deployment

This endpoint triggers a service deployment. You can specify the version of the service to deploy.

URL specification

PUT /api/service-deployments/{libraryId}/{serviceId}/{version}

Parameter	Description	Mandatory
libraryId	The ID of the library of the service to deploy	yes
serviceId	The service ID of the service to to deploy	yes
version	Provides the version number to deploy. You can find version numbers for your service listed in the Change management page of Digital Service Builder. If set to latest, the latest version is deployed. If set to remove, the service is removed from the environment.	yes

Query parameters

None

Sending your API key

Examples

Request Headers

Header name	value
Authorization	GovformsApiKey myApiKeyId:Mjg2NDY1M2MtZmE3OC00MzE5LThlYTUtYmJmODE4MDM0NDdiOmQwZjNjMjhhLTY1YzEtNDIxYS1iZjU1LTdkM2VmNzE3MzI1NDo2NjRkNzhhYi1hZjVlLTQ0NGUtYmY2My0xYTVlMTYzMGJlZTI6YzQ1MjNiMDUtYjZkYS00ZWRhLTk5YzQtYTg1ZmZlNTYyNDE5

Deploy latest version to QA example

Request URL

PUT https://qa.cloud.govforms.uk/api/service-deployments/demo-library/demo-service-1/latest

Request body
This endpoint does not expect a request body.

Response Headers

Header name	value
Content-Type	application/json

Response body
200 OK

{
  "isDeployed": true,
  "serviceVersion": 125,
  "versionTimestamp": "2023-03-14T10:51:44.288+00:00",
  "lastDeploymentTimestamp": "2023-03-15T15:22:13.552+00:00"
}

Deploy specfied version to Production example

Request URL

PUT https://cloud.govforms.uk/api/service-deployments/demo-library/demo-service-1/125

Request body
This endpoint does not expect a request body.

Response Headers

Header name	value
Content-Type	application/json

Response body
200 OK

{
  "isDeployed": true,
  "serviceVersion": 125,
  "versionTimestamp": "2023-03-14T10:51:44.288+00:00",
  "lastDeploymentTimestamp": "2023-03-15T15:22:13.552+00:00"
}

Remove service from Production example

Request URL

PUT https://cloud.govforms.uk/api/service-deployments/demo-library/demo-service-1/remove

Request body
This endpoint does not expect a request body.

Response Headers

Header name	value
Content-Type	application/json

Response body
200 OK

{
  "isDeployed": false
}

API endpoint: Get deployed service version

This endpoint gets the version and timestamp of the last deployment of a service to an environment.

URL specification

GET /api/service-deployments/{libraryId}/{serviceId}

Parameter	Description	Mandatory
libraryId	The ID of the library of the service to deploy	yes
serviceId	The service ID of the service to to deploy	yes

Query parameters

No query parameters.

Sending your API key

Examples

Request Headers

Header name	value
Authorization	GovformsApiKey myApiKeyId:Mjg2NDY1M2MtZmE3OC00MzE5LThlYTUtYmJmODE4MDM0NDdiOmQwZjNjMjhhLTY1YzEtNDIxYS1iZjU1LTdkM2VmNzE3MzI1NDo2NjRkNzhhYi1hZjVlLTQ0NGUtYmY2My0xYTVlMTYzMGJlZTI6YzQ1MjNiMDUtYjZkYS00ZWRhLTk5YzQtYTg1ZmZlNTYyNDE5

Retrieve deployed service version in QA

Request URL

GET https://qa.cloud.govforms.uk/api/service-deployments/demo-library/demo-service-1

Request body
This endpoint does not expect a request body.

Response Headers

Header name	value
Content-Type	application/json

Response body
200 OK

{
  "isDeployed": true,
  "serviceVersion": 125,
  "versionTimestamp": "2023-03-14T10:51:44.288+00:00",
  "lastDeploymentTimestamp": "2023-03-15T15:22:13.552+00:00"
}

Determine service not deployed in Production

Request URL

GET https://cloud.govforms.uk/api/service-deployments/demo-library/demo-service-1

Request body
This endpoint does not expect a request body.

Response Headers

Header name	value
Content-Type	application/json

Response body
200 OK

{
  "isDeployed": false
}

Was this article helpful?

What's Next

Liquid tags

Table of contents

Getting started
API endpoint: Fetch submitted form data
API endpoint: Fetch analytics events stream
API endpoint: Fetch journey analytics records
API endpoint: Trigger service deployment
API endpoint: Get deployed service version