API reference (beta)

The To Bill API is the one the app itself uses: clients, invoices, quotes, articles, expenses, bank, accounting, VAT, payroll and time. A personal API key opens it to your scripts and tools, with your rights. The interactive API reference describes every route a key can call, its parameters and responses, gives examples in curl, JavaScript, Python and PHP, and lets you try a request with your key.

A reference for developers

Like most technical references, it is written in English, the developers’ language. This page sums up what matters most.

A beta version

The API is in beta (0.x). Its routes and their responses may change without notice: there is no compatibility guarantee and no support for using it directly. To connect an AI assistant, use the MCP server, which is the stable interface: see Connect an AI assistant.

Authenticate

Every request carries a personal API key in the HTTP Authorization header:

curl https://app.tobill.ch/api/clients -H "Authorization: Bearer tb_pk_…"

You create the key in Settings › AI and API connections: see The API and API keys. It acts on your behalf, in the company where you created it, with your rights in that company. A Read only key only sends read requests (GET); a Read and modify key can also create, modify and delete.

Errors

A refused request gets a JSON response of this form: { "statusMessage": "error", "message": "…", "error_code": "…", "fallback": "…" }. message is a stable code for your program to test; fallback is a readable sentence, for example naming the field concerned.

HTTP code	Meaning
400	Invalid data.
401	Key missing, invalid, expired or revoked.
403	Refused: a read-only key, a missing right, a subscription without API access, or a part of To Bill closed to keys (not_available_with_api_token).
404	Not found in this company.
429	Too many requests: wait the number of seconds the Retry-After header gives.

Limits

• 300 requests per minute per key; a change counts as two.
• A key does not open the sign-in to your account, the subscription, payments, the management of the team and keys, another company, a fiduciary’s cockpit or bulk actions. These routes are not in the reference.

The OpenAPI specification

The reference is generated from the API’s OpenAPI 3.1 document. You can import it into a tool such as Postman or generate a client from it:

What	Address
Interactive reference	https://docs.tobill.ch/api
OpenAPI 3.1 specification	https://app.tobill.ch/api/openapi.json

Try a request

In the reference, the Test Request button sends the request from your browser straight to https://app.tobill.ch, with nothing in between. Your key goes to To Bill only and is not stored: it is gone when you close the page. A request that changes data really changes your data: to explore the API, try it with a Read only key.