This section of the helpdesk explains how the API is structured and how the underlying data model works. It is the conceptual companion to the API reference at /apipie, which lists every endpoint and parameter.
What the API is good for
Submitting expenses programmatically. Push receipts, mileage trips, daily allowances, and rewards into Bezala from another system — for example, an in-house procurement tool or a travel-booking platform — and have them flow through Bezala's approval workflow into your accounting software.
Reading the result. Pull approved expenses out of Bezala in structured form, with cost centers, VAT lines, attachments, and approval metadata, for use in downstream reporting or analytics.
Keeping master data in sync. Bezala holds its own users, chart of accounts, cost centers, and vendors. The API lets you mirror those from an HR system or ERP so accountants don't maintain them twice.
Reconciling credit-card spend. Import card statements, match each line to a receipt, and let Bezala fall back to "no receipt needed" with a documented reason for the lines that don't.
Time and absence tracking. Read and write work-time entries, project time entries, vacation, and sick leave.
What the API is not
The API is not a payments rail. Bezala generates SEPA payment files and bookkeeping vouchers as part of the accounting batch (see sending expenses to accounting), but the actual money movement happens in your bank or your bookkeeping software, not through this API.
The API also does not currently emit webhooks. Integrations that need to react to events — for example, "an expense was just approved" — need to poll. We recommend the updated_after parameter on list endpoints for efficient polling. See conventions.
Design at a glance
REST over HTTPS. Every endpoint is a path under https://app.bezala.com/api/. Verbs follow the usual REST conventions: GET to read, POST to create, PUT to update, DELETE to remove.
JSON in, JSON out. Send Content-Type: application/json and a JSON body for POST/PUT. Responses are always JSON unless explicitly noted (PDF and XLSX exports return binary content).
Bearer-token authentication. You authenticate with an Authorization: Bearer <token> header. Tokens are issued per user, scoped to that user's company. See Authentication.
Tied to a company context. A user can belong to several companies. Every API call is implicitly scoped to the user's currently selected company. To act in a different one, switch the user's company first.
State machines for everything. Expenses, absences, and budgets all move through documented states (draft, reviewing, approved, accounted, and so on). The lifecycle is the same shape across object types — once you've seen one, you've seen them all. See the expense lifecycle.
How to read the rest of this section
Read the articles in order if you're new. Each builds on the last:
Quickstart — get a token, make a call.
Authentication— token formats, SSO, security.
Conventions— pagination, dates, IDs, polling.
Errors— what status codes mean and how to recover.
Tour of the API — the conceptual model.
Once you've read those, dip into the object-specific pages — receipts, daily allowances, trips, credit-card bills, and so on — as you need them. The reference at /apipie is always one click away for full parameter detail.
Getting help
If you spot something that's wrong or missing, or you've hit a behaviour the docs don't explain, email [email protected] with the request you sent and the response you got. We read every message.