What the TOPdesk API does and does not return

The official TOPdesk API documentation is at developers.topdesk.com. It is thorough, and the API does what you expect. Some things only become clear after you have worked with it for a while, and they can mean rethinking your reporting plans. The points below came up while building a dashboard on it.

What is readily available

Incidents are the easy part. You get them with their category and subcategory, status, priority, line, operator group, operator, call date, completed date, closed date and the SLA fields. With those fields you can report on inflow, resolution time, SLA compliance by priority and the age of your oldest open incident.

Changes and their change activities are available too, as are operational activities, assets with their type, location and status, and knowledge items with their status and whether they are visible in the Self-Service Portal. Operators can be retrieved along with their permission groups, which show which operators hold a paid licence. The permission groups do not tell you whether such an account is actually in use; for that you need to bring together data from several modules.

The REST API does not return an incident’s route

The missing history is the most important limitation, and most reporting plans run into it. The REST API gives you the current state of an incident. You see which operator group and which operator have it and what its status is at the moment you ask.

You do not see the route it took to get there. The API cannot tell you that incident 4711 started with the first line, spent eleven days with network management and then came back. In TOPdesk you can see those handovers on the Audit Trail tab of the incident card, but at the time of writing (September 2026), the REST API does not return them.

You cannot answer “Where does work get stuck?” with the REST API alone. Management often wants that question answered, because resolution time builds up where work gets stuck.

With the REST API, the only option is to track the history yourself, and your timeline then only starts at the moment you connect. For the period before you connected, there is no way to build it up afterwards. So if you want such a timeline, start early, because it becomes more useful the longer it runs.

Paths differ by licence and version

The incidents API is the same everywhere, but the rest varies. Which endpoints are available for changes, assets and knowledge items depends on which modules are in your licence and on your TOPdesk version.

You cannot assume that a path exists. If an environment has no Asset Management, the path for assets does not exist, and you get an error where you might expect an empty list. First check which paths the environment itself offers, rather than relying on the general documentation.

401 and 403 mean different things

Knowing the difference can save you hours. A 401 means TOPdesk does not accept the login. The cause may be a wrong username, a revoked application token (an application password in older TOPdesk versions) or an account without the REST API permission. A 403 means the login is fine but you are not allowed to do this, because the operator does not have read permission for that module.

So if you get a 403, there is no need to replace the application token. Check that operator’s permission groups to see which module is missing. Mixing the two up once while building AureaDesk cost a whole afternoon.

Pagination in large environments

In an environment with a few thousand incidents you will not notice anything, but large, busy environments can handle pagination differently from what a small test suggests. The sync can then hang, or you miss part of the data.

Do not test against your own environment alone. What works on a few hundred incidents can behave differently on tens of thousands, and you often only find out when the integration is in use.

Also expect the first full sync to be heavier than you think. Pulling a large list in a single pass on a small server runs into memory limits, so fetch it in parts.

What you need in order to connect

At the time of writing, you do not need a special integration licence; check this against your own TOPdesk contract. Instead, you create an API account. An API account is an operator used only for the integration, with API access and read permission for the modules you need. You create an application token for it, and the integration uses that to sign in.

Do this with a separate operator, not with a colleague’s account. The logs then show at a glance which requests came from the integration. You can also disable the API account at any time without locking anyone out of their own account.

Keep permissions as narrow as possible. Reporting does not need write access to data, and a read-only integration cannot change anything in your TOPdesk. The integration does read data through the API, so let your TOPdesk administrator know it is there.

Building a dashboard on the REST API

The REST API is good enough for a proper dashboard, but building one takes longer than it seems after a first test. If you want to know where work gets stuck, you will have to track the history yourself. For each environment you also need to check what it actually offers, rather than relying on the general documentation. After a new TOPdesk version, check again which paths are available.