Create Staged File

Prepares the upload of a file that will later be attached to another Sodtrack resource, such as a dynamic form of a lead.

POST/api/integration/staged-file

Request

cURL

curl -X POST "https://uat.integration.cl.sodtrack-shared.sodtrack.com/api/integration/staged-file" \
  -H "Authorization: Bearer $SODTRACK_TOKEN" \
  -H "origin: <your-origin>"

Base URL: https://uat.integration.cl.sodtrack-shared.sodtrack.com · other environments

Headers

Name	Type	Description
`origin`	string	—

Responses

Create Staged File

{
  "reference": "3f2a7c1e-8b4d-4e6a-9c21-5d7f0a1b2c3d",
  "uploadUrl": "https://s3.amazonaws.com/example-bucket",
  "fields": {
    "key": "tmp/staged-file/3f2a7c1e-8b4d-4e6a-9c21-5d7f0a1b2c3d-electricity-bill.pdf",
    "Content-Type": "application/pdf",
    "acl": "bucket-owner-full-control",
    "bucket": "example-bucket",
    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
    "X-Amz-Credential": "EXAMPLECREDENTIAL/20261110/us-east-1/s3/aws4_request",
    "X-Amz-Date": "20261110T150000Z",
    "Policy": "eyJleHBpcmF0aW9uIjoiZXhhbXBsZSJ9",
    "X-Amz-Signature": "examplesignature"
  },
  "maxSizeBytes": 10485760,
  "uploadExpiresAt": "2026-11-10T15:15:00.000Z"
}

Error responses for this endpoint follow the shared error reference.

Purpose

Prepares the upload of a file that will later be attached to another Sodtrack resource, such as a dynamic form of a lead.

The file is not sent to this endpoint. Sodtrack returns a presigned upload (uploadUrl and fields) so you can upload the file directly to storage, and a reference that identifies it.

Once the file is uploaded, send the reference as the value of an attachment field in dynamicForms of Create Lead or Cancel Lead. Other endpoints do not resolve the reference and store it as plain text.

Field Definitions

📦 Request Data

Field	Type	Required	Description
`purpose`	`string`	✅	What the file will be attached to. One of: `"dynamic_form_attachment"` (an attachment field in `dynamicForms` of Create Lead or Cancel Lead).
`fileName`	`string`	✅	Original name of the file, up to 200 characters. Example: `"electricity-bill.pdf"`.
`contentType`	`string`	✅	MIME type of the file. Must exactly match one of the values accepted for the `purpose` (see Accepted files in Business Rules).

Example Request

json

{
  "purpose": "dynamic_form_attachment",
  "fileName": "electricity-bill.pdf",
  "contentType": "application/pdf"
}

Response Example

Status: 201 Created

json

{
  "reference": "3f2a7c1e-8b4d-4e6a-9c21-5d7f0a1b2c3d",
  "uploadUrl": "https://s3.amazonaws.com/example-bucket",
  "fields": {
    "key": "tmp/staged-file/3f2a7c1e-8b4d-4e6a-9c21-5d7f0a1b2c3d-electricity-bill.pdf",
    "Content-Type": "application/pdf",
    "acl": "bucket-owner-full-control",
    "bucket": "example-bucket",
    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
    "X-Amz-Credential": "EXAMPLECREDENTIAL/20261110/us-east-1/s3/aws4_request",
    "X-Amz-Date": "20261110T150000Z",
    "Policy": "eyJleHBpcmF0aW9uIjoiZXhhbXBsZSJ9",
    "X-Amz-Signature": "examplesignature"
  },
  "maxSizeBytes": 10485760,
  "uploadExpiresAt": "2026-11-10T15:15:00.000Z"
}

Response Fields

Field	Type	Description
`reference`	`string`	Identifier of the file. Send it in an attachment field of `dynamicForms` in Create Lead or Cancel Lead once the file is uploaded. Valid for 24 hours, single use.
`uploadUrl`	`string`	URL to upload the file to, with a `multipart/form-data` POST.
`fields`	`object`	Form fields to send, unchanged, along with the file. Treat its content as opaque: the set of entries can vary.
`maxSizeBytes`	`number`	Largest file size accepted, in bytes.
`uploadExpiresAt`	`string`	ISO 8601 date (UTC). The upload must start before this moment.

Uploading the file

Send a multipart/form-data POST to uploadUrl, with every entry of fields first and the file last, in a part named file. This request goes directly to storage and does not take your Sodtrack API key.

bash

curl -X POST "https://s3.amazonaws.com/example-bucket" \
  -F "key=tmp/staged-file/3f2a7c1e-8b4d-4e6a-9c21-5d7f0a1b2c3d-electricity-bill.pdf" \
  -F "Content-Type=application/pdf" \
  -F "acl=bucket-owner-full-control" \
  -F "bucket=example-bucket" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Credential=EXAMPLECREDENTIAL/20261110/us-east-1/s3/aws4_request" \
  -F "X-Amz-Date=20261110T150000Z" \
  -F "Policy=eyJleHBpcmF0aW9uIjoiZXhhbXBsZSJ9" \
  -F "X-Amz-Signature=examplesignature" \
  -F "file=@electricity-bill.pdf"

A successful upload returns 204 No Content. Errors in this step are returned by the storage service, not by Sodtrack.

Error Responses

HTTP Status	Error	Description
`400 Bad Request`	`UNSUPPORTED_STAGED_FILE_CONTENT_TYPE`	`contentType` is not accepted for the given `purpose`.
`400 Bad Request`	`InvalidParameters`	One or more required fields are missing or invalid (for example, an unknown `purpose` or a `fileName` longer than 200 characters).
`401 Unauthorized`	—	Authentication token missing or expired.
`403 Forbidden`	—	The API key or origin is not authorized.
`500 Internal Server Error`	—	Unexpected server error. Contact Sodtrack support.

Business Rules & Constraints

Accepted files

For dynamic_form_attachment:

Kind	`contentType`
JPEG image	`image/jpeg`
PNG image	`image/png`
HEIC image	`image/heic`
HEIF image	`image/heif`
WebP image	`image/webp`
GIF image	`image/gif`
PDF	`application/pdf`
Word (.doc)	`application/msword`
Word (.docx)	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel (.xls)	`application/vnd.ms-excel`
Excel (.xlsx)	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`

The file must be at least 1 byte and no larger than maxSizeBytes (10 MB for dynamic_form_attachment). Larger or empty files are rejected by storage during the upload.

Time limits

Item	Limit	When it is exceeded
Upload (`uploadUrl` and `fields`)	15 minutes from this response (`uploadExpiresAt`).	The upload is rejected. Call this endpoint again to get a new upload and a new `reference`.
`reference`	24 hours from this response.	The reference is no longer accepted. Call this endpoint again and upload the file again.

Using the reference

Each call returns a new reference, and each reference identifies one file.
A reference can be used once. Once a resource has been created with it, it cannot be used again.
A dynamic_form_attachment reference is only resolved by Create Lead and Cancel Lead. Other endpoints do not resolve it and store it as plain text.
Upload the file before sending the reference. The resource that receives it rejects a reference whose file was never uploaded.