API – Download a Form Submission Attachment

Download a file attached to a form submission by its ID.

---

Endpoint

GET  https://api.headlessforms.cloud/api/v1/form/{FORM_TOKEN}/attachments/{ATTACHMENT_ID}
HEAD https://api.headlessforms.cloud/api/v1/form/{FORM_TOKEN}/attachments/{ATTACHMENT_ID}

Note:

• GET returns the binary file stream.
• HEAD returns headers only (no body), useful for checking existence, size, or MIME‑type.

---

Path Parameters

Name	Type	Description
FORM_TOKEN	string	Required. Your form’s unique token.
ATTACHMENT_ID	string	Required. The ID of the attachment to download.

---

Query Parameters

Name	Type	Description
api_token	string	Required. Your API access token. Create/manage tokens in your profile.

---

Request Headers

Header	Value	Description
Accept	*/*	Allow any content type for file download.
Authorization	Bearer {API_TOKEN}	(Optional) Pass your API token in the header.

Tip: You can pass api_token either as a query parameter or in the Authorization header.

---

Successful Response (200)

• Content‑Type: <attachment‑mime‑type> (e.g. application/pdf, image/png)
• Content‑Disposition: attachment; filename="{original_filename}"

The raw bytes of the file will be streamed back. Your HTTP client or browser will trigger a download dialog.

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice_1234.pdf"

(binary data…)

---

Error Responses

401 Unauthorized

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "message": "Unauthenticated." }

Occurs when your api_token is missing or invalid.

403 Forbidden

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "message": null,
  "data": [],
  "error": "You do not have permission to access this resource."
}

Occurs when the token is valid but lacks permission for this form or attachment.

404 Not Found

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "status": 404,
  "error": "Attachment not found",
  "message": "Error",
  "data": []
}

Occurs when the form or the attachment ID does not exist.

---

Example: cURL

Download the file:

curl -L \
  -X GET "https://api.headlessforms.cloud/api/v1/form/{FORM_TOKEN}/attachments/{ATTACHMENT_ID}?api_token=YOUR_API_TOKEN" \
  -H "Accept: */*"

Retrieve headers only (check existence/MIME):

curl -I \
  -X HEAD "https://api.headlessforms.cloud/api/v1/form/{FORM_TOKEN}/attachments/{ATTACHMENT_ID}?api_token=YOUR_API_TOKEN"

---

Notes

• Large files are streamed directly—no memory buffering needed.

• You can also authenticate via header:

  Authorization: Bearer {API_TOKEN}

• Ensure FORM_TOKEN and ATTACHMENT_ID are URL‑encoded if they contain special characters.