Prerequisites
A Bezala account. If you don't have one, sign up at bezala.com — a personal free company is enough for testing.
The email and password for that account, or an SSO token from Google, Microsoft, or Okta if you sign in that way.
curl, or any HTTP client that speaks JSON.
Try it in Postman first (optional, but the fastest path)
If you'd rather click through requests than copy-paste curl, we publish a Postman collection covering every endpoint in this section (and many more): Bezala API on Postman.
Click Run in Postman, then in the imported collection:
Open the Variables tab on the collection root.
Set email and password to your Bezala credentials.
Send any request. The collection's pre-request script calls /api/auth/token for you, captures the token, and reuses it on every subsequent call. No copy-paste needed.
To re-authenticate (e.g. after rotating the password), clear the token collection variable and send any request again.
The rest of this article walks through the same flow on the command line, which is also a good way to make sure you understand what's happening under the hood.
Step 1 — Get a token
Trade your email and password for a token by calling /api/auth/token:
A successful response looks like this:
The token is what you'll use to authenticate every subsequent request. The receipts_email is the personal forwarding address that Bezala generated for this user — anything emailed there with a receipt attached becomes a draft transaction. Stash both somewhere safe.
If you sign in with Google, Microsoft, or Okta, swap auth/token for the matching SSO endpoint and pass the provider's access token. See authentication for the details.
Step 2 — Make an authenticated call
Pass the token in an Authorization: Bearer <token> header on every API call. Let's list your chart of accounts:
You'll get back an array of asset and expense accounts:
If you see a 401 Unauthorized instead, your token is wrong, has expired, or wasn't sent in the header. Double-check the Authorization value — it must literally be Bearer followed by the token, with a single space.
Step 3 — Bootstrap your client state
A real integration almost always starts with a single call to /api/home. This endpoint returns everything a fresh client needs in one round-trip: the current company, the current user, the chart of accounts, the list of vendors, the list of vehicles for mileage, available currencies, the VAT codes, and the dates of recent accounting batches.
/api/home is how the Bezala web app initialises itself, and it's a good shape for any integration too — call it once on startup, cache the result, refresh as needed.
Step 4 — Look around
You now have everything you need to explore. Some endpoints worth poking at:
GET /api/expenses — your draft, in-review, approved-and-queued, and unapproved expenses, grouped by state. This is the dashboard data.
GET /api/transactions — the receipts list, filterable by state, date, and user.
GET /api/users — the users in your company.
GET /api/cost_centers — the cost-center / dimension structure.
For the full endpoint list, see /apipie. For the conceptual model behind these objects, read tour of the API next.
What "production" looks like
Once you're past prototyping:
Don't store the password. Get a token once, store the token, and refresh it when calls start returning 401.
Use a service user. Create a dedicated Bezala user for your integration with manager or accountant rights as needed. Don't piggyback on a real employee's login — when they leave the company, your integration breaks.
Be defensive about pagination. List endpoints default to 50 records per page. Either page through with page / per_page, or use skip_pagination=true where supported. See Conventions.
Poll with updated_after. Don't fetch everything every time — pass a Unix timestamp and you'll get back only the records that have changed since.
That's it. You're integrated.