Public API: developer guide

This article is for developers connecting a system to the Illizeo public API: where to find the documentation, how to authenticate, what each scope opens, how to read responses and errors, and which limits to respect. The full contract, operation by operation, is published in OpenAPI 3.1 format.

Before you start #

• You need a token created by an administrator of the company, with the scopes required (see Creating and managing API tokens). Its value starts with illz_.
• The documentation page in the application opens with the “API tokens — View” permission. The raw contract itself is public.

The Documentation page #

Under Settings › Manage Illizeo › API Tokens, the Documentation button opens the API documentation page. It reads from top to bottom:

• the introduction to the API, the Base URL and a First call ready to copy;
• the Scopes card: each resource and the scopes that govern it, for example employees:read;
• one card per domain (employees, payroll, absences…): each operation with its method, path, summary and the scope it requires, or the mention no token;
• the Webhook events card: what Illizeo can send to your systems.

The openapi.json button opens the raw contract, to import into a tool such as Postman or a client generator. If the page shows “The API host did not answer”, check that the API address can be reached from your network. The descriptions in this reference are currently written in French; operation paths, scopes and codes are the same in every language.

Address and authentication #

• All calls go to https://api.illizeo.app, under /v1. The company does not appear in the address: the token identifies it.
• The token is sent in the Authorization: Bearer illz_… header. No other authentication method is accepted.
• Example: curl https://api.illizeo.app/v1/employees -H "Authorization: Bearer illz_your_token"
• Two addresses answer without a token: GET /openapi.json (the contract) and GET /v1/ping (an availability probe).
• Responses are in JSON, except file downloads (payroll documents, exports, payslips), which return the file.

Scopes and what they open #

Each operation requires a scope of the form resource:action, ticked on the token. A resource linked to a module is only offered if the module is enabled in the space.

Identity and perimeter #

A token acts under the identity of the person who created it. In addition to the scope ticked on the token, each operation requires that person to hold the permission of the equivalent screen in the application and, where relevant, access to the module: without them, the response is 403. An employee or object outside their perimeter answers 404. Payroll is read-only and only returns periods approved by HR: a period not yet approved answers 404 with the code PERIODE_NON_APPROUVEE.

Responses and errors #

Access-control refusals and recent resources answer with the same envelope: status (Success or Error), code (the HTTP code), message, request_id, error_code for an error, and data. For example: {"status":"Error","code":403,"request_id":"req_…","error_code":"SCOPE_MANQUANT","data":{"required_scope":"employees:read"}}. Resources inherited from the first version of the API (employees, absences, attendance, documents, signatures, organisation) keep their original envelope: a boolean status, data or message, and errors per field on a refused validation (400).

A business refusal (404, 409, 422…) carries its own error_code, listed in the contract, and a message in the language requested by the X-Locale or Accept-Language header. Every response also carries an X-Request-Id header (the request_id of the envelope): always quote it in a support request.

Limits and response headers #

• Per token: the per-minute limit set on the token, otherwise 60; and 10,000 requests per calendar day (UTC).
• Per company: 600 requests per minute, all tokens combined. Every response announces it with X-RateLimit-Limit and X-RateLimit-Remaining.
• After a 429: wait the number of seconds given by Retry-After before trying again.
• Quota: when the subscription includes a monthly quota, every response carries X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset.
• Size: 5 MB at most per request, body and files included.

Pagination and volumes #

• Paginated lists accept page (from 1) and per_page; the contract gives, for each operation, the default and the maximum (10 and 100 for the payroll tabs and exports, 100 and 200 for Flex Office, whose response carries meta with page, per_page, total and last_page).
• GET /v1/attendance requires a from / to window of 31 days at most.
• GET /v1/absences still returns every absence of the company, without pagination: filter by employee.
• Dated reads cover 43 days at most for Scheduling and 93 days for Flex Office (422 PERIODE_TROP_LONGUE beyond).

Good to know #

• To be notified of a change rather than look for it, subscribe your system to webhooks: see Receiving and verifying a webhook.
• Files of reports scheduled on the “Pickup via API” channel are retrieved through /v1/exports for 30 days (see Scheduling a report).
• A call refused by the token check (unknown token, missing scope, limit reached) does not appear in the token’s usage log: only the response keeps a trace of it.