Skip to main content

​
Overview

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.

​
Upload transactions

Transactions are the core objects in expense management. Every other step — receipt matching, validation, approval — happens in the context of a transaction.

​
Create a transaction

To create a single transaction, call POST /transactions:
The 201 response includes the new transaction’s id and its initial expense_status:
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.

​
Bulk-create transactions

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:
See POST /transactions/bulk for the full request schema.

​
Define transaction requirements

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).

​
View current requirements

​
Update requirements

Replace the full requirements list with PUT /transactions/validations. To require a receipt on all transactions and a description on transactions over $50:
amount_threshold is in minor units (cents). null means the requirement applies regardless of amount.
PUT /transactions/validations replaces the entire requirements list. To remove all requirements, send {"required_fields": []}.

​
Validate a transaction

Employees can use POST /transactions/{id}/validate to check whether a transaction satisfies the current requirements before submitting.
If the transaction is missing a required field, the response lists what needs to be fixed:
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.

​
Define expense approval policies

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.

​
Create an approval policy

To require approval from a specific user for any expense over $50:
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.

​
Auto-approve small expenses

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.

​
Configure accounting fields

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.

​
Create a ledger account

​
List ledger accounts

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.

​
Reporting manager and expense visibility

The reporting manager relationship determines whose expenses a user can see and act on when they have the expense:read:self or expense:write:self permission. “Self” includes the user’s own transactions plus those of any users who list them as their reporting manager. This matters for two common setups:
  • A Finance admin assigned expense:read:self sees their own expenses and any direct reports’ expenses automatically.
  • An Employee similarly sees only their own expenses by default, but sees their direct reports’ expenses if any users list them as reporting manager.

​
Designate a reporting manager

Reporting manager is a field on the user model — not a role or permission. Set it when creating or updating a user by including reportingManagerId in the request body:
Any user can be a reporting manager — there is no special role or toggle required.

​
Expense visibility and approvals

Having reporting manager access does not automatically grant approval rights. Whether a reporting manager can approve their team’s expenses is determined by the organization’s approval policies. See Approval policies for how to route approvals by reporting manager.