Upload File

Upload a file for a file upload, signature, or video and audio question with POST /v2/admin/forms/{formId}/uploads, then reference its fileId in a response.

Answers to File Upload, Signature, and Video / Audio questions do not carry the file itself. They carry a fileId. Getting one takes two steps:

Upload each file to this endpoint. It returns a fileId.
Put the fileId in the answer when you call Submit Response.

POSThttps://api.encatch.com/engage-product/encatch/api/v2/admin/forms/%7BformId%7D/uploads

This endpoint is listed in a form's OpenAPI document only when the form has a question that takes files.

Authentication

X-Api-KeystringRequired

Admin (secret) API key

Content-TypestringRequired

Multipart body with a boundary. Most HTTP clients set this header for you when you send form data.

multipart/form-data

Request body

A multipart/form-data body with these parts. Any other part returns 400 unsupported_field.

questionIdstringRequired

The UUID of a file upload, signature, or video and audio question on the form's live version. Slugs are not accepted here.

filefileRequired

The file. It must be one of the question's allowed file types and within its maximum file size.

formIdstring

Optional. Must match the formId in the path.

Examples

cURL

curl -X POST 'https://api.encatch.com/engage-product/encatch/api/v2/admin/forms/3f8a2c1e-7b4d-4e9a-9c61-2d5f8e0b7a14/uploads' \
  -H 'X-Api-Key: YOUR_ADMIN_API_KEY' \
  -F 'questionId=01a1443e-d8bf-799f-addc-ce93151d3281' \
  -F 'file=@receipt.pdf'

Success response

201Response

{
  "fileId": "c2a7e1f4-5b3d-4a9e-8f61-0d2b7c9e4a18",
  "fileUrl": "https://<storage-host>/<path>/receipt.pdf",
  "fileName": "receipt.pdf",
  "mimeType": "application/pdf",
  "fileSizeMb": 0.42,
  "expiresAt": "2026-10-20T07:06:00Z"
}

fileIdstringRequired

UUID to use in one answer before expiresAt.

fileUrlstringRequired

Location of the stored file.

fileNamestringRequired

File name as uploaded.

mimeTypestringRequired

Detected media type.

fileSizeMbnumberRequired

File size in MB.

expiresAtstringRequired

The fileId must be used in a response before this time (24 hours after upload).

Use the fileId in a response

Submit body

{
  "status": "completed",
  "answers": {
    "attach-your-receipt": [
      { "fileId": "c2a7e1f4-5b3d-4a9e-8f61-0d2b7c9e4a18" }
    ]
  }
}

Question type	Answer value
File Upload	Array of `{ "fileId" }`, up to the question's maximum number of files
Signature	`{ "mode": "draw", "fileId" }` or `{ "mode": "upload", "fileId" }`; a typed signature needs no upload: `{ "mode": "type", "typedName" }`
Video / Audio	`{ "mode": "video" \| "audio" \| "photo", "fileId", "durationSeconds"? }`; a text answer needs no upload: `{ "mode": "text", "text" }`

Rules for file answers:

A fileId works only for the question it was uploaded for.
A fileId can be used in one response only (file_already_used).
A fileId expires 24 hours after upload (file_not_found).
The file's type must match the answer's mode, and the mode must be on for the question (mode_not_allowed).
Listing the same fileId twice returns duplicate_file. Sending more files than the question allows returns too_many_files.

See Answer formats for details.

Errors

Status	When
`400`	Not multipart, no boundary, or a missing part (`malformed_body`); an unknown part (`unsupported_field`); or `formId` differs from the path (`form_id_mismatch`)
`401`	Missing or unknown API key (gateway, no `code`)
`403`	Not an admin key (gateway, no `code`)
`404`	No form with this `formId` (`form_not_found`)
`413`	Larger than the question allows, or than the upload limit (`file_too_large`)
`415`	Not one of the question's file types (`file_type_not_allowed`)
`422`	`questionId` is not a UUID, is not on this form, or is not a file, signature, or video question (`invalid_question`); or the form cannot take a response now (`form_not_live`, `api_channel_disabled`, `outside_schedule`, `response_limit_reached`, `usage_quota_exceeded`)
`429`	Admin API rate limit reached
`503`	File storage temporarily unavailable (`temporarily_unavailable`); retry later