---
title: "Upsert a receivable document and get a presigned upload URL"
method: POST
path: "/receivables/{id}/documents"
tags: ["Receivables"]
---

# Upsert a receivable document and get a presigned upload URL

`POST /receivables/{id}/documents`

## Request

- Base URL: `https://core.sivo.com`
- URL: `https://core.sivo.com/receivables/{id}/documents`
- Auth: one of:
  - API key in header `Authorization`
  - OAuth 2
    - Authorization code: `https://dashboard.sivo.com/oauth/authorize`
    - Client credentials
    - Token URL: `https://core.sivo.com/oauth/token`
- TypeScript: <https://skmtc.dev/sivo/apis/sivo-advance-api/docs/receivables/:id/documents/post.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `id` string, required: An object ID assigned and owned by the originator

## Headers

- `Idempotency-Key` string: A unique key per operation, could be V4 UUID or other high‑entropy random string. Keys can be up to 256 bytes. See [Idempotent Requests](/docs/idempotent-requests).

## Request body

- object: Creates the receivable document when the id is new, otherwise updates the existing document with the provided fields. Changing the file name, content type or size resets the document to pending_upload and issues a fresh upload URL. Set an optional field to null to clear it.
  - `id` string, required: The receivable document ID assigned by the originator
  - `file_name` string: File name of the document, used when the file is downloaded. Required at creation, optional for updates.
  - `content_type` 'application/pdf' | 'image/png' | 'image/jpeg' | 'image/webp' | 'application/xml' | 'text/xml': MIME type of the document file. Required at creation, optional for updates.
  - `size_bytes` integer: Size of the file in bytes, at most 25 MB. Required at creation, optional for updates.
  - `type` 'invoice' | 'contract' | 'proof_of_delivery' | 'other' | 'null', nullable: Kind of document attached to the receivable
  - `metadata` object, nullable: Additional custom data associated with this document

## Response `200`

Successful operation

- object
  - `file_name` string, required: File name of the document, used when the file is downloaded
  - `content_type` 'application/pdf' | 'image/png' | 'image/jpeg' | 'image/webp' | 'application/xml' | 'text/xml', required: MIME type of the document file
  - `size_bytes` integer, required: Size of the file in bytes, at most 25 MB
  - `type` 'invoice' | 'contract' | 'proof_of_delivery' | 'other': Kind of document attached to the receivable
  - `metadata` object: Additional custom data associated with this document
  - `id` string, required: The receivable document ID assigned by the originator
  - `created_at` string, date-time, required: Creation date and time
  - `created_by` string, required: ID of the user that created this object
  - `updated_at` string, date-time, required: Last update date and time
  - `updated_by` string, required: ID of the user that last updated this object
  - `status` 'pending_upload' | 'uploaded' | 'quarantined', required: Lifecycle status of the document: pending_upload until the file upload is confirmed, quarantined when the file failed malware scanning (upload a replacement file to clear it)
  - `etag` string: Entity tag of the stored file, set once the upload is confirmed
  - `upload` object: Present while the document is pending upload
    - `url` string, uri, required: URL to send the upload HTTP POST to
    - `fields` object, required: Form fields that must accompany the file in the multipart POST body
    - `expires_at` string, date-time, required: Expiry of the upload URL

## Changes

- **2026-11-03** `4bbab9699612`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sivo/apis/sivo-advance-api/changes/receivables/:id/documents/post.md)

---

[API](https://skmtc.dev/sivo/apis/sivo-advance-api.md) - [All operations](https://skmtc.dev/sivo/apis/sivo-advance-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sivo/apis/sivo-advance-api/revisions/4bbab9699612?raw)