What the TOPdesk API does and does not return

The TOPdesk API is documented properly and does what you expect. But there are a few things in it you only discover after working with it for a while, and they can upend your reporting plans. This is what surfaced while building a dashboard on top of it.

What comes out without any fuss

Incidents are the easy part. You get them with their category and subcategory, status, priority, line, operator group, operator, creation date, closing date and the SLA fields. Enough for intake, resolution time, SLA compliance per priority, and the question of how long the oldest open thing has been sitting there.

Changes and their underlying activities come out too, as do 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 pulled in including their permission groups, which is handier than it sounds: that is how you spot paid accounts that have done nothing for months.

What does not come out: the history

This is the important one, and the one that derails most plans. The API gives you the current state of an incident. Which operator group has it now, what status it has now, who it sits with now.

What you do not get is the path it took. You cannot ask the API that incident 4711 first sat with the first line, then eleven days with network management, and then came back. Those handovers are in TOPdesk itself, but the API does not hand them over.

That has an annoying consequence for your reporting: the question "where does work get stuck" cannot be answered with an API connection alone. And it is usually the question management is actually waiting for, because that is where resolution time hides.

The only way out is to track it yourself. You fetch the current state regularly, compare it with what you saw last time, and write down the difference. From that moment you are building a timeline. The drawback is obvious: about the period before you connected you know nothing, and you never get it back. So anyone who wants this should start early — the value grows with time.

Paths differ per licence and per version

The incidents API is the same everywhere. Outside of that it gets messier. Which endpoints are available for changes, assets and knowledge items depends on which modules are in your licence and on your TOPdesk version.

In practice that means you cannot build on assumptions. If an environment has no Asset Management, that path simply is not there, and you get an error rather than a tidy empty list. So always check the API reference of the environment itself, not the general documentation.

401 and 403 really do mean different things

A detail that can save you hours. A 401 means your credentials are wrong: wrong username, or an application password that has been revoked. A 403 means your credentials are fine but you are not allowed to do this: the operator has no read rights on that module.

So on a 403, do not go fiddling with the password. Go to that operator's permissions and see which module is missing. Those two got mixed up once while building AureaDesk, good for a wasted afternoon.

Pagination in large environments

On an environment with a few thousand incidents you notice nothing. On one with sixty thousand you do. Large, busy environments can respond to pagination differently than a small test would lead you to expect, and if your code assumes every page is neatly full until the last one, you either stall or quietly miss records.

The lesson: do not test only on your own environment. What works on a few hundred incidents can behave differently on tens of thousands, and you find out at precisely the wrong moment.

Also count on a first full fetch being heavier than expected. Pulling sixty thousand incidents on a small server runs into memory limits. So do not build that as one big operation.

What you need in order to connect

You do not need a special integration licence. What you create is an operator that exists purely for the connection, with API access and read rights on the modules you want to read. You generate an application password for it, and that is what your connection uses.

Do this with a separate operator, not with a colleague's account. Two reasons. In the logs you can see immediately that it was the connection and not a person. And you can switch it off whenever you like without costing anyone their own access.

Keep the rights as narrow as possible. Reporting never needs write access, and a connection that only reads cannot break anything in your process by definition.

What it comes down to

The API is good enough to build a proper dashboard on, as long as you accept two things. You have to track history yourself if you want to know where work gets stuck, and you have to check per environment what is available rather than trusting the documentation.

That first point is the reason not to wait. Every month you have not connected is a month you cannot look back on later.