---
title: Scheduling public API and webhooks
description: Read and write the schedule through the Illizeo public API v1, and receive shift changes through webhooks.
url: "https://illizeo.com/en/centre-aide/scheduling-api-and-webhooks/"
updated: "2026-11-01"
category: Scheduling
---

# Scheduling public API and webhooks

Your tools can read the schedule, place drafts in it and publish, through the Illizeo public API v1. Webhooks tell them when a shift changes. This article is for people who integrate Illizeo with other software.

## Before you start

- The Scheduling module must be active, for the workspace and for the employees concerned.
- The public API must be included in your subscription.
- Tokens are created in **Manage Illizeo › API Tokens**. The API documentation is available there.
- Webhooks are created in **Manage Illizeo › Webhooks**.

![API Tokens page: API usage, Documentation and New token](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/scheduling-api-and-webhooks-01.en_.png?resize=800%2C500&quality=80&ssl=1)
The "API Tokens" page in Manage Illizeo.

## Token scopes

Two scopes concern Scheduling:

- **`scheduling:read`**: read shifts, open shifts and their applications, availability;
- **`scheduling:write`**: create, edit and delete drafts, and publish.

A token acts under the identity of the person who created it. It has their rights and their scope, at the same level as on screen:

- reading requires the "Schedule: read (Access), create and edit shifts (Execute) of one’s population" right (`sch_planning`) at the Access level;
- writing a draft requires the Execute level;
- publishing requires the Admin level.

An employee outside that scope responds as not found (404).

## Routes

Read (`scheduling:read`):

- `GET /v1/scheduling/shifts`: the shifts of a period;
- `GET /v1/scheduling/shifts/{shift}`: one shift or open shift;
- `GET /v1/scheduling/open-shifts`: open shifts and their applications;
- `GET /v1/scheduling/availabilities`: declared availability.

Write (`scheduling:write`):

- `POST /v1/scheduling/shifts`: create a draft;
- `PUT /v1/scheduling/shifts/{shift}`: edit a draft;
- `DELETE /v1/scheduling/shifts/{shift}`: delete a draft;
- `POST /v1/scheduling/publications`: publish a batch of drafts.

## Reading the schedule

Each read covers a period: `from` and `to`, in YYYY-MM-DD format. The period covers at most 43 days, both ends included. Beyond that, the API responds 422 (`PERIODE_TROP_LONGUE`).

`GET /v1/scheduling/shifts` also accepts filters: `employee_id`, `employment_id` (the contract), `office_id` (the location), `status` and `published`. The statuses are `draft`, `published`, `confirmed`, `rejected` and `cancelled`. Results are paginated: 100 per page by default, 500 at most (`per_page`, `page`).

## Writing: drafts only

The API goes through the same checks as the application: conflicts, short notice, rights, scope.

- **Drafts only.** An integrator creates, edits and deletes drafts. A shift that has already been sent out is changed in Illizeo: the API responds 409 (`SHIFT_NON_BROUILLON`).
- **No recurrence in v1.** A recurrence rule (`recurrence`) or a series scope (`scope`) is refused (422).
- **Short notice.** If the week starts soon, the API responds 409 (`PREAVIS_COURT`). Send the request again with `confirm_short_notice: true` to confirm.
- **Contract dates.** A shift outside the contract dates is refused (422), as on screen.

## Publishing

`POST /v1/scheduling/publications` takes a batch name (`name`), an optional note (`note`) and the list of drafts (`shift_ids`).

If an active workflow on the "Schedule published" trigger covers the person who created the token, the batch waits for its decision: the response carries `status = pending_approval`. Otherwise, the batch is published immediately and employees are notified. This is the default case: the workflow provided by Illizeo is inactive. A workflow in which no one can approve the batch is cancelled, and the batch is published directly. See [Creating and publishing a schedule](https://illizeo.com/en/centre-aide/scheduling-create-and-publish/).

## Webhooks

Subscribe a webhook to the whole Scheduling family, or to specific events.

![Webhooks page with the Documentation and New webhook buttons](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/scheduling-api-and-webhooks-02.en_.png?resize=800%2C500&quality=80&ssl=1)
The "Webhooks" page in Manage Illizeo.

- `shift.published`: a shift is published, directly or through the workflow. One event per shift in the batch.
- `shift.updated`: a shift that has been sent out changes (date, times, contract, location, position or status, cancellation included). The `changed` field says which.
- `shift.unpublished`: a shift that has been sent out becomes a draft again, through unpublishing or withdrawal of the batch.
- `shift.deleted`: a shift that has been sent out is deleted, or given back by the employee.
- `shift.confirmed` and `shift.rejected`: the employee's response.
- `open_shift.claimed`: a shift is created from an open shift for an employee (claim, accepted application, assignment).
- `shift.replacement_completed`: a shift changes holder after a handover or a swap. One event per transferred shift.
- `shift.checked_in`: the holder starts the shift.
- `shift.completed`: the holder completes the shift. This event is sent only once per shift.

`shift.checked_in` and `shift.completed` also give `outside_zone` (action outside the location zone) and `mode` (shift status or Attendance clocking).

## What an event contains

Each event carries the core of the shift: `shift_id`, `employee_id`, `employment_id`, `date`, `start_time`, `end_time` (HH:MM, in the schedule's time zone), `all_day`, `office_id`, `status`, `is_open` and `open_shift_id`. An open shift (`is_open`) has neither employee nor contract.

Event-specific fields are added: `publication_id`, `changed`, `responded_at`, `application_id` and `source`, `replacement_id`, `replacement_type` and the previous holder, `checked_in_at` or `completed_at`.

## Good to know

An event contains nothing personal: no name, no response note, no GPS location. For details, read the shift again with `GET /v1/scheduling/shifts/{shift_id}`, with your token's rights.

### When nothing is sent

- **Drafts**: they send nothing. What an integrator receives is what employees see.
- **Module off**: if Scheduling is deactivated for the workspace, or withdrawn from the shift's employee, no event is sent.
- **After saving**: an event is sent only once the action has been saved. If sending fails, the action does not fail: the failure is logged.

### *Similaire*