Receipts & OCR

Overview

A receipt is a digital file — PDF, PNG, JPEG, or GIF — representing proof of a purchase. Receipts can be created from structured data, uploaded from a file, or forwarded by email. Regardless of how a file arrives, Tesouro runs OCR to extract structured fields, and the AI auto-matching engine then tries to link the receipt to an existing transaction. Receipts created from structured data skip OCR entirely.

Upload paths

Direct upload (API or web)

Call POST /receipts/upload-from-file with the file as multipart/form-data. Tesouro accepts PDF, PNG, JPEG, and GIF files up to 20 MB:

curl -X POST 'https://api.sandbox.tesouro.com/v1/receipts/upload-from-file' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'X-Finops-Version: 2025-06-23' \
  -F 'file=@receipt.pdf;type=application/pdf'

The response is immediate. The receipt is created with source_of_data: "ocr" and OCR processing begins asynchronously:

{
  "id": "e5ea872b-a3d6-452b-b1d3-7b4e30b8ce2b",
  "created_at": "2026-05-22T12:59:50.507691+00:00",
  "updated_at": "2026-05-22T12:59:50.507704+00:00",
  "created_by_entity_user_id": null,
  "currency": null,
  "description": null,
  "document_id": null,
  "file_id": "e17e0a47-79a5-4672-af79-9a5ce47597f0",
  "file_name": "receipt.pdf",
  "file_url": "https://tesouro-monite-file-saver-stage.s3.us-east-1.amazonaws.com/staging/payables/e17e0a47-79a5-4672-af79-9a5ce47597f0/receipt.pdf",
  "issued_at": null,
  "merchant_location": null,
  "merchant_name": null,
  "ocr_request_id": null,
  "ocr_status": null,
  "origin": "upload",
  "source_of_data": "ocr",
  "total_amount": null,
  "transaction_id": null
}

The ocr_status field on the receipt tracks where processing is:

Status	Meaning
`null`	OCR hasn’t started yet — the receipt was just created.
`processing`	OCR is running.
`success`	OCR completed and fields are populated.
`error`	OCR failed. The receipt still exists but structured fields won’t be populated.
`canceled`	OCR was canceled before completing.

When OCR finishes, fields like merchant_name, total_amount, issued_at, and currency are populated and you receive a receipt.ocr_finished webhook:

{
  "action": "receipt.ocr_finished",
  "object": {"id": "e5ea872b-a3d6-452b-b1d3-7b4e30b8ce2b"},
  "object_type": "receipt"
}

Email forwarding

Each organization has a dedicated mailbox. Employees forward receipt emails as attachments (PDF, PNG, JPEG, or GIF, up to 20 MB) to that address. Tesouro creates a receipt for each attachment and runs OCR automatically. To get an organization’s mailbox address, call GET /mailboxes:

curl -X GET 'https://api.sandbox.tesouro.com/v1/mailboxes' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'X-Finops-Version: 2025-06-23'

[
  {
    "id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
    "status": "active",
    "related_object_type": "receipt",
    "mailbox_name": "1102737648192968373_receipts",
    "mailbox_full_address": "1102737648192968373_receipts@mg.sandbox.tesouro.com"
  }
]

Email-forwarded receipts show origin: "email" and the sender field contains the forwarding address. The receipt’s source_of_data is "ocr"—OCR still processes the attachment regardless of how it was delivered.

Mailboxes must be created with related_object_type: "receipt" to receive expense receipts. Mailboxes with type "payable" route to accounts payable, not expense management. See Mailboxes to set up a custom email domain.

Create a receipt from structured data

If you already have the receipt data in structured form (from a partner system or POS integration), use POST /receipts to create a receipt without a file. This skips OCR entirely:

curl -X POST 'https://api.sandbox.tesouro.com/v1/receipts' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant_name": "The Smith Restaurant",
    "merchant_location": "28 West 21st St, New York, NY 10010",
    "description": "Team lunch with new client",
    "currency": "USD",
    "total_amount": 8500,
    "issued_at": "2026-05-22T12:00:00Z"
  }'

{
  "id": "519143ef-22c0-481c-80d2-4348a135bc58",
  "origin": "upload",
  "source_of_data": "user_specified",
  "ocr_status": null,
  "transaction_id": null
}

You can also attach a file to an existing receipt at any time using POST /receipts/{id}/attach-file. See POST /receipts and POST /receipts/upload-from-file for the full API reference.

Auto-matching to transactions

After OCR completes, Tesouro’s AI auto-matching engine tries to link the receipt to an unmatched transaction in the same organization. It scores candidates based on amount, currency, merchant name, and timestamp proximity. The receipt is linked to the highest-scoring transaction that clears the match threshold and hasn’t already been matched. If no candidate clears the threshold, the receipt remains unmatched in the Receipts inbox. When the AI links a receipt, the transaction’s source_of_data.receipt_id is set to "automatched". At that point, the auto-categorization step fires and populates ledger_account_id and description on the transaction.

Each receipt can only be linked to one transaction. If a receipt is already matched, the auto-matching engine won’t re-link it.

Receipt bank and manual matching

Unmatched receipts accumulate in the Receipts inbox — retrievable via GET /receipts?has_transaction=false. Use the has_receipt=false filter on GET /transactions to find the other side: transactions still waiting for a receipt.

List unmatched receipts

curl -X GET 'https://api.sandbox.tesouro.com/v1/receipts?has_transaction=false' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'X-Finops-Version: 2025-06-23'

Manual match

When auto-matching doesn’t find a match, or links the wrong transaction, manually link a receipt to a transaction by sending PATCH /receipts/{receipt_id} with the transaction_id:

curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receipts/e5ea872b-a3d6-452b-b1d3-7b4e30b8ce2b' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'Content-Type: application/json' \
  -d '{"transaction_id": "792c0577-3adf-4643-9570-2b641a5b04f2"}'

A manual match sets source_of_data.receipt_id to "user" on the transaction, and link_source: "user" on the receipt. This distinguishes it from an AI-generated match in audit logs and in the UI.

Unlink a receipt

To remove a receipt from a transaction, send PATCH /receipts/{receipt_id} with "transaction_id": null. The receipt returns to the Receipts inbox. See GET /receipts and PATCH /receipts/{id} for the full API reference.

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Overview

Upload paths

Direct upload (API or web)

Email forwarding

Create a receipt from structured data

Auto-matching to transactions

Receipt bank and manual matching

List unmatched receipts

Manual match

Unlink a receipt

​Overview

​Upload paths

​Direct upload (API or web)

​Email forwarding

​Create a receipt from structured data

​Auto-matching to transactions

​Receipt bank and manual matching

​List unmatched receipts

​Manual match

​Unlink a receipt

Overview

Upload paths

Direct upload (API or web)

Email forwarding

Create a receipt from structured data

Auto-matching to transactions

Receipt bank and manual matching

List unmatched receipts

Manual match

Unlink a receipt