Ellipse Gradient for Header

TOPdesk Integration Guide

Connect TOPdesk service-management resources with enterprise applications through REST APIs, scheduled workflows, and verified event-driven capabilities.

TOPdesk integration options at a glance

TOPdesk provides REST APIs for reading and modifying service-management resources such as Incidents, Persons, Operators, Assets, Changes, and Problems. Martini can consume these APIs through reusable workflows that manage authentication, pagination, mapping, validation, retries, and synchronization checkpoints. TOPdesk may provide event-driven or outbound notification capabilities for selected use cases, but universal webhook coverage is not confirmed and must be verified for each tenant and object. Attachments are supported in the product, while object-level attachment API operations require confirmation. API token authentication, restricted integration accounts, and Martini secrets provide the foundation for secure integrations.

Integration pointSupported by TOPdesk?Common use casesHow Martini supports it
REST APIsYesRead, create, and update TOPdesk Incidents, Persons, Operators, Assets, Changes, Problems, and other tenant-supported resources. Use REST APIs for scheduled synchronization and API-led service requests.Martini can consume TOPdesk REST endpoints in workflows, centralize request handling, paginate responses, transform payloads, and expose APIs that invoke TOPdesk operations.
Webhooks and outbound callbacksLimitedTOPdesk may provide event-driven or outbound notification capabilities for selected use cases, but universal coverage across objects and events is not confirmed.Martini can receive webhook-style notifications through an exposed API where the TOPdesk tenant supports the required event, payload, authentication, and delivery behavior. Otherwise, scheduled polling is used.
File and attachment APIsLimitedTOPdesk supports attachments associated with service-management records in the product, but endpoint coverage and operations vary by object and must be verified.Martini can transfer files when the relevant TOPdesk endpoint is confirmed, while applying content-type, size, privacy, and encoding rules.
AuthenticationYesTOPdesk REST integrations use API token authentication with an operator or integration account that has access to the required modules and objects.Martini stores the token as a secret, applies it to API requests, and keeps tenant-specific credentials and base URLs outside workflow logic.
Pagination and incremental synchronizationYesLarge resource collections should be retrieved through documented pagination and, where supported, incremental filters or timestamp-based synchronization.Martini workflows can loop through pages, maintain checkpoints or overlap windows, throttle requests, and preserve source identifiers for reconciliation.
Bulk and asynchronous APIsNot confirmedA general-purpose TOPdesk bulk or asynchronous API was not confirmed. Large transfers should use paginated REST calls unless a tenant-specific capability is verified.Martini can orchestrate controlled batches, checkpoints, bounded retries, and reconciliation workflows without assuming a bulk endpoint.
Database accessNoDirect access to the TOPdesk SaaS data store was not confirmed and should not be used as the primary integration method.Martini should consume supported TOPdesk APIs or confirmed export mechanisms rather than connecting directly to TOPdesk's database.
SDKsNot confirmedThe research notes confirm REST APIs but do not confirm a current TOPdesk SDK required for integration.Martini can integrate using HTTP-based API workflows and reusable mappings without requiring a TOPdesk-specific SDK.

How TOPdesk exposes data and business events

TOPdesk REST APIs

TOPdesk REST APIs provide the primary integration mechanism for reading and modifying service-management resources. Supported resources and operations can vary by API version, tenant configuration, permissions, and object.

Martini implementation pattern

Martini implementation pattern: a reusable workflow stores the TOPdesk base URL and API token in environment configuration, calls the required endpoint, follows pagination, validates the response, maps fields to a canonical model, and writes the result to the target system. Shared error handling distinguishes authentication, authorization, validation, rate-limit, timeout, and transient server failures.

Implementation sequence

Load the TOPdesk base URL and API token from secure configuration
Call the required TOPdesk REST endpoint
Follow the documented pagination or incremental retrieval parameters
Validate the response and required object fields
Resolve related Persons, Operators, Assets, or groups
Map TOPdesk data to the target model and apply business rulesaigned state transitions are

TOPdesk event notifications

TOPdesk may support event-driven or outbound notification capabilities for selected use cases, but universal webhook coverage for all objects and state transitions was not confirmed.

Martini implementation pattern

Martini implementation pattern: expose a controlled Martini API or webhook endpoint only after confirming the TOPdesk event, payload, authentication, retry behavior, and delivery guarantees. Treat notifications as triggers to retrieve the current TOPdesk object when the payload contains only an identifier, and use polling when the required event is unavailable.

Implementation sequence

Confirm the TOPdesk object, event type, payload, and tenant availability
Receive the notification at a protected Martini API endpoint
Validate authentication, payload structure, and source identifier
Retrieve the current TOPdesk resource when the notification is incomplete
Deduplicate the event using the source identifier and event metadata
Map the resource and invoke the downstream workflow

TOPdesk attachments

TOPdesk supports attachments associated with service-management records in its product experience. The exact API operations and coverage must be verified for the target object and environment.

Martini implementation pattern

Martini implementation pattern: when a supported attachment endpoint is confirmed, retrieve or submit the file as part of a controlled workflow, validate size and content type, apply privacy rules, and associate the file with the correct Incident, Change, Problem, or other resource.

Implementation sequence

Confirm attachment operations for the target TOPdesk object
Retrieve or receive the attachment metadata and content
Validate file size, content type, and permitted data classification
Map the attachment to the target object identifier
Transfer the file through the confirmed TOPdesk endpoint
Record the transfer result without logging sensitive content

Common TOPdesk integration patterns

Pattern 1: Create TOPdesk Incidents from monitoring alerts

When to use this pattern

Use this pattern when an external monitoring platform such as Datadog must create or update TOPdesk Incidents. Deduplication, alert correlation, priority mapping, assignment, and closure synchronization are central to the design.

Integration direction
Datadog
Martini
TOPdesk
Example Mapping
TOPdesk FieldCanonical FieldTarget Field
alert_idsourceAlertIdIncident external reference
alert_statuslifecycleStatusIncident status
severitypriorityIncident priority
host or serviceaffectedAssetIncident Asset
Martini implementation pattern

Expose a Martini API for alert intake, validate the payload, derive a deterministic incident key, and look up an existing TOPdesk Incident before creating one. Resolve the related Asset, Person, Operator, or operator group, map severity to tenant-specific priorities, and retry only transient failures. Store the TOPdesk Incident identifier for later acknowledgement and closure updates.

Martini capabilities used
  • APIs
  • workflows
  • data mapping
  • business rules
  • error handling
  • secrets

Pattern 2: Synchronize TOPdesk Incidents with ServiceNow

When to use this pattern

Use this pattern during platform coexistence, migration, or multi-platform operations where selected incidents and statuses must remain aligned between TOPdesk and ServiceNow.

Integration direction
TOPdesk
Martini
ServiceNow
Example Mapping
TOPdesk FieldCanonical FieldTarget Field
numbersourceIncidentNumberincident.correlationId
statuslifecycleStatusincident.state
prioritypriorityincident.priority
briefDescriptionsummaryincident.short_description
Martini implementation pattern

Poll TOPdesk incrementally or consume a verified notification, filter fields that may not leave TOPdesk, and map status and priority values through environment configuration. Use cross-system identifiers and field ownership rules to prevent loops, reconcile failed writes, and route permanent validation errors for review.

Martini capabilities used
  • scheduled workflows
  • API consumption
  • data mapping
  • configuration
  • idempotency
  • retry handling

Pattern 3: Synchronize directory users to TOPdesk Persons

When to use this pattern

Use this pattern when identity or HR changes must be reflected in TOPdesk Persons, including new users, changed contact data, organizational assignments, and controlled deactivation.

Integration direction
Microsoft Entra ID
Martini
TOPdesk
Example Mapping
TOPdesk FieldCanonical FieldTarget Field
idexternalPersonIdPerson external identifier
userPrincipalNameloginNamePerson email or login
departmentdepartmentNamePerson department
accountEnabledactivePerson active status
Martini implementation pattern

Retrieve changed users from the directory API, match existing TOPdesk Persons using a stable identifier, and map organizational values to TOPdesk departments or branches. Apply explicit rules for email changes, duplicates, missing references, and deactivation, then retry transient API failures without recreating already matched Persons.

Martini capabilities used
  • workflows
  • API consumption
  • data transformation
  • validation
  • business rules
  • error handling

Pattern 4: Coordinate TOPdesk Changes and Assets with deployment processes

When to use this pattern

Use this pattern when approved deployment or infrastructure changes must update TOPdesk Changes or associate Assets and Incidents, while preserving TOPdesk governance and auditability.

Integration direction
Deployment process
Martini
TOPdesk
Example Mapping
TOPdesk FieldCanonical FieldTarget Field
deploymentIdchangeReferenceChange external reference
approvalStateapprovalStatusChange status
assetIdaffectedAssetIdAsset reference
deploymentResultoutcomeChange completion or closure field
Martini implementation pattern

Receive deployment milestones through a Martini API or scheduled workflow, locate the related TOPdesk Change, validate that the requested transition is permitted, and associate supported Assets or Incidents. Do not bypass approval requirements; record correlation identifiers and route invalid transitions or missing objects to an operational exception path.

Martini capabilities used
  • API exposure
  • workflow orchestration
  • mapping
  • state validation
  • business rules
  • monitoring

Applications commonly integrated with TOPdesk

TOPdesk can be connected with adjacent enterprise applications when organizations need to synchronize service-management data, coordinate operational processes, or migrate between platforms. These scenarios use the relevant product APIs and Martini workflows rather than assuming a certified TOPdesk connector.

Application Scenario Direction Martini Pattern
ServiceNow Synchronize incidents, changes, service requests, or configuration information during coexistence, migration, or multi-platform operations. TOPdesk → Martini → ServiceNow Use scheduled or API-triggered workflows to retrieve changed TOPdesk objects, map statuses and references to ServiceNow models, apply ownership and conflict rules, and write results in both directions where required. Store cross-system identifiers to prevent duplicates.
Jira Software Link TOPdesk service incidents with software defects and development work so support and engineering teams can share status and references. TOPdesk → Martini → Jira Software Receive or poll TOPdesk Incident changes, transform incident fields into Jira issue fields, create or update linked issues, and synchronize selected status or resolution changes with correlation and retry handling.
Microsoft Entra ID Synchronize users and organizational attributes into TOPdesk Persons and support identity-aware service processes. Microsoft Entra ID → Martini → TOPdesk Retrieve changed directory users through the available Entra ID API, match them using stable identifiers, map department or branch values, and create, update, or deactivate TOPdesk Persons according to configured business rules.
Microsoft Active Directory Reconcile employee or directory information with TOPdesk Persons in organizations using on-premises identity infrastructure. Microsoft Active Directory → Martini → TOPdesk Use an appropriate directory-access mechanism or intermediary API, normalize identity attributes in Martini, resolve TOPdesk organizational references, and apply controlled create, update, and deactivation behavior.
Salesforce Surface TOPdesk service incidents to account or customer-service teams and synchronize customer or contact references. TOPdesk → Martini → Salesforce Poll or receive selected TOPdesk changes, filter confidential operational content, resolve Salesforce accounts and contacts, and synchronize approved incident summaries with deterministic matching and error queues.
SAP S/4HANA Link service incidents, assets, customers, or changes with enterprise business and asset-management processes. SAP S/4HANA → Martini → TOPdesk Orchestrate calls to both APIs, translate identifiers and organizational values, validate required TOPdesk fields, and update related objects only when state-transition and governance rules permit.
Microsoft Teams Notify support or operations teams about new, escalated, or resolved TOPdesk Incidents and provide links back to TOPdesk. TOPdesk → Martini → Microsoft Teams Poll TOPdesk or consume a verified TOPdesk notification, apply escalation and privacy rules, then invoke the relevant Microsoft API to publish a concise notification with correlation metadata.
Datadog Convert selected monitoring alerts into TOPdesk Incidents and synchronize acknowledgement or resolution state. Datadog → Martini → TOPdesk Expose a Martini API for alert intake, validate and deduplicate Datadog events, look up TOPdesk Assets or operator groups, create or update Incidents, and process selected reverse status updates.

How to build a TOPdesk integration in Martini

Objective

Establish a controlled connection to the TOPdesk tenant using the documented API token pattern and tenant-specific configuration.

Instructions in Martini

  • Store the TOPdesk base URL and API token in Martini environment configuration and secrets
  • Use a dedicated TOPdesk integration account with only required permissions
  • Confirm the authentication format, API version, modules, and accessible objects

Objective

Select a trigger that matches the confirmed TOPdesk capability and synchronization requirements.

Instructions in Martini

  • Use a scheduled workflow for polling and incremental synchronization
  • Use a Martini API endpoint for upstream systems such as monitoring platforms
  • Use TOPdesk event notifications only after confirming coverage and delivery behavior for the tenant

Objective

Retrieve the current TOPdesk object or notification-related resource reliably and completely.

Instructions in Martini

  • Call the required TOPdesk REST endpoint
  • Follow documented pagination parameters
  • Use checkpoints, overlap windows, or incremental filters where supported
  • Retrieve related Persons, Operators, Assets, or groups when their identifiers are required

Objective

Coordinate API calls, validation, branching, and downstream writes in a maintainable Martini workflow.

Instructions in Martini

  • Centralize common TOPdesk request and response handling
  • Separate transport failures from business validation failures
  • Apply correlation identifiers and preserve TOPdesk object IDs
  • Use controlled concurrency and bounded retries

Objective

Convert TOPdesk fields and tenant-specific values into a canonical model and target-system representation.

Instructions in Martini

  • Map statuses, priorities, categories, assignments, timestamps, and references explicitly
  • Filter confidential notes, descriptions, and attachments before sharing data
  • Keep custom fields and organizational values configurable
  • Preserve source-system metadata for traceability

Objective

Apply deduplication, ownership, transition, privacy, and relationship rules before writing changes.

Instructions in Martini

  • Use stable source identifiers or external references to prevent duplicate Incidents or Persons
  • Validate required fields and permitted status transitions
  • Resolve missing or inactive Persons, Operators, Assets, and groups according to defined rules
  • Prevent synchronization loops with field ownership and source markers

Common TOPdesk data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
IncidentsRepresent reported issues or service requests, including descriptions, status, priority, assignment, category, and related references.ServiceNow, Jira Software, Salesforce, Datadog, Microsoft TeamsMartini retrieves, creates, and updates Incidents through REST workflows, resolves related Persons, Operators, and Assets, filters sensitive content, and applies deduplication and status rules.
PersonsRepresent callers, users, contacts, and people associated with service processes.Microsoft Entra ID, Microsoft Active Directory, Salesforce, ServiceNowMartini matches Persons using stable identifiers, maps contact and organizational attributes, validates branches or departments, and handles create, update, or deactivation rules.
OperatorsRepresent TOPdesk agents responsible for handling Incidents and other service activities.ServiceNow, Microsoft Entra ID, Microsoft TeamsMartini looks up Operators and operator groups when assigning work, validates permissions and active status, and avoids hard-coding tenant-specific identifiers.
AssetsRepresent configuration items or organizational assets related to service delivery and incidents.SAP S/4HANA, ServiceNow, Datadog, SalesforceMartini resolves Asset references before Incident or Change updates, maps identifiers and ownership, and handles missing or inactive assets according to business rules.
ChangesRepresent planned changes managed through change-management processes, including status and approval-related information.ServiceNow, Jira Software, SAP S/4HANAMartini synchronizes approved fields, enforces state-transition rules, preserves audit identifiers, and avoids bypassing TOPdesk governance.
ProblemsRepresent root-cause or recurring-issue records associated with service management.ServiceNow, Jira Software, SalesforceMartini can retrieve and synchronize supported Problems, map relationships to Incidents, and apply tenant-specific field and status mappings.

Authentication and security considerations

API token authentication

TOPdesk REST integrations use an API token associated with an operator or integration account. Confirm the required authentication format, permissions, API version, and accessible modules for the target tenant.

Credential protection

Store the TOPdesk base URL and API token in Martini environment configuration and secrets rather than workflow definitions. Do not write authorization headers or token values to logs.

Least privilege and data protection

  • Use a dedicated TOPdesk integration account with only the permissions required by the workflows.
  • Protect incident descriptions, notes, personal information, and attachments according to organizational data policies.
  • Filter sensitive operational content before sending TOPdesk data to external applications.
  • Rotate credentials according to organizational policy and any applicable TOPdesk controls.

Operational considerations for TOPdesk integrations

Pagination and synchronization windows

TOPdesk collections may be paginated. Follow documented limits, maintain checkpoints or timestamps where supported, and use overlap windows when timestamp precision or ordering could cause missed updates.

Rate limits and retries

Confirm rate limits for the target environment. Throttle requests, limit concurrency, use exponential backoff for transient failures, and distinguish rate-limit or transport errors from permanent validation and authorization errors.

Idempotency and relationships

Use stable source identifiers and deterministic matching before creating Incidents or Persons. Resolve Persons, Operators, Assets, branches, categories, and operator groups before writing related objects.

Tenant-specific schemas

TOPdesk environments may differ in custom fields, required fields, statuses, priorities, categories, branches, departments, and permissions. Keep mappings configurable and validate them before production activation.

Testing and observability

Test representative objects, status transitions, missing references, pagination, attachments, and failure responses. Log safe correlation identifiers, TOPdesk object IDs, workflow execution IDs, retry counts, and final failure reasons.

Why use Martini instead of scripts or point-to-point integrations?

Reusable integration workflows

Martini centralizes TOPdesk authentication, pagination, response validation, mapping, business rules, and error handling in reusable workflows instead of duplicating logic across scripts.

Reliable orchestration

Scheduled, API-led, and selectively event-driven workflows can coordinate TOPdesk with monitoring, identity, CRM, development, and enterprise applications while preserving checkpoints and correlation identifiers.

Controlled transformation

Martini provides a maintainable place to normalize TOPdesk statuses, priorities, identifiers, relationships, custom fields, and sensitive content before data reaches another system.

Operational maintainability

  • Apply bounded retries and separate transient failures from business validation errors.
  • Keep tenant-specific configuration and secrets outside workflow logic.
  • Expose controlled APIs for upstream systems without requiring point-to-point TOPdesk logic in every application.
  • Support monitoring, troubleshooting, and controlled deployment of integration changes.

Frequently asked questions

How can TOPdesk be integrated with enterprise systems?

TOPdesk can be integrated primarily through its REST APIs, which support programmatic access to resources such as Incidents, Persons, Operators, Assets, Changes, and Problems. Organizations can use scheduled synchronization, API-led workflows, and selected event or outbound notification capabilities where those features are confirmed for the tenant. API token authentication is the documented REST integration pattern.

Can Martini integrate with TOPdesk?

Yes. Martini can consume TOPdesk REST APIs, expose APIs for upstream systems, orchestrate scheduled or event-triggered workflows, map and transform data, and handle validation, retries, checkpoints, and errors. No native Martini TOPdesk connector is documented in the supplied sources.

Do I need a connector to integrate TOPdesk with Martini?

No. A dedicated TOPdesk connector is not required. Martini can integrate using TOPdesk's confirmed REST APIs and API token authentication, with event or callback mechanisms used only where the required TOPdesk capability is available and verified.

Is there any extra Lonti cost to integrate TOPdesk with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate TOPdesk. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from TOPdesk, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.

Which TOPdesk integration methods should architects use?

REST APIs should be the primary method for new integrations. Scheduled workflows are appropriate for reliable polling and reconciliation. TOPdesk event-driven or outbound notification capabilities may be used for selected scenarios only after confirming object coverage, payloads, authentication, retries, and tenant availability. No official TOPdesk GraphQL or current SOAP API was confirmed.

Are TOPdesk webhooks or event notifications available?

TOPdesk may support event-driven or outbound notification capabilities for selected use cases, but universal webhook coverage for all objects and events was not confirmed. Verify the event, payload, authentication, retry behavior, and delivery guarantees. Martini can receive a verified notification or use scheduled REST polling when the required event is unavailable.

How does Martini synchronize TOPdesk data?

Martini can retrieve paginated TOPdesk REST responses on a schedule, use incremental filters or timestamps where supported, and maintain checkpoints or overlap windows. Workflows can map statuses, priorities, assignments, identifiers, and related objects, then write changes to another system while applying field ownership, deduplication, and reconciliation rules.

How are TOPdesk errors, retries, and duplicate Incidents handled?

Martini can separate authentication, authorization, validation, rate-limit, timeout, and transient server errors. Bounded retries and backoff are appropriate for transient failures, while invalid data should be routed for correction rather than retried indefinitely. Stable source identifiers, external references, and existing-Incident lookups help prevent duplicates.

Related Martini documentation

TOPdesk APIs

Workflows

Transformation

Security

Operations

Connect TOPdesk with your enterprise systems

Use Martini to build maintainable TOPdesk integrations around REST APIs, secure credentials, scheduled workflows, verified event notifications, data mapping, and operational error handling.

EXPLORE MARTINI
BOOK A DEMO