API units: 5 or 25. A page of up to 100 records uses 5 units. A page over 100 records uses 25 units. The default page size is 1,000, so a request without a page size uses 25 units.

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.

Endpoint and parameters

/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	Restrict the result to one completed hour (0–23). Use only when fromDate and toDate are the same. For today, the hour must be earlier than the current hour. If omitted for today, Govforms returns data only up to the start of the current hour.	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
pageSize	Number of results per page, from 1 to 1000. Defaults to 1000; larger values are capped at 1000.	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

Authentication: send GovformsApiKey <key-id>:<key-secret> in the Authorization header. Substitute credentials from your secrets manager; never copy a live key into documentation, source control or logs.

Examples

Request headers

Header name	value
Authorization	GovformsApiKey <key-id>:<key-secret>

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
Govforms-Total-Results	2
Govforms-Total-Results-Pages	1
Govforms-Results-Page	1

Response body

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

  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

"submissionId","userId","userEmail","createdTime","submittedTime","updatedTime","doYouMeetTheRequirementsForThisForm","dateOfBirth-day","dateOfBirth-month","dateOfBirth-year","firstName","gender","lastName","emailAddress","reEnterEmailAddress"
"426T-HBR7-PMB2","customer.one@example.invalid","customer.one@example.invalid","2023-03-18T14:57:04.254+00:00","2023-03-18T15:02:25.777+00:00","2023-03-18T15:02:25.777+00:00","yes","15","05","2001","John","male","Hopkins","customer.one@example.invalid","customer.one@example.invalid"
"FJEU-R8SN-S2JN","customer.two@example.invalid","customer.two@example.invalid","2023-03-18T16:40:54.665+00:00","2023-03-18T17:19:12.145+00:00","2023-03-18T17:19:12.145+00:00","yes","20","03","1964","Jane","female","Smith","customer.two@example.invalid","customer.two@example.invalid"

     

---

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