---
updatedAt: 2026-11-20T20:15:32.764Z
---

Fetch the complete documentation index at: https://docs.avvio.xyz/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Send an invoice to prepare

`POST https://api.avvio.xyz/business/api/v1/assistant/v1/{orgId}/documents`

Send an invoice or bill (PDF, PNG or JPEG). Avvio reads it, matches the
payee, runs the same checks as the dashboard, and prepares the payment.

**Nothing is paid from this API.** A person on your team reviews and
approves the package in Avvio, at `approveUrl`, with their own sign-in.
There is no approve or send endpoint.

Needs a live key with scopes `["write", "assistant"]`. At most two
documents per key at once (`429 TOO_MANY_IN_FLIGHT`). Sending the same
file again from the same key returns the same package.

## Parameters

- `orgId` (path, required) — The opaque organization id issued to you, normally CUID-shaped (for example `cmsx…`). It is not an `org_`-prefixed alias. Pass it unchanged in every organization-scoped path.
- `Idempotency-Key` (header) — Same semantics as `Idempotency-Key` on the money routes (replay on the same body, `409` on a different one, released by a `4xx`), but optional here: without it the request simply runs once with no replay. Every `POST`, `PATCH` and `DELETE` honors it; send one whenever your client might retry.

## Example

```bash
IDEMPOTENCY_KEY=$(uuidgen)  # new key per call; reuse it only to retry this exact request
curl -s -X POST "$AVVIO_BASE_URL/assistant/v1/$AVVIO_ORG_ID/documents" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "filename": "<filename>",
        "contentType": "application/pdf",
        "dataBase64": "<dataBase64>"
      }'
```

## Responses

- `201` — The package. Usually `status` is still a hold while the document is read; poll the package or subscribe to `assistant_package.ready`.
- `400` — Not a PDF, PNG or JPEG, empty, or over the page limit.
- `401` — The key was refused. Nothing ran. - `UNAUTHORIZED`: missing, invalid or revoked, or a key on a route that does not accept one. - `KEY_EXPIRED`: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated. - `KEY_IP_NOT_ALLOWED`: the key is pinned to source addresses and this request came from another.
- `403` — `INSUFFICIENT_SCOPE` (the key lacks `write` or `assistant`), `LIVE_KEY_REQUIRED` (a test key), or `API_KEY_REQUIRED` (a dashboard session).
- `409` — `DUPLICATE_DOCUMENT`: someone else already sent this file. Nothing new was created. Or an `Idempotency-Key` reused with a different body.
- `429` — Too many requests. The default ceiling is **100 requests per minute per API credential** on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies. Obey `Retry-After`; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same `Idempotency-Key`.
- `503` — `ASSISTANT_API_DISABLED`: the Assistant API is not on for this organization.

Machine contract: [partner-payouts.openapi.yaml](/partner-payouts.openapi.yaml), operation `createAssistantDocument`.
