# Fetch submitted form data Source: https://govform.com/resources/documentation/article/33-01-api-fetch-submitted-form-data Topic: Govform API & MCP Need the Service ID? Use the [Builder service directory and field-schema endpoints]() first. Pass the Service ID without the library prefix when retrieving submitted data. **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 Govform 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, Govform 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 :` 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 : | 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]()