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.

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.

Webhooks #

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

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