---
title: "Public API: developer guide"
description: Address, authentication, scopes, response envelope, error codes, limits and pagination of the Illizeo public API, and the OpenAPI documentation.
url: "http://illizeo.com/en/centre-aide/api-developer-guide/"
updated: "2026-11-05"
category: Platform / REST API
---

# 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](https://illizeo.com/en/centre-aide/api-managing-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.

![The API documentation page, version v1.0.0: introduction to the public API (in French), authentication with the Authorization: Bearer header, single host https://api.illizeo.app, scopes, token identity, error envelopes, webhooks and rate limits, openapi.json button at the top right](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-developer-guide-01.en_.png?resize=800%2C500&quality=80&ssl=1)
The API documentation in the application.

## 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.

| Scope (creation screen) | Codes | Paths |
| --- | --- | --- |
| Employees | `employees:read`, `employees:write` | `/v1/employees` |
| Absences | `absences:read`, `absences:write` | `/v1/absences` |
| Time and attendance | `attendance:read`, `attendance:write` | `/v1/attendance` |
| Scheduling | `scheduling:read`, `scheduling:write` | `/v1/scheduling` |
| Annualised working time | `annualisation:read`, `annualisation:write` | `/v1/annualisation` |
| Budget & payroll costs | `budget:read`, `budget:write` | `/v1/budget` |
| BDESE (economic and social database) | `bdese:read` | `/v1/bdese` |
| Documents | `documents:read`, `documents:write` | `/v1/documents` |
| Electronic signatures | `signatures:read`, `signatures:write` | `/v1/signatures` |
| Payroll (export) | `payroll:read` | `/v1/payroll` |
| Swiss payroll | `swiss_payroll:read` | `/v1/swiss-payroll` |
| Scheduled exports | `reports:read` | `/v1/exports` |
| Flex Office (reading the whole module) | `flex_office:read` | `/v1/flex-office` |
| Flex Office: desk bookings, parking, catering, visits and visitors, meetings | `office_bookings:write`, `office_parking:write`, `office_meals:write`, `office_visits:write`, `office_rooms:write` | `/v1/flex-office` |
| Organisation (Referential group) | `org:read`, `org:write` | `/v1/org` |
| Flex Office: workstations, meeting rooms (Referential group) | `office_desks:write`, `office_rooms_config:write` | `/v1/flex-office/desks`, `/v1/flex-office/rooms` |

![The Scopes card of the documentation: Data and Referential groups, each resource with its scope codes, for example employees:read and employees:write](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-developer-guide-02.en_.png?resize=800%2C365&quality=80&ssl=1)
API scopes and their codes.

## 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).

| Status | `error_code` | Meaning |
| --- | --- | --- |
| 401 | `JETON_ABSENT` | `Authorization` header missing, or a value that does not start with `illz_`. |
| 401 | `JETON_INVALIDE` | Unknown value: copy error, token regenerated or revoked. |
| 401 | `JETON_EXPIRE` | Expiry date passed. |
| 403 | `JETON_DESACTIVE` | Token deactivated (including an expired token, after the nightly run). |
| 403 | `CREATEUR_INDISPONIBLE` | The token's creator is no longer active. |
| 403 | `SCOPE_MANQUANT` | Scope missing from the token; `data.required_scope` names it. |
| 403 | `FONCTIONNALITE_NON_INCLUSE` | The subscription does not include API access. |
| 413 | `TAILLE_DE_REQUETE` | Request larger than 5 MB; `data.max_bytes` gives the limit. |
| 429 | `LIMITE_DE_DEBIT` | Token's per-minute limit reached. |
| 429 | `LIMITE_JOURNALIERE` | The day's 10,000 requests reached; `data.reset_at` gives the reset time. |
| 429 | `LIMITE_DE_DEBIT_TENANT` | The company's 600 requests per minute reached, all tokens combined. |
| 429 | `PLAFOND_DE_CONSOMMATION` | The period's safety cap reached, until the next period. |

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).

![The Collaborateurs card of the documentation: each operation with its GET, POST, PUT or DELETE method, its path under /v1/employees, its summary and the scope required](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/api-developer-guide-03.en_.png?resize=800%2C287&quality=80&ssl=1)
A domain's operations, with the scope required.

## 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](https://illizeo.com/en/centre-aide/webhooks-receiving-and-verifying/).
- Files of reports scheduled on the “Pickup via API” channel are retrieved through `/v1/exports` for 30 days (see [Scheduling a report](https://illizeo.com/en/centre-aide/people-analytics-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.

### *Similaire*