Setup has two distinct parts, each performed by a different actor:
Your integration pushes transactions into Tesouro — typically from a card feed in real time or in batch. This uses your partner-level credentials.
Your customer’s admin configures the organization: what employees must provide before submitting, which transactions require approval and who signs off, and which ledger accounts expenses map to.
Run this once per organization and update it as your customers’ policies change.
Transactions are the core objects in expense management. Every other step — receipt matching, validation, approval — happens in the context of a transaction.
entity_user_id ties the transaction to the employee who made the purchase — it’s used by the approval engine and by access-level filtering. If you omit it, the transaction isn’t associated with any user.
For card feed ingestion, use POST /transactions/bulk. It accepts up to 5,000 transactions per request and processes them in order, so each result maps to the same index in the input. Duplicate external_id values within the same organization are silently skipped:
The response reports a status (success, partial_success, or error) and a data array where each entry has the created transaction’s id or null if that record failed:
Transaction requirements control what an employee must provide before they can submit a transaction for approval. You configure requirements once per organization; they apply to every transaction in that organization.Two fields can be made required: receipt_id and description. You can also set an amount_threshold so the requirement only applies to transactions above a certain value (in minor units).
Replace the full requirements list with PUT /transactions/validations. To require a receipt on all transactions and a description on transactions over $50:
A transaction that satisfies all requirements returns "validation_errors": []. The has_validation_errors field on the transaction itself reflects the same state.See PUT /transactions/validations and POST /transactions/{id}/validate for the full API reference.
Approval policies determine which transactions require approval and who the approvers are. Tesouro evaluates policies automatically when a transaction is submitted.Expense approval policies follow the same engine as accounts payable approval policies, with two differences:
Set "object_type": "transaction" on the policy to scope it to expense transactions.
The trigger variable is transaction — e.g., {transaction.amount >= 5000}.
Creating and updating approval policies requires an organization user token with the approval_policy permission. See Authentication for how to obtain one.
To route approvals by role rather than by specific user ID — for example, to any user with a finance-manager role — use ApprovalRequests.request_approval_by_role in the script. See TesouroScript reference and Script examples for the full set of approval methods, including role-based and reporting-manager routing.
To approve transactions automatically when they meet a condition — for example, expenses under $20 — use Transactions.approve in the script instead of an approval request:
When this policy matches, the transaction moves directly from approve_in_progress to approved with no human approver involved.If multiple policies could match a transaction, the one with the highest priority value wins. See Approval policy priority for details.See POST /approval-policies for the full request schema.
Configuring accounting fields tells Tesouro which general ledger accounts are available for auto-assignment when a receipt is matched to a transaction. Without ledger accounts, Tesouro’s auto-categorization step can’t populate ledger_account_id.
The response is a paginated list. Tesouro’s auto-categorization engine fetches this same list (up to 1000 records) when selecting the best GL match for a new receipt. Keep name and description precise — the AI uses both fields to determine the right account.See POST /ledger-accounts and GET /ledger-accounts for the full API reference.
