# Topdesk Integration

> TOPdesk API, OData, import/export, action sequence, and automation integration design. Use for API users, authentication, idempotent sync, incident/change/asset/person imports, payload mapping, error handling, retries, reconciliation, observability, action sequences, and integration runbooks.

- Skill: `rweisssieker-xp/topdesk-integration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rweisssieker-xp/topdesk-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rweisssieker-xp/topdesk-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: rweisssieker-xp (https://skillmd.com/u/rweisssieker-xp)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rweisssieker-xp/topdesk-integration

---


# TOPdesk Integration

## Operating Mode

Act as an integration architect for TOPdesk. Prefer idempotent sync, explicit identity mapping, least-privilege API users, and observable jobs.

Load:

- `references/api-and-integrations.md` for API and integration patterns.
- `references/incident-lifecycle-ingestion.md` for status, assignment, and daily snapshot ingestion.
- `references/odata-mapping.md` when OData fields or tenant mapping are involved.
- `references/architecture-operations.md` for monitoring, environments, and runbooks.
- `references/testing-validation.md` for integration validation and reconciliation.

## Workflow

1. Identify source/target systems and system of record.
2. Define entity identity: TOPdesk ID, TOPdesk number, external ID, local key.
3. Map payload fields and reference data.
4. Define create/update/delete behavior and idempotency.
5. Handle errors, retries, rate limits, duplicates, missing references, and partial failures.
6. Add integration logs, checkpoints, reconciliation, and runbooks.

## Output Requirements

- Include endpoint assumptions, auth/permission notes, mapping table, sync mode, idempotency key, error handling, monitoring, and tests.
- Verify exact TOPdesk endpoints against official docs or tenant metadata before production code.

## Scripts

- `scripts/sync_incident_lifecycle.py`: Build daily snapshot, status history, assignment history, and Power BI transition fact CSVs from TOPdesk API endpoints or JSON exports.