# Received invoices (https://docs.getbeel.com/en/api/received-invoices)

List and review supplier invoices, upload one for the AI to read, and manage the categories and AI rules that file them.

Received invoices are the supplier invoices and receipts of your company: from SDI (`source: "sdi"`), collected from email (`email`) or the forwarding address (`forwarded`), uploaded (`manual`), or read from a bank movement (`bank_transaction`). The same list as **Received invoices** in the app.

Reads take `received_invoices:read` and work with both key modes. Writes take `received_invoices:write` and a live key: the books are real, there is no sandbox copy (`403 livemode_required` with a test key).

## List [#list]

```bash
curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Newest invoice date first, [paginated](/en/api/pagination). Filter by `status` (`processing`, `pending_review`, `verified`, `rejected`, `exported`, `missing_document`), `source`, `search` and `date_from` / `date_to`. With a test key the list holds only the invoices received in the [sandbox](/en/api/sdi-receiving).

MCP: `list_received_invoices`, and `list_collected_documents` for those still to review.

## Approve or reject [#approve-or-reject]

```bash
curl -X POST https://www.getbeel.com/api/v1/received-invoices/$INVOICE_ID/approve \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

- `POST /received-invoices/{id}/approve` moves an invoice from `pending_review` (or `rejected`) to `verified`, like reviewing it in the app. Already verified: nothing changes.
- `POST /received-invoices/{id}/reject` moves it from `pending_review` (or `verified`) to `rejected`: use it for documents that are not invoices.

MCP: `approve_collected_document`, with `decision: "reject"` to reject.

## Reverse charge on foreign invoices [#reverse-charge-on-foreign-invoices]

An invoice from a foreign supplier collected by email, the forwarding address or an upload carries `reverse_charge`: the autofattura getbeel proposed for it (`null` when none applies, for example an Italian supplier or an invoice received through SDI).

```json title="reverse_charge"
{
  "tipo_documento": "TD17",
  "status": "proposed",
  "reason": "non_eu_services",
  "deadline_basis": "effettuazione",
  "deadline": "2026-12-15"
}
```

- `tipo_documento`: `TD17` services from abroad, `TD18` goods from another EU state, `TD19` goods already in Italy; `null` when no TD applies or the supplier country is missing. The rule decides it, not the AI.
- `status`, the live state of the proposal: `proposed` (the XML draft is generated automatically), `needs_review` (check it on the Autofatture page first), `needs_country` (enter the supplier country), `not_required` (goods imported from outside the EU: the customs document replaces the TD), `generated` (the XML draft exists, not sent), `sent` (handed to SDI), `dismissed` (deleted by the team).
- `reason` and `deadline` are the ones the rule set when the proposal was made (or when the team set its country and type).
- `deadline`: the 15th of the month after the receipt of the invoice (EU suppliers, `receipt`) or after the purchase (non-EU suppliers, `effettuazione`), art. 1, c. 3-bis, lett. b, d.lgs. 127/2015.

Sending the autofattura to SDI is always done by a person in the app. Rules and sources: [Autofatture](/en/guide/autofatture).

## Upload an invoice [#upload-an-invoice]

Send a PDF, JPEG, PNG or WEBP (up to 50 MB) for the AI to read, as an upload in the app.

```bash
curl -X POST https://www.getbeel.com/api/v1/received-invoices/uploads \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "file_url": "https://example.com/fattura-rossi.pdf" }'
```

```json title="Response"
{
  "object": "received_invoice_upload",
  "id": "scan_1794408453000_k3j9x2a",
  "status": "pending",
  "files": 1,
  "processed": 0,
  "skipped": 0,
  "error": null
}
```

- Send `file_url` (a public `https` URL, no redirects) or `file_base64` with `file_name`. The type is read from the file, not its name.
- Each file uses one invoice credit ([Pricing](/en/api/pricing)).
- `GET /received-invoices/uploads/{id}` follows it: `pending` and `processing` while the AI reads it, `completed` when the invoice is in the list with `status: "pending_review"`, `failed` with the reason in `error`. `skipped` counts files that were not an invoice or were a duplicate.

| Status | `code`                  | When                                                                                                |
| ------ | ----------------------- | --------------------------------------------------------------------------------------------------- |
| 413    | `payload_too_large`     | The file is over 50 MB                                                                              |
| 415    | `unsupported_file_type` | Not a PDF, JPEG, PNG or WEBP (FatturaPA XML arrives through [SDI receiving](/en/api/sdi-receiving)) |
| 402    | `credits_exhausted`     | No invoice credits left                                                                             |

MCP: `upload_received_invoice`, `get_received_invoice_upload`.

## Categories [#categories]

Categories file received invoices by type of cost. A received invoice carries the category's `slug` in `category`.

```bash
curl -X POST https://www.getbeel.com/api/v1/categories \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "label": "Software" }'
```

- `GET /categories` lists them in the app's order. `POST /categories` adds one: its slug comes from the label, its colour from the next preset unless you send `color` (`#rrggbb` or `hsl()`).
- `PATCH /categories/{id}` renames or recolours one; the slug stays. `DELETE /categories/{id}` deletes one and moves its invoices to `other`. Default categories cannot be deleted (`409 default_category`).
- `POST /received-invoices/{id}/category` with `{ "category": "software" }` sets an invoice's category (`422 unknown_category` for a slug the team doesn't have).

MCP: `list_categories`, `create_category`, `update_category`, `delete_category`, `set_received_invoice_category`.

## AI rules [#ai-rules]

Plain-language instructions the AI follows, in order, when it reads your invoices. The same rules as **Settings → AI rules**.

```bash
curl -X POST https://www.getbeel.com/api/v1/ai-rules \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "text": "Le fatture di Amazon Web Services vanno nella categoria software" }'
```

- `type` is `invoice_scan` (the default: reading received invoices) or `fattura_emessa` (drafting issued invoices from Stripe payments). The scope follows the type: `invoice_scan` rules take the `received_invoices` scopes, `fattura_emessa` rules the `invoices` scopes.
- A new rule goes last of its type and applies to the next invoices the AI reads; invoices already read stay as they are.
- `GET /ai-rules` lists them (filter with `type`). `PATCH /ai-rules/{id}` changes the text or pauses the rule (`"active": false`). `DELETE /ai-rules/{id}` deletes it.

MCP: `list_ai_rules`, `create_ai_rule`, `update_ai_rule`, `delete_ai_rule`.

## Related [#related]

- [Connections](/en/api/connections): connect a mailbox and scan it for invoices.
- [SDI receiving](/en/api/sdi-receiving): receive supplier invoices straight from SDI.
- [Webhooks](/en/api/webhooks): `received_invoice.created` for every new invoice.
