REST API basics
How external systems reach the system's data: API key, request and response structure, error codes and the interactive API documentation.
The system's REST API gives external programs (for example accounting software or your own web front end) access to partner, address and bank account data and to subscription ordering. Every call uses a personal API key and runs with the permissions of the key's owner.
Making the first call
- Request an API key for your user. Keys are managed in the user settings (Users → API key), where they can also be revoked.
- Ask the administrator to give your user the function permissions and company content permissions you want to use through the API. The API allows exactly what the screens allow.
- Open the interactive API documentation (the administrator gives you the address). The documentation is built automatically from the system's own endpoints.
- Enter the API key on the documentation page, choose an endpoint, for example the partner list, and run a test call.
- Check the response: on success you get the data, on error a short message and a machine-readable error code.
Error codes
| Code | Meaning |
|---|---|
| 401 | missing or invalid API key |
| 403 | no function permission, or the company is outside your content permissions |
| 404 | the requested record does not exist |
| 409 | conflict, for example the address to delete is used by companies |
| 422 | invalid or missing data |
| 500 | unexpected server error |
| 503 | the system is being updated; try again in two minutes |
An API key is like a password. Do not put it anywhere public, and have it revoked if it has leaked.
Example
Sample Ltd.'s web shop uses a new customer's tax number to check whether the partner already exists. The response with code 200 returns the partner's data, addresses and bank accounts; if the partner belongs to a company group the key owner has no rights for, there is no match.