Attachments API: Upload and Manage Files

The Attachments API lets you associate files with invoices, bank movements, and general ledger entries. Every host follows the same two-phase upload pattern: request a presigned upload URL, PUT the file from your client, then confirm the upload so the record is created. You can list attachments, fetch a temporary download URL, and remove an attachment when it is no longer needed. All three hosts share the same five endpoints. Replace the host path segment with the resource you are targeting.

Open in the app. This resource has a page in the Sintropix web app at https://app.sintropix.com/{entityId}/invoices?open={invoiceId}, where each id in braces is the same UUID as in the API route or response. Attachments appear inside the Invoice panel. Use /{entityId}/bills?open={invoiceId} when the Invoice direction is payable. When you mention a record to a user, include that link. See Link to the App for the full URL grammar.

Supported hosts

Host	Base path
Invoice	`POST /api/entities/:entityId/invoices/:invoiceId/attachments`
Bank movement	`POST /api/entities/:entityId/bank-movements/:movementId/attachments`
Ledger entry	`POST /api/entities/:entityId/ledger/entries/:entryId/attachments`

Two-phase upload flow

Presign: POST …/presign with the file metadata. The server returns an attachmentId and a signed url.
Upload: PUT the file bytes to the signed URL from your client (not through the ERP API).
Confirm: POST …/confirm with the attachmentId and display filename. The server checks the uploaded object’s content type and size against what was declared and creates the attachment record.

Accepted content types: application/pdf, image/png, image/jpeg, application/xml, text/xml, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. Maximum file size is 25 MB.

Presign an upload

Request a presigned upload URL and an attachment ID before uploading file bytes. POST /api/entities/:entityId/invoices/:invoiceId/attachments/presign

Path parameters

Parameter	Type	Description
`entityId`	UUID	Entity that owns the parent resource.
`invoiceId`	UUID	Parent invoice (or `movementId` / `entryId` for other hosts).

Body parameters

Parameter	Type	Description
`filename`	string	Display filename for the attachment. Required, minimum 1 character.
`contentType`	enum	One of the accepted MIME types listed above.
`byteSize`	integer	File size in bytes. Must be positive and at most 25 MB.

Response

Field	Type	Description
`attachmentId`	UUID	Identifier to pass to the confirm step.
`url`	URL	Presigned URL to `PUT` the file bytes to. Send the same `Content-Type` you declared. The URL expires after a short window.

{
  "attachmentId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
  "url": "https://storage.example.com/entity/3f2c9a1e-7b4d-4c8e-9f0a-2b6d8e1c4a57/0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b?X-Amz-Algorithm=..."
}

Example

curl -X POST "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/$INVOICE_ID/attachments/presign" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SINTROPIX_API_KEY" \
  -d '{
    "filename": "invoice-001.pdf",
    "contentType": "application/pdf",
    "byteSize": 142000
  }'

Confirm an upload

After PUTting the file to the presigned URL, confirm the upload to create the attachment record and link it to the host resource. POST /api/entities/:entityId/invoices/:invoiceId/attachments/confirm

Path parameters

Parameter	Type	Description
`entityId`	UUID	Entity that owns the parent resource.
`invoiceId`	UUID	Parent invoice (or `movementId` / `entryId` for other hosts).

Body parameters

Parameter	Type	Description
`attachmentId`	UUID	The ID returned by the presign step.
`filename`	string	Display filename. Required, minimum 1 character.

Response

Returns the attachment record.

Field	Type	Description
`id`	UUID	Attachment id. Same value as the `attachmentId` from presign.
`entityId`	UUID	Entity that owns the attachment.
`filename`	string	Display filename.
`contentType`	enum	One of the accepted MIME types listed above, as read from the stored object.
`byteSize`	integer	File size in bytes, as read from the stored object.
`createdAt`	ISO datetime	When the record was created.
`updatedAt`	ISO datetime	When the record was last updated.

{
  "id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
  "entityId": "3f2c9a1e-7b4d-4c8e-9f0a-2b6d8e1c4a57",
  "filename": "invoice-001.pdf",
  "contentType": "application/pdf",
  "byteSize": 142000,
  "createdAt": "2025-01-15T09:23:00.000Z",
  "updatedAt": "2025-01-15T09:23:00.000Z"
}

Example

curl -X POST "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/$INVOICE_ID/attachments/confirm" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SINTROPIX_API_KEY" \
  -H "x-audit-actor: my-agent" \
  -d '{
    "attachmentId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
    "filename": "invoice-001.pdf"
  }'

List attachments

Retrieve all attachments linked to a host resource. GET /api/entities/:entityId/invoices/:invoiceId/attachments

Path parameters

Parameter	Type	Description
`entityId`	UUID	Entity that owns the parent resource.
`invoiceId`	UUID	Parent invoice (or `movementId` / `entryId` for other hosts).

Response

Returns an array of attachment records, each with the same fields as the confirm response (id, entityId, filename, contentType, byteSize, createdAt, updatedAt).

Example

curl "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/$INVOICE_ID/attachments" \
  -H "x-api-key: $SINTROPIX_API_KEY"

Get a download URL

Generate a temporary signed URL to download a specific attachment. GET /api/entities/:entityId/invoices/:invoiceId/attachments/:attachmentId/url

Path parameters

Parameter	Type	Description
`entityId`	UUID	Entity that owns the parent resource.
`invoiceId`	UUID	Parent invoice (or `movementId` / `entryId` for other hosts).
`attachmentId`	UUID	Attachment to retrieve.

Response

Field	Type	Description
`url`	URL	Temporary signed download link. Fetch it with a plain `GET`; no Sintropix credential is needed. The URL expires after a short window, so request a fresh one rather than storing it.

{
  "url": "https://storage.example.com/entity/3f2c9a1e-7b4d-4c8e-9f0a-2b6d8e1c4a57/0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b?X-Amz-Algorithm=..."
}

Example

curl "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/$INVOICE_ID/attachments/$ATTACHMENT_ID/url" \
  -H "x-api-key: $SINTROPIX_API_KEY"

Delete an attachment

Remove an attachment and its link to the host resource. The response has no body. DELETE /api/entities/:entityId/invoices/:invoiceId/attachments/:attachmentId

Path parameters

Parameter	Type	Description
`entityId`	UUID	Entity that owns the parent resource.
`invoiceId`	UUID	Parent invoice (or `movementId` / `entryId` for other hosts).
`attachmentId`	UUID	Attachment to delete.

Response

204 No Content

Example

curl -X DELETE "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/$INVOICE_ID/attachments/$ATTACHMENT_ID" \
  -H "x-api-key: $SINTROPIX_API_KEY" \
  -H "x-audit-actor: my-agent"

Response schemas

Shape	Description
Presign result	`{ attachmentId: UUID, url: URL }`. Returned by `POST …/presign`.
Attachment record	`{ id, entityId, filename, contentType, byteSize, createdAt, updatedAt }`. Returned by `POST …/confirm` and, as an array, by `GET …/attachments`. The internal storage key is never exposed.
Download URL	`{ url: URL }`. Returned by `GET …/:attachmentId/url`.

Status codes

Code	Meaning
`200`	Success (GET list, GET url).
`201`	Success (POST presign, POST confirm).
`204`	Success, no content (DELETE).
`400`	Validation error on request body or path parameter, or on confirm the uploaded object’s content type is missing or not accepted, or its size is empty or over 25 MB.
`401`	Unauthenticated.
`403`	Your Role in the Entity’s Organization doesn’t allow this action (`PERMISSION_DENIED_ERROR`).
`404`	Entity, host resource, or attachment not found, or the Entity is outside your Organizations.
`409`	Attachment already exists, or no file was uploaded to the presigned URL before confirm.
`429`	Rate limit exceeded (25,000 requests per hour per API key).

Error codes

Attachment domain errors carry a code and a params object in the body.

Status	`code`	`params`	When
`400`	`ATTACHMENT_CONTENT_TYPE_NOT_FOUND_ERROR`	`{ attachmentId }`	The uploaded object has no content type.
`400`	`ATTACHMENT_CONTENT_TYPE_NOT_SUPPORTED_ERROR`	`{ attachmentId, contentType }`	The uploaded object’s content type isn’t one of the accepted types.
`400`	`ATTACHMENT_BYTE_SIZE_EMPTY_ERROR`	`{ attachmentId }`	The uploaded object is empty.
`400`	`ATTACHMENT_BYTE_SIZE_TOO_LARGE_ERROR`	`{ attachmentId, byteSize, maxByteSize }`	The uploaded object is larger than 25 MB.
`404`	`ATTACHMENT_HOST_NOT_FOUND_ERROR`	`{ hostKind, hostId }`	The host resource doesn’t exist in the Entity. `hostKind` is `invoices`, `bank-movements`, or `ledger/entries`.
`404`	`ATTACHMENT_NOT_FOUND_ERROR`	`{ attachmentId }`	No attachment with that id is linked to the host.
`409`	`ATTACHMENT_UPLOAD_NOT_FOUND_ERROR`	`{ attachmentId }`	Confirm found no uploaded file for that `attachmentId`.
`409`	`ATTACHMENT_ALREADY_EXISTS_ERROR`	`{ attachmentId }`	The attachment was already confirmed. A file backs at most one host.

Get Started

Ledger

Banking

Documents

Reports & Audit

Sources & Integrations

Platform

Attachments API: Upload and Manage Files

Supported hosts

Two-phase upload flow

Presign an upload

Path parameters

Body parameters

Response

Example

Confirm an upload

Path parameters

Body parameters

Response

Example

List attachments

Path parameters

Response

Example

Get a download URL

Path parameters

Response

Example

Delete an attachment

Path parameters

Response

Example

Response schemas

Status codes

Error codes

​Supported hosts

​Two-phase upload flow

​Presign an upload

​Path parameters

​Body parameters

​Response

​Example

​Confirm an upload

​Path parameters

​Body parameters

​Response

​Example

​List attachments

​Path parameters

​Response

​Example

​Get a download URL

​Path parameters

​Response

​Example

​Delete an attachment

​Path parameters

​Response

​Example

​Response schemas

​Status codes

​Error codes

Supported hosts

Two-phase upload flow

Presign an upload

Path parameters

Body parameters

Response

Example

Confirm an upload

Path parameters

Body parameters

Response

Example

List attachments

Path parameters

Response

Example

Get a download URL

Path parameters

Response

Example

Delete an attachment

Path parameters

Response

Example

Response schemas

Status codes

Error codes