TOPdesk

Use an application password, never the operator's own.

1. In TOPdesk open Modules → Supporting Files → Operator Management, pick the operator the integration should act as, and on its card create an Application Password. TOPdesk shows it once.
2. Give that operator exactly the permission groups the agent needs — TOPdesk enforces them per module, and a missing one produces a 403 rather than an empty list, which is at least honest.
3. Set TOPDESK_URL to your instance root (e.g. https://mycompany.topdesk.net, no trailing slash), TOPDESK_USERNAME to the operator login name and TOPDESK_APP_PASSWORD to the generated value.

FIQL is the query language, and it is worth learning. query=status==firstLine;caller.branch.name==Berlin filters server-side. ; is AND, , is OR, == is equals, =lt=/=gt= compare, =in= takes a list. The tools below pass a query string through verbatim.

Paging is start and page_size (max 100 on most endpoints), not page numbers. TOPdesk returns 206 Partial Content when more rows exist and 204 No Content when the result is empty — a 204 with no body is a successful search that matched nothing.

fields cuts the response down. Incident records are large; fields=id,number,briefDescription,status,caller.dynamicName keeps the answer readable.

Writes: topdesk_create_incident opens a real incident, which notifies whoever the process assigns it to.