---
title: "Uploads a document to an invoice"
method: POST
path: "/invoices/{invoice_id}/documents"
tags: ["Invoice Documents"]
---

# Uploads a document to an invoice

`POST /invoices/{invoice_id}/documents`

## Request

- Base URL: `https://api.rillet.com`
- URL: `https://api.rillet.com/invoices/{invoice_id}/documents`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/rillet/apis/rillet-accounting-api/docs/invoices/:invoice_id/documents/post.ts> (a function with typed inputs; its response is checked against the schema)

Attaches one PDF, JPEG, PNG, or XLSX file to an existing invoice.
Existing attachments are preserved, including files uploaded through the Rillet application.
Repeating an upload creates a new file; there is no idempotency key.
When Update approval is required, returns 202 with a review reference and the file is not
attached until approval. A different upload while an edit is pending returns 409.
Cancel or resolve a pending approval before uploading another file.
An invoice can have at most 10 attachments totalling at most 7 MiB, including files uploaded
through the Rillet application, so the invoice email stays within delivery limits.
A file name may have at most 255 characters and must not contain a path.
Attachments are included when Rillet emails the invoice. Attach before the invoice is sent:
adding a file to an invoice that was already sent does not send it again.

## Request body `multipart/form-data`

- object
  - `file` string, binary, required

## Response `200`

Document attached

- union
  - InvoiceDocument
    - `id` string, uuid, required: Identifier of the attachment.
    - `file_name` string, required
    - `size` integer, required: Size in bytes.
    - `url` string, uri, required: Temporary download URL valid for up to 1 hour.
  - InvoiceUpdateProposal: Proposed edits awaiting approval. These changes have not been applied to the invoice.
    - `invoice_id` string, uuid, required
    - `approval_request_id` string, uuid, required
    - `status` 'PENDING', required

## Other responses

- `202`: Attachment addition awaiting approval; effective attachments are unchanged
- `400`: Empty file, missing filename, unsupported file content, or attachment limit reached
- `404`: Invoice not found or not accessible
- `409`: An invoice edit is awaiting approval, or other uploads kept changing the invoice's attachments; retry the upload. Or the size of an existing attachment cannot be read; the error names it so it can be removed or re-uploaded.
- `413`: The invoice's attachments would exceed 7 MiB in total
- `default`: Error

## Changes

- **2026-11-03** `c393d0102005`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rillet/apis/rillet-accounting-api/changes/invoices/:invoice_id/documents/post.md)

---

[API](https://skmtc.dev/rillet/apis/rillet-accounting-api.md) - [All operations](https://skmtc.dev/rillet/apis/rillet-accounting-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rillet/apis/rillet-accounting-api/revisions/c393d0102005?raw)