TOPdesk

App · 20 actions

Run your TOPdesk service desk from workflows: register, update, close and archive incidents, add actions and time, create and update changes, and add, find and archive persons. Start a workflow when an incident or change is created or changes, an incident is closed, or a person is added.

Actions

ActionWhat it does
Add action to incidentAdd an action (a note in the progress trail) to an incident, internal or seen by the caller.
Add note to changeAdd a note to a change's progress trail, internal or seen by the requester.
Archive changeArchive a change.
Archive incidentArchive an incident, and its partial incidents.
Archive personArchive a person, such as someone who has left, and the operator linked to them if there is one.
Create changeCreate a change (a request for change) for a requester, from a template or from scratch.
Create incidentRegister an incident for a caller: a known person by email address, or anyone by name.
Create personAdd a person (someone who can report incidents) to TOPdesk.
Get changeGet a change's details by its number or id.
Get incidentGet an incident's details by its number or id.
Get personGet a person's details by their id.
List changesList changes, filtered by type, state, requester or dates.
List incident actionsList the actions (notes) on an incident's progress trail.
List incidentsList incidents, filtered by state, caller, group, operator, category, status or dates.
List personsFind persons by email address, surname or branch.
Register time spentRegister time spent on an incident.
Unarchive incidentBring an archived incident back.
Update changeChange a change's description, category, priority, impact or external number.
Update incidentChange an incident's description, category, priority, assignment, status or dates, or close it.
Update personChange a person's name, contact details, job title or branch.

Add action to incident

Add an action (a note in the progress trail) to an incident, internal or seen by the caller.

Inputs

IncidentincidenttextRequired
The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
TexttexttextRequired
What to write, as plain text or simple HTML (bold, italic, line breaks).
Who can see itvisibilitytext
Internal notes are seen only by operators; otherwise the caller sees it in the Self-Service Portal too.One of: internal (Only operators (internal)), caller (The caller can see it). Default: internal.

Outputs

incidentobject
The incident, after the action was added
invisible_for_callertrue/false
Whether only operators can see it
texttext
The action's text, as sent
Example output
{
  "incident": {
    "archived": false,
    "brief_description": "Printer on floor 2 is jammed",
    "call_date": "2026-11-18T09:12:00Z",
    "call_type": "Malfunction",
    "caller_branch": "Head office",
    "caller_email": "jane.smith@example.com",
    "caller_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "caller_name": "Jane Smith",
    "category": "Hardware",
    "closed": false,
    "closed_date": "",
    "closure_code": "",
    "completed": false,
    "creation_date": "2026-11-18T09:12:44Z",
    "entry_type": "Email",
    "external_number": "",
    "id": "0d4b2f1e-7c55-4c1a-9a0b-5f2a8e3c1d42",
    "impact": "Person",
    "line": "firstLine",
    "modification_date": "2026-11-18T10:02:13Z",
    "number": "I 2311 042",
    "on_hold": false,
    "operator": "Sam Operator",
    "operator_group": "Service Desk",
    "operator_group_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "operator_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "priority": "P3",
    "processing_status": "In progress",
    "request": "The printer next to the kitchen shows a paper jam.",
    "subcategory": "Printer",
    "target_date": "2026-11-19T17:00:00Z",
    "urgency": "Normal"
  },
  "invisible_for_caller": true,
  "text": "Replaced the toner and cleared the jam."
}

Add note to change

Add a note to a change's progress trail, internal or seen by the requester.

Inputs

ChangechangetextRequired
The change's number, such as C 2311 007, or its id from a trigger or an earlier step.
TexttexttextRequired
What to write, as plain text or simple HTML.
Who can see itvisibilitytext
Internal notes are seen only by operators; otherwise the caller sees it in the Self-Service Portal too.One of: internal (Only operators (internal)), caller (The caller can see it). Default: internal.

Outputs

change_idtext
The change's id
change_numbertext
The change's number
noteobject
The note added to the change's progress trail
Example output
{
  "change_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
  "change_number": "C 2311 007",
  "note": {
    "creation_date": "2026-11-18T10:02:13Z",
    "entry_date": "2026-11-18T10:02:13Z",
    "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
    "invisible_for_caller": true,
    "operator": "Sam Operator",
    "person": "",
    "text": "Ordered the new printer."
  }
}

Archive change

Archive a change.

Inputs

ChangechangetextRequired
The change's number, such as C 2311 007, or its id from a trigger or an earlier step.
Reasonreasontext
Why it is archived. Needed only when TOPdesk has no default reason.

Outputs

changeobject
The change
Example output
{
  "change": {
    "archived": true,
    "assignee": "Sam Operator",
    "assignee_group": "Service Desk",
    "brief_description": "Replace the floor 2 printer",
    "category": "Hardware",
    "change_type": "simple",
    "creation_date": "2026-11-18T09:30:00Z",
    "emergency": false,
    "external_number": "",
    "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
    "impact": "Department",
    "modification_date": "2026-11-18T09:45:00Z",
    "number": "C 2311 007",
    "priority": "Normal",
    "processing_status": "rfc",
    "requester": "Jane Smith",
    "requester_email": "jane.smith@example.com",
    "requester_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "status": "Request for change",
    "subcategory": "Printer"
  }
}

Archive incident

Archive an incident, and its partial incidents. 'Unarchive incident' brings it back.

Inputs

IncidentincidenttextRequired
The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
Reasonreasontext
Why it is archived. Needed only when TOPdesk has no default reason.

Outputs

incidentobject
The incident
Example output
{
  "incident": {
    "archived": true,
    "brief_description": "Printer on floor 2 is jammed",
    "call_date": "2026-11-18T09:12:00Z",
    "call_type": "Malfunction",
    "caller_branch": "Head office",
    "caller_email": "jane.smith@example.com",
    "caller_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "caller_name": "Jane Smith",
    "category": "Hardware",
    "closed": false,
    "closed_date": "",
    "closure_code": "",
    "completed": false,
    "creation_date": "2026-11-18T09:12:44Z",
    "entry_type": "Email",
    "external_number": "",
    "id": "0d4b2f1e-7c55-4c1a-9a0b-5f2a8e3c1d42",
    "impact": "Person",
    "line": "firstLine",
    "modification_date": "2026-11-18T10:02:13Z",
    "number": "I 2311 042",
    "on_hold": false,
    "operator": "Sam Operator",
    "operator_group": "Service Desk",
    "operator_group_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "operator_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "priority": "P3",
    "processing_status": "In progress",
    "request": "The printer next to the kitchen shows a paper jam.",
    "subcategory": "Printer",
    "target_date": "2026-11-19T17:00:00Z",
    "urgency": "Normal"
  }
}

Archive person

Archive a person, such as someone who has left, and the operator linked to them if there is one.

Inputs

PersonpersontextRequired
The person's id, from 'List persons', 'Create person' or a trigger.
Reasonreasontext
Why they are archived. Needed only when TOPdesk has no default reason.

Outputs

personobject
The person
Example output
{
  "person": {
    "archived": true,
    "branch": "Head office",
    "branch_id": "7b8c9d0e-1f2a-4b3c-9d4e-5f6a7b8c9d0e",
    "creation_date": "2026-11-01T08:00:00Z",
    "department": "Facilities",
    "email": "jane.smith@example.com",
    "employee_number": "E1042",
    "first_name": "Jane",
    "id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "job_title": "Office manager",
    "location": "",
    "login_name": "",
    "mobile_number": "",
    "modification_date": "2026-11-18T09:00:00Z",
    "name": "Smith, Jane",
    "network_login_name": "jsmith",
    "phone_number": "+31 15 123 4567",
    "surname": "Smith"
  }
}

Create change

Create a change (a request for change) for a requester, from a template or from scratch.

Inputs

Brief descriptionbrief_descriptiontextRequired
What the change is, up to 80 characters.
RequesterrequestertextRequired
Who asks for it: pick a person, or give their email address.
Typechange_typetext
A simple change, or an extensive one with phases and activities. A template sets its own.One of: simple, extensive. Default: simple.
Templatetemplatetext
A change template to start from.
Requestrequesttext
What is asked for, in the requester's words.
Categorycategorytext
The change's category, by name.
Subcategorysubcategorytext
The change's subcategory, by name.
Priorityprioritytext
The change's priority.
Impactimpacttext
The change's impact.
External numberexternal_numbertext
A reference from another system.
Emergency changeemergencytext
Whether it is an emergency change. Defaults to no.One of: yes, no.

Outputs

changeobject
The change
Example output
{
  "change": {
    "archived": false,
    "assignee": "Sam Operator",
    "assignee_group": "Service Desk",
    "brief_description": "Replace the floor 2 printer",
    "category": "Hardware",
    "change_type": "simple",
    "creation_date": "2026-11-18T09:30:00Z",
    "emergency": false,
    "external_number": "",
    "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
    "impact": "Department",
    "modification_date": "2026-11-18T09:45:00Z",
    "number": "C 2311 007",
    "priority": "Normal",
    "processing_status": "rfc",
    "requester": "Jane Smith",
    "requester_email": "jane.smith@example.com",
    "requester_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "status": "Request for change",
    "subcategory": "Printer"
  }
}

Create incident

Register an incident for a caller: a known person by email address, or anyone by name.

Inputs

Brief descriptionbrief_descriptiontextRequired
What it's about, up to 80 characters, such as Printer on floor 2 is jammed.
CallercallertextRequired
Who reported it: pick a person, give their email address, or type a name for someone TOPdesk doesn't know.
Requestrequesttext
What the caller asked or reported, in their words.
Caller's branchcaller_branchtext
The branch of a caller TOPdesk doesn't know. Not needed for a known person.
Linelinetext
First or second line. Leave blank for TOPdesk's default.One of: firstLine (First line), secondLine (Second line).
Categorycategorytext
The incident's category.
Subcategorysubcategorytext
The subcategory. Its category is filled in for you when it has only one.
Call typecall_typetext
The kind of call, such as Question or Malfunction.
Entry typeentry_typetext
How it came in, such as Email or Phone.
Impactimpacttext
How many it affects.
Priorityprioritytext
Its priority.
Operator groupoperator_grouptext
The operator group to assign it to.
Operatoroperatortext
The operator to assign it to.
Processing statusprocessing_statustext
Its processing status, such as In progress.
Target datetarget_datedate and time
When it should be done.
External numberexternal_numbertext
A reference from another system, up to 60 characters.

Outputs

incidentobject
The incident
Example output
{
  "incident": {
    "archived": false,
    "brief_description": "Printer on floor 2 is jammed",
    "call_date": "2026-11-18T09:12:00Z",
    "call_type": "Malfunction",
    "caller_branch": "Head office",
    "caller_email": "jane.smith@example.com",
    "caller_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "caller_name": "Jane Smith",
    "category": "Hardware",
    "closed": false,
    "closed_date": "",
    "closure_code": "",
    "completed": false,
    "creation_date": "2026-11-18T09:12:44Z",
    "entry_type": "Email",
    "external_number": "",
    "id": "0d4b2f1e-7c55-4c1a-9a0b-5f2a8e3c1d42",
    "impact": "Person",
    "line": "firstLine",
    "modification_date": "2026-11-18T10:02:13Z",
    "number": "I 2311 042",
    "on_hold": false,
    "operator": "Sam Operator",
    "operator_group": "Service Desk",
    "operator_group_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "operator_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "priority": "P3",
    "processing_status": "In progress",
    "request": "The printer next to the kitchen shows a paper jam.",
    "subcategory": "Printer",
    "target_date": "2026-11-19T17:00:00Z",
    "urgency": "Normal"
  }
}

Create person

Add a person (someone who can report incidents) to TOPdesk.

Inputs

SurnamesurnametextRequired
Their surname, up to 50 characters.
BranchbranchtextRequired
The branch they belong to. TOPdesk needs one for every person.
First namefirst_nametext
Their first name, up to 30 characters.
Emailemailtext
Their email address.
Phonephone_numbertext
Their phone number, up to 25 characters.
Mobilemobile_numbertext
Their mobile number, up to 25 characters.
Job titlejob_titletext
Their job title.
Employee numberemployee_numbertext
Their employee number.
Network login namenetwork_login_nametext
Their network (Windows) login name.

Outputs

personobject
The person
Example output
{
  "person": {
    "archived": false,
    "branch": "Head office",
    "branch_id": "7b8c9d0e-1f2a-4b3c-9d4e-5f6a7b8c9d0e",
    "creation_date": "2026-11-01T08:00:00Z",
    "department": "Facilities",
    "email": "jane.smith@example.com",
    "employee_number": "E1042",
    "first_name": "Jane",
    "id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "job_title": "Office manager",
    "location": "",
    "login_name": "",
    "mobile_number": "",
    "modification_date": "2026-11-18T09:00:00Z",
    "name": "Smith, Jane",
    "network_login_name": "jsmith",
    "phone_number": "+31 15 123 4567",
    "surname": "Smith"
  }
}

Get change

Get a change's details by its number or id.

Inputs

ChangechangetextRequired
The change's number, such as C 2311 007, or its id from a trigger or an earlier step.

Outputs

changeobject
The change
Example output
{
  "change": {
    "archived": false,
    "assignee": "Sam Operator",
    "assignee_group": "Service Desk",
    "brief_description": "Replace the floor 2 printer",
    "category": "Hardware",
    "change_type": "simple",
    "creation_date": "2026-11-18T09:30:00Z",
    "emergency": false,
    "external_number": "",
    "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
    "impact": "Department",
    "modification_date": "2026-11-18T09:45:00Z",
    "number": "C 2311 007",
    "priority": "Normal",
    "processing_status": "rfc",
    "requester": "Jane Smith",
    "requester_email": "jane.smith@example.com",
    "requester_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "status": "Request for change",
    "subcategory": "Printer"
  }
}

Get incident

Get an incident's details by its number or id.

Inputs

IncidentincidenttextRequired
The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.

Outputs

incidentobject
The incident
Example output
{
  "incident": {
    "archived": false,
    "brief_description": "Printer on floor 2 is jammed",
    "call_date": "2026-11-18T09:12:00Z",
    "call_type": "Malfunction",
    "caller_branch": "Head office",
    "caller_email": "jane.smith@example.com",
    "caller_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "caller_name": "Jane Smith",
    "category": "Hardware",
    "closed": false,
    "closed_date": "",
    "closure_code": "",
    "completed": false,
    "creation_date": "2026-11-18T09:12:44Z",
    "entry_type": "Email",
    "external_number": "",
    "id": "0d4b2f1e-7c55-4c1a-9a0b-5f2a8e3c1d42",
    "impact": "Person",
    "line": "firstLine",
    "modification_date": "2026-11-18T10:02:13Z",
    "number": "I 2311 042",
    "on_hold": false,
    "operator": "Sam Operator",
    "operator_group": "Service Desk",
    "operator_group_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "operator_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "priority": "P3",
    "processing_status": "In progress",
    "request": "The printer next to the kitchen shows a paper jam.",
    "subcategory": "Printer",
    "target_date": "2026-11-19T17:00:00Z",
    "urgency": "Normal"
  }
}

Get person

Get a person's details by their id.

Inputs

PersonpersontextRequired
The person's id, from 'List persons', 'Create person' or a trigger.

Outputs

personobject
The person
Example output
{
  "person": {
    "archived": false,
    "branch": "Head office",
    "branch_id": "7b8c9d0e-1f2a-4b3c-9d4e-5f6a7b8c9d0e",
    "creation_date": "2026-11-01T08:00:00Z",
    "department": "Facilities",
    "email": "jane.smith@example.com",
    "employee_number": "E1042",
    "first_name": "Jane",
    "id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "job_title": "Office manager",
    "location": "",
    "login_name": "",
    "mobile_number": "",
    "modification_date": "2026-11-18T09:00:00Z",
    "name": "Smith, Jane",
    "network_login_name": "jsmith",
    "phone_number": "+31 15 123 4567",
    "surname": "Smith"
  }
}

List changes

List changes, filtered by type, state, requester or dates. Gets one page; run it again with the next page start to see more.

Inputs

Typechange_typetext
Only simple or only extensive changes. Leave blank for both.One of: simple, extensive.
Open or closedopen_statetext
Only open or only closed changes. Leave blank for both.One of: open (Open only), closed (Closed only).
Requesterrequestertext
Only changes this person asked for.
Created aftercreated_afterdate and time
Only changes created at or after this time.
Changed afterchanged_afterdate and time
Only changes changed at or after this time.
Include archivedinclude_archivedtext
Also list archived ones. Defaults to no.One of: yes, no.
Advanced filterquerytext
A FIQL query for anything the filters don't cover, such as externalNumber==INC42. It is combined with the other filters.
Ordersorttext
How to order them. Defaults to newest first.One of: creationDate:desc (Newest first), creationDate:asc (Oldest first), number:desc (Number, highest first).
How manypage_sizenumber
The most to get on this page, 1 to 1000. Defaults to 25.From 1 to 1000.
Start atpage_startnumber
Where the page starts: 0 for the first, or the 'next_page_start' from the page before.At least 0.

Outputs

changeslist
The changes on this page
countnumber
How many are on this page
has_moretrue/false
Whether there are more after this page
next_page_startnumber
The 'Start at' for the next page; 0 when there are no more
Example output
{
  "changes": [
    {
      "archived": false,
      "assignee": "Sam Operator",
      "assignee_group": "Service Desk",
      "brief_description": "Replace the floor 2 printer",
      "category": "Hardware",
      "change_type": "simple",
      "creation_date": "2026-11-18T09:30:00Z",
      "emergency": false,
      "external_number": "",
      "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
      "impact": "Department",
      "modification_date": "2026-11-18T09:45:00Z",
      "number": "C 2311 007",
      "priority": "Normal",
      "processing_status": "rfc",
      "requester": "Jane Smith",
      "requester_email": "jane.smith@example.com",
      "requester_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
      "status": "Request for change",
      "subcategory": "Printer"
    }
  ],
  "count": 1,
  "has_more": false,
  "next_page_start": 0
}

List incident actions

List the actions (notes) on an incident's progress trail. Gets one page; run it again with the next page start to see more.

Inputs

IncidentincidenttextRequired
The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
How manypage_sizenumber
The most to get on this page, 1 to 100. Defaults to 25.From 1 to 100.
Start atpage_startnumber
Where the page starts: 0 for the first, or the 'next_page_start' from the page before.At least 0.

Outputs

actionslist
The incident's actions on this page
countnumber
How many are on this page
has_moretrue/false
Whether there are more after this page
next_page_startnumber
The 'Start at' for the next page; 0 when there are no more
Example output
{
  "actions": [
    {
      "creation_date": "2026-11-18T10:02:13Z",
      "entry_date": "2026-11-18T10:02:13Z",
      "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
      "invisible_for_caller": true,
      "operator": "Sam Operator",
      "person": "",
      "text": "Replaced the toner and cleared the jam."
    }
  ],
  "count": 1,
  "has_more": false,
  "next_page_start": 0
}

List incidents

List incidents, filtered by state, caller, group, operator, category, status or dates. Gets one page; run it again with the next page start to see more.

Inputs

Open or closedopen_statetext
Only open or only closed incidents. Leave blank for both.One of: open (Open only), closed (Closed only).
Linelinetext
Only first line, second line or partial incidents. Leave blank for first and second line.One of: firstLine (First line), secondLine (Second line), partial.
Callercallertext
Only this caller's incidents: pick a person or give their email address.
Operator groupsoperator_groupslist
Only incidents assigned to these groups.
Operatorsoperatorslist
Only incidents assigned to these operators.
Categoriescategorieslist
Only incidents in these categories.
Processing statusesprocessing_statuseslist
Only incidents with these processing statuses.
Registered aftercreated_afterdate and time
Only incidents registered at or after this time.
Registered beforecreated_beforedate and time
Only incidents registered before this time.
Changed afterchanged_afterdate and time
Only incidents changed at or after this time.
Advanced filterquerytext
A FIQL query for anything the filters don't cover, such as externalNumber==INC42. It is combined with the other filters.
Include archivedinclude_archivedtext
Also list archived ones. Defaults to no.One of: yes, no.
Ordersorttext
How to order them. Defaults to newest first.One of: creationDate:desc (Newest first), creationDate:asc (Oldest first), modificationDate:desc (Recently changed first), targetDate:asc (Target date, soonest first).
How manypage_sizenumber
The most to get on this page, 1 to 1000. Defaults to 25.From 1 to 1000.
Start atpage_startnumber
Where the page starts: 0 for the first, or the 'next_page_start' from the page before.At least 0.

Outputs

countnumber
How many are on this page
has_moretrue/false
Whether there are more after this page
incidentslist
The incidents on this page
next_page_startnumber
The 'Start at' for the next page; 0 when there are no more
Example output
{
  "count": 1,
  "has_more": false,
  "incidents": [
    {
      "archived": false,
      "brief_description": "Printer on floor 2 is jammed",
      "call_date": "2026-11-18T09:12:00Z",
      "call_type": "Malfunction",
      "caller_branch": "Head office",
      "caller_email": "jane.smith@example.com",
      "caller_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
      "caller_name": "Jane Smith",
      "category": "Hardware",
      "closed": false,
      "closed_date": "",
      "closure_code": "",
      "completed": false,
      "creation_date": "2026-11-18T09:12:44Z",
      "entry_type": "Email",
      "external_number": "",
      "id": "0d4b2f1e-7c55-4c1a-9a0b-5f2a8e3c1d42",
      "impact": "Person",
      "line": "firstLine",
      "modification_date": "2026-11-18T10:02:13Z",
      "number": "I 2311 042",
      "on_hold": false,
      "operator": "Sam Operator",
      "operator_group": "Service Desk",
      "operator_group_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "operator_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
      "priority": "P3",
      "processing_status": "In progress",
      "request": "The printer next to the kitchen shows a paper jam.",
      "subcategory": "Printer",
      "target_date": "2026-11-19T17:00:00Z",
      "urgency": "Normal"
    }
  ],
  "next_page_start": 0
}

List persons

Find persons by email address, surname or branch. Gets one page; run it again with the next page start to see more.

Inputs

Emailemailtext
Only the person with this email address.
Surname starts withsurnametext
Only persons whose surname starts with this.
Branchbranchtext
Only persons in this branch.
Active or archivedstatetext
Defaults to active persons only.One of: active (Active only), archived (Archived only).
Added aftercreated_afterdate and time
Only persons added at or after this time.
Advanced filterquerytext
A FIQL query for anything the filters don't cover, such as externalNumber==INC42. It is combined with the other filters.
How manypage_sizenumber
The most to get on this page, 1 to 1000. Defaults to 25.From 1 to 1000.
Start atpage_startnumber
Where the page starts: 0 for the first, or the 'next_page_start' from the page before.At least 0.

Outputs

countnumber
How many are on this page
has_moretrue/false
Whether there are more after this page
next_page_startnumber
The 'Start at' for the next page; 0 when there are no more
personslist
The persons on this page
Example output
{
  "count": 1,
  "has_more": false,
  "next_page_start": 0,
  "persons": [
    {
      "archived": false,
      "branch": "Head office",
      "branch_id": "7b8c9d0e-1f2a-4b3c-9d4e-5f6a7b8c9d0e",
      "creation_date": "2026-11-01T08:00:00Z",
      "department": "Facilities",
      "email": "jane.smith@example.com",
      "employee_number": "E1042",
      "first_name": "Jane",
      "id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
      "job_title": "Office manager",
      "location": "",
      "login_name": "",
      "mobile_number": "",
      "modification_date": "2026-11-18T09:00:00Z",
      "name": "Smith, Jane",
      "network_login_name": "jsmith",
      "phone_number": "+31 15 123 4567",
      "surname": "Smith"
    }
  ]
}

Register time spent

Register time spent on an incident. Time registration must be switched on in TOPdesk.

Inputs

IncidentincidenttextRequired
The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
MinutesminutesnumberRequired
How many minutes. A negative number takes time off, as long as the total stays above 0.
Notesnotestext
A note about the time, up to 250 characters.
Dateentry_datedate and time
When the time was spent. Defaults to now.
Reasonreasontext
The reason, such as Normal tariff.
Operatoroperatortext
Who spent the time. Defaults to the connected operator.

Outputs

time_spentobject
The time registered
Example output
{
  "time_spent": {
    "entry_date": "2026-11-18T10:00:00Z",
    "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
    "minutes": 15,
    "notes": "Cleared the jam.",
    "operator": "Sam Operator",
    "operator_group": "Service Desk",
    "reason": "Normal tariff"
  }
}

Unarchive incident

Bring an archived incident back.

Inputs

IncidentincidenttextRequired
The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.

Outputs

incidentobject
The incident
Example output
{
  "incident": {
    "archived": false,
    "brief_description": "Printer on floor 2 is jammed",
    "call_date": "2026-11-18T09:12:00Z",
    "call_type": "Malfunction",
    "caller_branch": "Head office",
    "caller_email": "jane.smith@example.com",
    "caller_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "caller_name": "Jane Smith",
    "category": "Hardware",
    "closed": false,
    "closed_date": "",
    "closure_code": "",
    "completed": false,
    "creation_date": "2026-11-18T09:12:44Z",
    "entry_type": "Email",
    "external_number": "",
    "id": "0d4b2f1e-7c55-4c1a-9a0b-5f2a8e3c1d42",
    "impact": "Person",
    "line": "firstLine",
    "modification_date": "2026-11-18T10:02:13Z",
    "number": "I 2311 042",
    "on_hold": false,
    "operator": "Sam Operator",
    "operator_group": "Service Desk",
    "operator_group_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "operator_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "priority": "P3",
    "processing_status": "In progress",
    "request": "The printer next to the kitchen shows a paper jam.",
    "subcategory": "Printer",
    "target_date": "2026-11-19T17:00:00Z",
    "urgency": "Normal"
  }
}

Update change

Change a change's description, category, priority, impact or external number. Blank fields stay as they are.

Inputs

ChangechangetextRequired
The change's number, such as C 2311 007, or its id from a trigger or an earlier step.
Brief descriptionbrief_descriptiontext
A new brief description. Leave blank to keep it.
Categorycategorytext
A new category, by name. Leave blank to keep it.
Subcategorysubcategorytext
A new subcategory, by name. Leave blank to keep it.
Priorityprioritytext
A new priority. Leave blank to keep it.
Impactimpacttext
A new impact. Leave blank to keep it.
External numberexternal_numbertext
A new external number. Leave blank to keep it.
Emergency changeemergencytext
Mark it an emergency change, or not. Leave blank to keep it.One of: yes, no.

Outputs

changeobject
The change
Example output
{
  "change": {
    "archived": false,
    "assignee": "Sam Operator",
    "assignee_group": "Service Desk",
    "brief_description": "Replace the floor 2 printer",
    "category": "Hardware",
    "change_type": "simple",
    "creation_date": "2026-11-18T09:30:00Z",
    "emergency": false,
    "external_number": "",
    "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
    "impact": "Department",
    "modification_date": "2026-11-18T09:45:00Z",
    "number": "C 2311 007",
    "priority": "Normal",
    "processing_status": "rfc",
    "requester": "Jane Smith",
    "requester_email": "jane.smith@example.com",
    "requester_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "status": "Request for change",
    "subcategory": "Printer"
  }
}

Update incident

Change an incident's description, category, priority, assignment, status or dates, or close it. Blank fields stay as they are.

Inputs

IncidentincidenttextRequired
The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
Brief descriptionbrief_descriptiontext
A new brief description, up to 80 characters. Leave blank to keep it.
Categorycategorytext
The incident's category. Leave blank to keep it.
Subcategorysubcategorytext
The subcategory. Its category is filled in for you when it has only one. Leave blank to keep it.
Call typecall_typetext
The kind of call, such as Question or Malfunction. Leave blank to keep it.
Entry typeentry_typetext
How it came in, such as Email or Phone. Leave blank to keep it.
Impactimpacttext
How many it affects. Leave blank to keep it.
Priorityprioritytext
Its priority. Leave blank to keep it.
Operator groupoperator_grouptext
The operator group to assign it to. Leave blank to keep it.
Operatoroperatortext
The operator to assign it to. Leave blank to keep it.
Processing statusprocessing_statustext
Its processing status, such as In progress. Leave blank to keep it.
Target datetarget_datedate and time
When it should be done. Leave blank to keep it.
External numberexternal_numbertext
A reference from another system, up to 60 characters. Leave blank to keep it.
On holdon_holdtext
Put it on hold, or take it off hold. Leave blank to keep it.One of: yes, no.
Completedcompletedtext
Mark it completed, or not. Leave blank to keep it.One of: yes, no.
Closedclosedtext
Close it, or reopen it. Leave blank to keep it.One of: yes, no.
Closure codeclosure_codetext
Why it was closed. Leave blank to keep it.

Outputs

incidentobject
The incident
Example output
{
  "incident": {
    "archived": false,
    "brief_description": "Printer on floor 2 is jammed",
    "call_date": "2026-11-18T09:12:00Z",
    "call_type": "Malfunction",
    "caller_branch": "Head office",
    "caller_email": "jane.smith@example.com",
    "caller_id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "caller_name": "Jane Smith",
    "category": "Hardware",
    "closed": false,
    "closed_date": "",
    "closure_code": "",
    "completed": false,
    "creation_date": "2026-11-18T09:12:44Z",
    "entry_type": "Email",
    "external_number": "",
    "id": "0d4b2f1e-7c55-4c1a-9a0b-5f2a8e3c1d42",
    "impact": "Person",
    "line": "firstLine",
    "modification_date": "2026-11-18T10:02:13Z",
    "number": "I 2311 042",
    "on_hold": false,
    "operator": "Sam Operator",
    "operator_group": "Service Desk",
    "operator_group_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "operator_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "priority": "P3",
    "processing_status": "In progress",
    "request": "The printer next to the kitchen shows a paper jam.",
    "subcategory": "Printer",
    "target_date": "2026-11-19T17:00:00Z",
    "urgency": "Normal"
  }
}

Update person

Change a person's name, contact details, job title or branch. Blank fields stay as they are.

Inputs

PersonpersontextRequired
The person's id, from 'List persons', 'Create person' or a trigger.
Surnamesurnametext
A new surname. Leave blank to keep it.
First namefirst_nametext
Their first name, up to 30 characters.
Emailemailtext
Their email address.
Phonephone_numbertext
Their phone number, up to 25 characters.
Mobilemobile_numbertext
Their mobile number, up to 25 characters.
Job titlejob_titletext
Their job title.
Employee numberemployee_numbertext
Their employee number.
Network login namenetwork_login_nametext
Their network (Windows) login name.
Branchbranchtext
A new branch. Leave blank to keep it.

Outputs

personobject
The person
Example output
{
  "person": {
    "archived": false,
    "branch": "Head office",
    "branch_id": "7b8c9d0e-1f2a-4b3c-9d4e-5f6a7b8c9d0e",
    "creation_date": "2026-11-01T08:00:00Z",
    "department": "Facilities",
    "email": "jane.smith@example.com",
    "employee_number": "E1042",
    "first_name": "Jane",
    "id": "6a1c9e3b-2f4d-4b8a-9c7e-1d2f3a4b5c6d",
    "job_title": "Office manager",
    "location": "",
    "login_name": "",
    "mobile_number": "",
    "modification_date": "2026-11-18T09:00:00Z",
    "name": "Smith, Jane",
    "network_login_name": "jsmith",
    "phone_number": "+31 15 123 4567",
    "surname": "Smith"
  }
}

On this page