---
title: The help desk API
description: File, follow and reply to help desk tickets from your own tools, change their status and priority, write internal notes and read published articles through Illizeo’s public API.
url: "https://illizeo.com/en/centre-aide/help-desk-api/"
updated: "2026-11-20"
category: Help desk
---

# The help desk API

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

1. Open **Settings › Help center › Services** and click the service.
2. In the **Identity** section, under **Public API**, switch the toggle to **Open to the API**.
3. Click **Save**.

![Identity section of a service: Open to, State, then Public API with the Open to the API toggle, the sentence API tokens and webhooks only reach the services opened here, and the Save button](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-api-01.en_.png?resize=800%2C189&quality=80&ssl=1)
Opening a service to the API

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](https://illizeo.com/en/centre-aide/help-desk-webhooks/)). |

![New API token form, Data group: Help center — tickets ticked for read and write, internal notes unticked, knowledge base articles ticked for read, webhook subscriptions unticked](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-api-02.en_.png?resize=800%2C191&quality=80&ssl=1)
The help desk scopes of a token

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.

![API documentation in the application, Help center card: its introduction then the twelve operations, each with its method, its address under /v1/helpdesk, its summary and its scope](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-api-03.en_.png?resize=800%2C494&quality=80&ssl=1)
The help desk operations in the API documentation

## 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 `langue` given. 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 by `GET /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 optional `statut` changes 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. `statut` is 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.

![Agent’s page of ticket AST-000071: API channel, no agent, then the conversation: automatic reply, team reply marked via API · Supervision, an agent’s internal note, requester’s reply written through the API](https://i0.wp.com/illizeo.com/wp-content/uploads/2026/11/centre-assistance-api-04.en_.png?resize=800%2C672&quality=80&ssl=1)
A ticket filed and followed through the API, as the agent sees it

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](https://illizeo.com/en/centre-aide/help-desk-major-incidents-and-problems/), and a [catalogue request](https://illizeo.com/en/centre-aide/help-desk-service-catalogue/) 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](https://illizeo.com/en/centre-aide/help-desk-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](https://illizeo.com/en/centre-aide/api-monitoring-and-troubleshooting-a-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](https://illizeo.com/en/centre-aide/help-desk-webhooks/).

### *Similaire*
