Skip to main content

​
Overview

A receipt is a digital file representing proof of an expense. Receipts can be uploaded independently or attached to transactions for reconciliation, auditing, or reporting purposes.

​
Create a receipt

There are several ways to create a receipt: When a receipt is created from a PDF, PNG, or JPEG file, Tesouro’s OCR service automatically extracts the receipt information from the file and a new receipt is created with the extracted data fields accordingly. The file property of the receipt contains the file metadata and the link to access the original source file.

​
Create a receipt from data

If you already have the receipt data stored somewhere as individual attributes, you can create a receipt with these attributes by calling POST /receipts. You can provide the base64-encoded contents of the original invoice file in the field base64_encoded_file: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/receipts' \
  -H 'accept: application/json' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -d '{
        "document_id": "CN-DE-2024-103",
        "issued_at": "2025-08-01T09:10:00Z",
        "merchant_name": "Burgers Inc",
        "merchant_location": "5th Avenue, 70001 NYC, USA",
        "description": "Payment for lunch with clients",
        "base64_encoded_file": "JVBERi0xLjQKJ...(your PDF base64 here)...",
        "partner_metadata": {},
        "currency": "USD",
        "total_amount": 15000,
        "transaction_id": null
    }'
The successful response contains the receipt ID and other fields: 
{
  "id": "eaf3b832-1d20-49c7-b5d4-f0e15b88d1a9",
  "created_at": "2024-10-29T14:23:41Z",
  "updated_at": "2024-10-29T14:23:41Z",
  "total_amount": 15000,
  "currency": "USD",
  "currency_exchange": null,
  "document_id": "CN-DE-2024-103",
  "issued_at": "2025-08-01T09:10:00Z",
  "merchant_name": "Burgers Inc",
  "merchant_location": "5th Avenue, 70001 NYC, USA",
  "description": "Payment for lunch with clients",
  "file_id": "9f263818-3c97-4038-8f30-2f4a4a92dcd9",
  "file_url": "https://files.sandbox.tesouro.com/preview/9f263818-3c97-4038-8f30-2f4a4a92dcd9",
  "ocr_request_id": null,
  "ocr_status": null,
  "origin": "upload",
  "partner_metadata": {},
  "sender": "hello@example.com",
  "source_of_data": "user_specified",
  "transaction_id": null,
  "created_by_entity_user_id": "b3f637d6-b25c-4b0f-8c7f-c829ad0d4561"
}
You can attach a receipt file to an existing receipt, in any status, by calling POST /receipts/{receipt_id}/attach-file.

​
Upload files via API

You can upload receipts in the PDF, PNG, or JPEG format to Tesouro by calling POST /receipts/upload-from-file. Upon file upload, the system automatically initiates OCR to extract structured fields such as merchant_name, total_amount, issued_at, and line_items from the document. The maximum file size is 20 MB: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/receipts/upload-from-file' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: multipart/form-data' \
     -F 'file=@pdf-receipt.pdf;type=application/pdf'
The successful contains the receipt ID and other parameters: 
{
  "id": "eaf3b832-1d20-49c7-b5d4-f0e15b88d1a9",
  "created_at": "2025-08-01T09:10:00Z",
  "updated_at": "2025-08-01T09:10:00Z",
  "total_amount": 15000,
  "currency": "USD",
  "currency_exchange": null,
  "document_id": "CN-DE-2024-103",
  "issued_at": "2025-07-01T09:10:00Z",
  "merchant_name": "Burgers Inc",
  "merchant_location": "5th Avenue, 70001 NYC, USA",
  "description": "Payment for lunch with clients",
  "file_id": "9f263818-3c97-4038-8f30-2f4a4a92dcd9",
  "file_url": "https://files.sandbox.tesouro.com/preview/9f263818-3c97-4038-8f30-2f4a4a92dcd9",
  "ocr_request_id": null,
  "ocr_status": null,
  "origin": "upload",
  "partner_metadata": {},
  "sender": "hello@example.com",
  "source_of_data": "ocr",
  "transaction_id": null,
  "created_by_entity_user_id": "b3f637d6-b25c-4b0f-8c7f-c829ad0d4561"
}
When the OCR scanning is finished (this might take up to 5-7 minutes), you will receive the receipt.ocr_finished webhook, indicating that this receipt resource has been created: 
{
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "created_at": "2024-03-04T20:06:48.593225+00:00",
  "action": "receipt.ocr_finished",
  "api_version": "2025-06-23",
  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
  "description": "Action has been performed on the receipt: created_from_file_upload.",
  "object": {
    "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0"
  },
  "object_type": "receipt",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}
Notes
  • OCR results are processed asynchronously and can be accessed through the ocr_status field or by subscribing to the receipt.ocr_finished webhook.
  • You can call POST /receipts/{receipt_id}/cancel-ocr while the ocr_status is in_progress to stop the OCR extraction.

​
AI-generated expense descriptions

After OCR processing, receipts are automatically enriched with AI-generated descriptions. The system analyses both the OCR output and the transaction context to populate the description field with concise, business-relevant content. The AI interprets receipt details to summarize what was purchased and, when possible, the business purpose or context. This reduces manual entry by providing pre-filled descriptions that users can review and adjust as needed. For example, a restaurant receipt from The Burger Inc in New York at 6pm could be described as “Dinner in NYC”, while a taxi receipt from the airport to the city center during a business trip might become “Taxi ride”. If the AI cannot confidently generate a meaningful description, the field remains empty instead of filling in potentially misleading text.

​
Send receipts by email

Each organization has a dedicated mailbox in Tesouro to which the receipts can be sent. The organization or organization user can send receipts as attachments in PDF, PNG, or JPEG format to this mailbox (the maximum file size is 20 MB). The Tesouro OCR service scans the information inside each email’s attachments. Then, Tesouro automatically creates a receipt for each occurrence found. To find the mailbox assigned to a specific organization, call GET /v1/mailboxes: 
curl -X GET 'https://api.sandbox.tesouro.com/v1/mailboxes' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_APP_TOKEN'
The successful response contains information about the mailbox: 
[
  {
    "id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
    "entity_id": "68fdd6b5-b60c-4f4d-8642-1cd7f2fa31e8",
    "status": "active",
    "related_object_type": "receipt",
    "mailbox_name": "1102737648192968373_receipts",
    "mailbox_full_address": "1102737648192968373_receipts@mg.sandbox.tesouro.com",
    "belongs_to_mailbox_domain_id": null
  }
]
Notes
  • By default, the automatically created mailboxes belong to the Tesouro domain (the web address that comes after @ in an email address), but the partners can set up their own email domain for better convenience.
  • When configuring email imports, make sure the mailbox is created with type receipt (not payable) so incoming emails are correctly filtered for this workflow.

​
Match a receipt to a transaction

To match a receipt to a transaction, send a PATCH request to the /receipts/{receipt_id} endpoint with the request body containing the transaction_id associated with the recepit: 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receipts/{receipt_id}' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "transaction_id": "fb3463a0-7d6e-54a3-bcd8-1b93388c648d"
     }'

​
AI Receipt-to-Transaction Automatching

Receipts can be automatically matched to transactions by an AI-driven matching engine once the OCR is completed. The system evaluates only unmatched items with the same entity_id, a timestamp difference of ≤1 day, and either the same (amount + currency) or (merchant_amount + currency) (with ≤1% allowed difference). The AI logic applies a two-step approach:
  1. Equal match - Exact merchant name match (case-insensitive, trimmed).
  2. Semantic match - If no exact match, merchant name + location are embedded and compared using fuzzy semantic similarity (≥0.8).

​
Considerations

  • The matching process runs only when receipts and transactions share the same entity_id and satisfy the required timestamp and amount conditions.
  • When an exact merchant name match is found, the receipt is immediately linked to the transaction.
  • If there is no exact match but the semantic similarity between merchant name and location is at least 0.8, the system also links the receipt automatically.
  • If neither condition is met, the receipt remains unmatched.
  • To ensure data consistency, each receipt can only ever be linked to one transaction.

​
CSV export (Coming soon)

Easily export transactions and receipts into a CSV file for reporting, analysis, or integration with external tools. The export will include structured fields such as amounts, currencies, merchants, dates, and matching receipt references.

​
List all receipts

To get information about all receipts associated with the specified organization, call GET /receipts.

​
Retrieve a receipt

To get information about a specific receipt, call GET /receipts/{receipt_id}.

​
Edit a receipt

To edit an existing receipt, call PATCH /receipts/{receipt_id}.

​
Delete a receipt

To delete a specific receipt, call DELETE /receipts/{receipt_id}.

​
Receipt line items

Each receipt may include one or more line items representing individual goods or services listed on the document. Line items can be extracted via OCR and include structured data such as item name, total, cost_center_id, and accounting_tax_rate_id.

​
Add line items to a receipt

To add line items to a receipt, call the POST /receipts/{receipt_id}/line-items endpoint: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/receipts/{receipt_id}/line-items' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
        "name": "Dinner with client",
        "total": 18000,
        "cost_center_id": "c1d2e3f4-5678-4321-abcd-987654321000",
        "accounting_tax_rate_id": "e7f8g9h0-1112-1314-1516-171819202122",
        "general_ledger_id": "b3a4c5d6-7890-4321-bcde-34567890abcd"
    }'
When adding line items, you may need to reference the following objects:

​
List all line items of a receipt

To list all line items of a specific receipt, call the GET /receipts/{receipt_id}/line-items endpoint.

​
Update line item

To edit a specific line item of a receipt, call the PATCH /receipts/{receipt_id}/line-items/{line_item_id} endpoint.

​
Delete line item

To remove the line item from the receipt, call the DELETE /receipts/{id}/line-items/{line_item_id} endpoint.