API units: 25. Each successful list or download request uses 25 units.

Use these endpoints to retrieve uploaded files and drawn signature images from a completed submission. They support single-file fields, multiple-file fields and files inside repeating groups.

Before you start

The API key must have the Fetch submitted data permission. Both GovformsApiKey and GovformsApiHmac authentication are supported. Files remain available only while the completed submission, deployed service definition and stored file are retained.

List uploaded files and signatures

GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/files

No date filters or user ID are required. The response is built from the saved submission and does not contact file storage.

{
  "submissionId": "324H-LWDN-BE7D",
  "files": [
    {
      "fieldId": "enclosureUpload",
      "fileIndex": 0,
      "fileName": "teams.jpg",
      "mimeType": "image/jpeg",
      "extension": "jpg",
      "size": "143608",
      "downloadUrl": "/api/submitted-data/nhslanarkshire/staff-engagement-form--employee/324H-LWDN-BE7D/files/enclosureUpload?fileIndex=0"
    }
  ]
}

Each entry contains the field ID, zero-based file index, saved filename, type and size metadata, and an authenticated root-relative download URL. Files in a repeating group also include a zero-based iteration. A submission with no uploaded files or drawn signatures returns an empty files array.

Resolve each downloadUrl against the same environment base URL and include an Authorization header on the download request. If using HMAC, sign the download request path using the existing authentication scheme. These are Govforms API links, not public links or browser-session links.

Download one file

GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/files/{fieldId}?fileIndex={fileIndex}&iteration={iteration}

fileIndex and iteration are zero-based integers. A multiple-file field requires fileIndex, and a repeating field requires iteration. For a non-repeating single-file field, omit both selectors or use fileIndex=0.

A drawn signature appears in the list as signature.png with image/png content type. Download it using its downloadUrl and the same Authorization header. A typed signature has no image and is not listed. For a non-repeating signature, omit both selectors or use fileIndex=0; a signature inside a repeating group also needs its iteration.

Use the list response rather than constructing selectors from filenames. Re-list files after a submission changes because positions represent the currently saved answers.

Download response

A successful request streams the original bytes as an attachment. The response includes the original filename in Content-Disposition, the file content type, Content-Length when known, and Cache-Control: no-store.

Govforms does not apply a file-size ceiling to these downloads. Clients should stream the response to a file or processor instead of buffering it in memory. Hosting and network transfer limits can still apply. Interrupted transfers restart from the beginning; byte-range resume and ZIP downloads are not supported.

Errors

Status	Reason
400	A selector is malformed, or a required file index or repeat iteration is missing.
403	The key is invalid, belongs to another library, lacks the submitted-data permission or is used from a disallowed network.
404	The completed submission, field, selected file or stored file is unavailable.
429	An API capacity limit has been reached.

Existing submitted-data responses

The existing Submitted Data JSON and CSV formats are unchanged. In particular, a saved upload can still have an empty downloadUrl when Govforms internal storage is used. A signature’s signatureImageFileId is a storage reference, and its signatureImageDataUrl can be empty. Use the authenticated URLs returned by this listing endpoint to retrieve file bytes.

The listing contains metadata only, not Base64 file contents. Generated PDFs, document fields, ZIP downloads and byte-range resume are outside the scope of these endpoints.

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