Documents attached to Kontier records: upload in two steps (start, then confirm), share with the customer or not, get a download link, delete.
Start a file upload
Registers the document and returns a URL to upload its bytes to, valid for 15 minutes. Call the confirm endpoint afterwards: until you do, the document is not visible anywhere, because the server has not yet checked that the bytes match what you declared. An upload that is never confirmed is discarded automatically after an hour. The answer is the file itself plus upload_url and expires_at; the nested file repeats it and is removed on 2026-11-30.
Required scope: org.read (Read organization profile).
query Parameters
includeExtra data to add to the response: has_signing_fields, origin. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Start a file upload › Request Body
categoryWhat the document is. Decides the size cap and the accepted formats.
declared_content_typeThe format you believe the file is. The server checks the file's actual bytes when you confirm the upload, and rejects a file that disagrees.
declared_sizeThe file's size in bytes. Checked against the limit for this category before the upload starts, and again against the real size afterwards.
filenameThe file's name, shown in lists.
owner_idThe owning record's UUID.
owner_kindWhat this document hangs off.
visibilityDefaults to internal. Set shared to also show the document to the customer.
Start a file upload › Responses
OK
Get a file
Returns one document: the same shape as in its record's list and as every write on it answers. A deleted document is not found. An upload that is still pending or was refused is returned with its status.
Required scope: org.read (Read organization profile).
path Parameters
idFile UUID
query Parameters
includeExtra data to add to the response: has_signing_fields, origin. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a file › Responses
OK
Delete a file
Removes the document immediately from every list and revokes any download link. The stored bytes are erased shortly afterwards.
Required scope: org.read (Read organization profile).
path Parameters
idFile UUID
query Parameters
reasonOptional note recorded with the deletion.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete a file › Responses
No Content
Change whether a file is shared, or what it is
Sets the visibility, the category, or both (the category first). The name and the record a document belongs to are fixed when it is uploaded. The category changes only on a document an operator uploaded, shared or not, while it is neither prepared for signature nor part of a signature request, to a category its record offers and its file fits; otherwise 409 (or 400 for a category the record does not offer or the file does not fit). The change is recorded in the audit log.
Required scope: org.read (Read organization profile).
path Parameters
idFile UUID
query Parameters
includeExtra data to add to the response: has_signing_fields, origin. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Change whether a file is shared, or what it is › Request Body
categoryWhat the document is. Changes only on a document you uploaded, shared or not, while no signing step holds it, to a type its record offers and its file fits.
visibilityinternal keeps the document on the operator surfaces; shared also shows it to the customer.
Change whether a file is shared, or what it is › Responses
OK
Confirm an uploaded file
Checks the uploaded bytes — their size, their real format and their checksum — and makes the document available. Returns 422 when the file is not what was declared or is not an accepted format for its category; the document is then held aside rather than published, and cannot be downloaded.
Required scope: org.read (Read organization profile).
path Parameters
idFile UUID
query Parameters
includeExtra data to add to the response: has_signing_fields, origin. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Confirm an uploaded file › Responses
OK
Download a file's bytes
Streams the file's bytes through the API, with the same access as the download link. For a page that reads the bytes itself, such as a PDF viewer. Only available once the upload has been confirmed.
Required scope: org.read (Read organization profile).
path Parameters
idFile UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Download a file's bytes › Responses
The file's bytes
Get the signature fields placed on a document
For a PDF a quote shares with its buyer. Measures every page from the stored file and returns the fields placed so far (none before the first save). Returns 422 SIGNING_LAYOUT_UNSUPPORTED_PDF with a reason when the PDF cannot be signed: rotated, encrypted, form fields, already signed, too large, too many pages, a non-standard unit size, or unreadable.
Required scope: org.read (Read organization profile).
path Parameters
idFile UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get the signature fields placed on a document › Responses
OK
Save the signature fields placed on a document
Replaces the whole field list. Boxes are moved into the visible page; a box smaller than its kind's minimum is refused. A layout with at least one field makes the document one the buyer signs with the quote: it is added to the quote's PDF when the quote is sent. Send back the updated_at you read; a layout saved by somebody else since answers 409. A sent quote's layouts cannot change (409 SIGNING_LAYOUT_LOCKED).
Required scope: org.read (Read organization profile).
path Parameters
idFile UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Save the signature fields placed on a document › Request Body
The whole field list; it replaces the saved one.
updated_atThe updated_at you read; null or absent for the first save. A layout saved since answers 409.
Save the signature fields placed on a document › Responses
OK
Get a download link for a file
Returns a temporary link to the file's bytes, valid for 5 minutes. Only available once the upload has been confirmed.
Required scope: org.read (Read organization profile).
path Parameters
idFile UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a download link for a file › Responses
OK