Your tools — monitoring, website, ERP, n8n, Power Automate — can work directly in the help desk: file a ticket when an alert fires, find it again, reply on the team’s side or on behalf of the requester, change its status and priority, write an internal note and read the published articles of the knowledge base. This article describes that part of Illizeo’s public API. It is for the developers who build the integration and for the help desk administrator who authorises it.
Before you start #
- The help desk module must be installed, and your subscription must include API access.
- The help desk administrator opens the services concerned to the API (see below): a token never reaches a closed service.
- The token is created under Settings › Manage Illizeo › API Tokens (see Creating and managing API tokens). It acts on behalf of the person who creates it: that person must hold, in the role matrix, Help center agent or Administer the help center, at the Access level to read and the Execute level to write, and the module must be open to them.
- The API address, authentication, response envelope and rate limits are common to the whole API: see Public API: developer guide.
Opening a service to the API #
Every service is closed to the API by default. Opening it requires the Administer the help center right at the Execute level.
- Open Settings › Help center › Services and click the service.
- In the Identity section, under Public API, switch the toggle to Open to the API.
- Click Save.

As the screen reminds you, API tokens and webhooks only reach the services opened here. Closing a service again applies from the next call: its tickets and articles then answer 404, and it no longer sends webhooks. Opening and closing are recorded in the activity log.
Creating the integration’s token #
Under Settings › Manage Illizeo › API Tokens, click New token. Choose the Name with care: it signs what the integration writes. A token named “Supervision” replies under the “via API · Supervision” mark on the ticket page, and the e-mail the requester receives is signed “Supervision”. Then, in the Data group, tick the help desk scopes the integration needs:
| Scope (screen) | Code | What it opens |
|---|---|---|
| Help center — tickets (Read) | helpdesk_tickets:read |
List services and tickets; read a ticket, its public messages and its public timeline. |
| Help center — tickets (Write) | helpdesk_tickets:write |
File a ticket, reply (on the team’s or the requester’s side), change the status and priority. |
| Help center — internal notes (Read) | helpdesk_notes:read |
Read internal notes, on their own or with the ticket. |
| Help center — internal notes (Write) | helpdesk_notes:write |
Write an internal note. |
| Help center — knowledge base articles (Read) | helpdesk_articles:read |
List and read published articles. |
| Help center — webhook subscriptions (Write) | helpdesk_webhooks:write |
Subscribe to the help desk webhooks and unsubscribe (see Help desk webhooks). |

Write does not include read: an integration that files tickets and then follows them ticks both. Without a helpdesk_notes scope, no internal note goes out or comes in through the API. These scopes only appear if the help desk module is enabled.
What the token reaches #
The token reaches the services open to the API, and among them those its creator reaches in Illizeo:
- created by an agent: the services they are an agent of. The token acts there as on screen: on an unassigned ticket, on the agent’s own tickets, and on all the tickets of a service they manage. A colleague’s ticket can be read, given a note or written to on behalf of the requester; replying on the team’s side or changing its status or priority is refused (422);
- created by the help desk administrator (“Administer the help center” at the Execute level): every service open to the API, with the right to act on every ticket.
A ticket or article outside this reach answers 404, as if it did not exist. If the creator’s rights change, the token’s follow from the next call.
The operations #
All addresses start from https://api.illizeo.app, with the Authorization: Bearer illz_… header. In the addresses, {ticket} is a ticket’s number (AST-000812) or its identifier, and {article} an article’s slug or its identifier.
| Operation | Scope | Use |
|---|---|---|
GET /v1/helpdesk/services |
helpdesk_tickets:read |
The services reached, with their request types and the fields of their form. |
GET /v1/helpdesk/tickets |
helpdesk_tickets:read |
The list of tickets, without their messages. |
GET /v1/helpdesk/tickets/{ticket} |
helpdesk_tickets:read |
A ticket, its messages and its public timeline. |
POST /v1/helpdesk/tickets |
helpdesk_tickets:write |
File a ticket. |
PATCH /v1/helpdesk/tickets/{ticket} |
helpdesk_tickets:write |
Change the status or the priority. |
POST /v1/helpdesk/tickets/{ticket}/messages |
helpdesk_tickets:write |
Reply, on the team’s side or the requester’s side. |
GET /v1/helpdesk/tickets/{ticket}/notes |
helpdesk_notes:read |
The ticket’s internal notes. |
POST /v1/helpdesk/tickets/{ticket}/notes |
helpdesk_notes:write |
Write an internal note. |
GET /v1/helpdesk/articles |
helpdesk_articles:read |
Search the published articles. |
GET /v1/helpdesk/articles/{article} |
helpdesk_articles:read |
Read a published article. |
POST /v1/helpdesk/webhooks, DELETE /v1/helpdesk/webhooks/{id} |
helpdesk_webhooks:write |
Subscribe to the help desk webhooks, unsubscribe. |
The Documentation button of the tokens page describes each operation in the Help center card; its openapi.json button gives the full contract.

Reading tickets #
The list accepts the filters statut (one or more codes separated by commas), service_id, reference_externe and modified_since (an ISO 8601 date; modifie_depuis is accepted too). A ticket counts as modified when its record changes or when activity visible to the token is added to it: a message, a status change. Tickets come by ascending identifier, 50 per page (limit, 200 at most); the response carries items, next_cursor and has_more. To synchronise another system, read again with cursor set to next_cursor as long as has_more is true.
A ticket carries in particular numero, objet, description, statut, priorite, service, type, canal, demandeur (salarie or externe, with name and e-mail), agent, its dates (depose_le, modifie_le, resolu_le, clos_le, in ISO 8601 UTC), its first-response and resolution echeances, the reponses_au_formulaire, the reference_externe, and the numbers of the parent (the request it is a task of) and of the major incident it is attached to, or null. Keys are in French, as in the application; values are codes:
| Field | Codes (label on screen) |
|---|---|
statut |
new (New), taken (In progress), waiting_requester (Waiting for the requester), waiting_third_party (Waiting for a third party), resolved (Resolved), closed (Closed) |
priorite |
low (Low), normal (Normal), high (High), critical (Critical) |
canal |
internal (Employee space), portal (Portal), email (E-mail), agent (Filed by an agent), widget (Website widget), teams (Microsoft Teams), api (API) |
Reading a ticket adds messages — each with cote (equipe, demandeur or note), auteur, via_api, le, corps in HTML and pieces (name and size; the files are downloaded in Illizeo) — then chronologie, the timeline the requester sees. Internal notes only appear there with the helpdesk_notes:read scope.
Filing a ticket #
The body of POST /v1/helpdesk/tickets carries service_id and objet (required), if needed type_id, description, priorite, reponses_au_formulaire and reference_externe (your own identifier, for example the alert’s), and the demandeur: email (required), nom and langue.
POST /v1/helpdesk/tickets
Authorization: Bearer illz_…
Content-Type: application/json
{
"service_id": 3,
"objet": "File server unreachable",
"description": "FS-01 has not responded since 08:42.",
"priorite": "high",
"demandeur": { "email": "supervision@your-company.co.uk", "nom": "Supervision", "langue": "en" },
"reference_externe": "ALERT-20261120-0042"
}
The response, a 201, returns the ticket and its thread ("numero": "AST-000812", "statut": "new", "canal": "api"…). The ticket enters the queue like any other: help desk rules, service commitments, acknowledgement to the requester.
- The requester is given by their e-mail address. If the service is open to employees and the address belongs to a single active employee who may file requests (“Help center requests” right at the Execute level), it is that employee. Otherwise, if the service is open to external people, it is an external person, created on their first request in the
languegiven. Otherwise, the response is 422. An alert can therefore carry the address of the tool that raises it. - The type is optional. If given, it must be active and offered to this requester, and its required fields must appear in
reponses_au_formulaire, under the keys returned byGET /v1/helpdesk/services. - The priority, if omitted, is the type’s, otherwise Normal; it is raised to the minimum set by the client organisation’s contract, if there is one.
- A service closed to the API, outside the token’s reach or inactive is refused (422 on
service_id).
Replying #
POST /v1/helpdesk/tickets/{ticket}/messages takes a corps in HTML, cleaned on arrival, and a cote.
"cote": "equipe": a public reply from the team, marked “via API ·” followed by the token’s name, and sent to the requester in an e-mail signed with that name. It counts as the first response for service commitments, but does not take the ticket: it keeps its agent, or still has none. An optionalstatutchanges it in the same move; the requester then receives a single e-mail. The reply is refused (422) on a closed ticket, on a ticket awaiting approval and on a colleague’s ticket. On a task of a catalogue request, it is written on the request, as on screen."cote": "demandeur": the reply is written on behalf of the ticket’s requester, for example from your customer portal. It follows the rules of a requester’s reply: a ticket waiting for the requester goes back to In progress; a ticket resolved within the reopening delay is reopened; after that delay, or on a closed ticket, a follow-up is created and receives the message.statutis not accepted on this side, nor a reply on a task.
POST /v1/helpdesk/tickets/AST-000812/messages
{ "cote": "equipe", "corps": "<p>The probe is back to normal.</p>", "statut": "resolved" }
The response, a 201, carries message (the message written, with "via_api": true) and ticket, the ticket that received it: the same one, its follow-up, or the request of a task.

On the ticket page, agents see the API channel and the via API · Supervision mark on each of the integration’s messages; the timeline names it too (“Supervision (API) replied”). The requester sees the same mark in their request.
Changing the status or the priority #
PATCH /v1/helpdesk/tickets/{ticket} takes statut, priorite or both, all or nothing. The rules are those of the screen:
- a closed ticket no longer changes; a resolved ticket can only go back to In progress or be closed; a ticket only becomes New again from In progress;
- a ticket awaiting approval changes neither status nor priority; the status does not change on a ticket attached to an open major incident, and a catalogue request is neither resolved nor closed while one of its tasks is open (422, with the reason);
- the priority no longer changes on a resolved or closed ticket, and does not go below the minimum of the client organisation’s contract;
- a colleague’s ticket is refused (422).
The response, a 200, returns the ticket without its thread. In a single call, the priority is handled before the status: to reopen a resolved ticket and change its priority, make two calls, status first. The change is signed with the token’s name in the timeline. "statut": "taken" gives the ticket to nobody, and "statut": "new" returns it to the queue, without an agent.
Internal notes #
With helpdesk_notes:write, POST /v1/helpdesk/tickets/{ticket}/notes and a corps in HTML write an internal note signed with the token’s name, on any ticket reached, even closed, awaiting approval or held by a colleague. It changes neither the status nor the agent, and is never shown to the requester. With helpdesk_notes:read, GET …/notes returns the notes alone, and reading a ticket mixes them with its messages ("cote": "note").
Knowledge base articles #
With helpdesk_articles:read, the integration reads the published articles of the services reached, in their current version, for example to suggest answers on your website. GET /v1/helpdesk/articles accepts q (the same search as the space’s help), service_id, public (interne or externe; internal and external are accepted too) and langue, and returns for each article its title, an excerpt, the language served, its visibility and its category. GET /v1/helpdesk/articles/{article} returns the whole article, body in HTML; repli is true when the language requested is missing and another one is served. A draft, an archived article or one outside the token’s reach answers 404, and an article attached to no service is not served. See The knowledge base.
Refusals #
| Response | Cause |
|---|---|
403, SCOPE_MANQUANT |
The operation’s scope is not ticked on the token; data.required_scope names it. A read-only token cannot write anything. |
403, MODULE_NOT_ACTIVE or MODULE_DISABLED_FOR_EMPLOYEE (code field) |
The help desk is not enabled in the space, or not open to the token’s creator. |
| 403 | The token’s creator does not hold the screen right at the right level: “Help center agent” or “Administer the help center” (the latter, at the Execute level, for webhooks). |
404, NOT_FOUND |
Ticket or article outside the token’s reach, or in a service closed to the API. |
422, VALIDATION_ERROR |
A field refused, detailed in errors; or a screen rule, whose reason is in message, in the language requested by X-Locale or Accept-Language, otherwise in the token creator’s language. |
Good to know #
- API actions are signed by no person: the token’s name signs them in the thread and the timeline. That name is copied onto each message: renaming the token does not change messages already written. In the activity log, changes are recorded under the token creator’s name.
- A team reply written through the API on an agent’s ticket does not send them a notification.
- Attachments cannot be sent through the API: messages only name them.
- Each call counts as one unit in the API platform usage, as does each webhook delivered (see Monitoring and troubleshooting an API token).
- The API channel appears in reporting and in the “Channel” condition of automations.
- To be told what happens to tickets rather than reading them again, subscribe to their webhooks: see Help desk webhooks.
