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
| Action | What it does |
|---|---|
| Add action to incident | Add an action (a note in the progress trail) to an incident, internal or seen by the caller. |
| Add note to change | Add a note to a change's progress trail, internal or seen by the requester. |
| Archive change | Archive a change. |
| Archive incident | Archive an incident, and its partial incidents. |
| Archive person | Archive a person, such as someone who has left, and the operator linked to them if there is one. |
| Create change | Create a change (a request for change) for a requester, from a template or from scratch. |
| Create incident | Register an incident for a caller: a known person by email address, or anyone by name. |
| Create person | Add a person (someone who can report incidents) to TOPdesk. |
| Get change | Get a change's details by its number or id. |
| Get incident | Get an incident's details by its number or id. |
| Get person | Get a person's details by their id. |
| List changes | List changes, filtered by type, state, requester or dates. |
| List incident actions | List the actions (notes) on an incident's progress trail. |
| List incidents | List incidents, filtered by state, caller, group, operator, category, status or dates. |
| List persons | Find persons by email address, surname or branch. |
| Register time spent | Register time spent on an incident. |
| Unarchive incident | Bring an archived incident back. |
| Update change | Change a change's description, category, priority, impact or external number. |
| Update incident | Change an incident's description, category, priority, assignment, status or dates, or close it. |
| Update person | Change 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
- Incident
incidenttextRequired - The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- Text
texttextRequired - What to write, as plain text or simple HTML (bold, italic, line breaks).
- Who can see it
visibilitytext - 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
- Change
changetextRequired - The change's number, such as C 2311 007, or its id from a trigger or an earlier step.
- Text
texttextRequired - What to write, as plain text or simple HTML.
- Who can see it
visibilitytext - 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
- Change
changetextRequired - The change's number, such as C 2311 007, or its id from a trigger or an earlier step.
- Reason
reasontext - 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
- Incident
incidenttextRequired - The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- Reason
reasontext - 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
- Person
persontextRequired - The person's id, from 'List persons', 'Create person' or a trigger.
- Reason
reasontext - 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 description
brief_descriptiontextRequired - What the change is, up to 80 characters.
- Requester
requestertextRequired - Who asks for it: pick a person, or give their email address.
- Type
change_typetext - A simple change, or an extensive one with phases and activities. A template sets its own.One of:
simple,extensive. Default:simple. - Template
templatetext - A change template to start from.
- Request
requesttext - What is asked for, in the requester's words.
- Category
categorytext - The change's category, by name.
- Subcategory
subcategorytext - The change's subcategory, by name.
- Priority
prioritytext - The change's priority.
- Impact
impacttext - The change's impact.
- External number
external_numbertext - A reference from another system.
- Emergency change
emergencytext - 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 description
brief_descriptiontextRequired - What it's about, up to 80 characters, such as Printer on floor 2 is jammed.
- Caller
callertextRequired - Who reported it: pick a person, give their email address, or type a name for someone TOPdesk doesn't know.
- Request
requesttext - What the caller asked or reported, in their words.
- Caller's branch
caller_branchtext - The branch of a caller TOPdesk doesn't know. Not needed for a known person.
- Line
linetext - First or second line. Leave blank for TOPdesk's default.One of:
firstLine(First line),secondLine(Second line). - Category
categorytext - The incident's category.
- Subcategory
subcategorytext - The subcategory. Its category is filled in for you when it has only one.
- Call type
call_typetext - The kind of call, such as Question or Malfunction.
- Entry type
entry_typetext - How it came in, such as Email or Phone.
- Impact
impacttext - How many it affects.
- Priority
prioritytext - Its priority.
- Operator group
operator_grouptext - The operator group to assign it to.
- Operator
operatortext - The operator to assign it to.
- Processing status
processing_statustext - Its processing status, such as In progress.
- Target date
target_datedate and time - When it should be done.
- External number
external_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
- Surname
surnametextRequired - Their surname, up to 50 characters.
- Branch
branchtextRequired - The branch they belong to. TOPdesk needs one for every person.
- First name
first_nametext - Their first name, up to 30 characters.
- Email
emailtext - Their email address.
- Phone
phone_numbertext - Their phone number, up to 25 characters.
- Mobile
mobile_numbertext - Their mobile number, up to 25 characters.
- Job title
job_titletext - Their job title.
- Employee number
employee_numbertext - Their employee number.
- Network login name
network_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
- Change
changetextRequired - 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
- Incident
incidenttextRequired - 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
- Person
persontextRequired - 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
- Type
change_typetext - Only simple or only extensive changes. Leave blank for both.One of:
simple,extensive. - Open or closed
open_statetext - Only open or only closed changes. Leave blank for both.One of:
open(Open only),closed(Closed only). - Requester
requestertext - Only changes this person asked for.
- Created after
created_afterdate and time - Only changes created at or after this time.
- Changed after
changed_afterdate and time - Only changes changed at or after this time.
- Include archived
include_archivedtext - Also list archived ones. Defaults to no.One of:
yes,no. - Advanced filter
querytext - A FIQL query for anything the filters don't cover, such as externalNumber==INC42. It is combined with the other filters.
- Order
sorttext - How to order them. Defaults to newest first.One of:
creationDate:desc(Newest first),creationDate:asc(Oldest first),number:desc(Number, highest first). - How many
page_sizenumber - The most to get on this page, 1 to 1000. Defaults to 25.From 1 to 1000.
- Start at
page_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
- Incident
incidenttextRequired - The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- How many
page_sizenumber - The most to get on this page, 1 to 100. Defaults to 25.From 1 to 100.
- Start at
page_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 closed
open_statetext - Only open or only closed incidents. Leave blank for both.One of:
open(Open only),closed(Closed only). - Line
linetext - Only first line, second line or partial incidents. Leave blank for first and second line.One of:
firstLine(First line),secondLine(Second line),partial. - Caller
callertext - Only this caller's incidents: pick a person or give their email address.
- Operator groups
operator_groupslist - Only incidents assigned to these groups.
- Operators
operatorslist - Only incidents assigned to these operators.
- Categories
categorieslist - Only incidents in these categories.
- Processing statuses
processing_statuseslist - Only incidents with these processing statuses.
- Registered after
created_afterdate and time - Only incidents registered at or after this time.
- Registered before
created_beforedate and time - Only incidents registered before this time.
- Changed after
changed_afterdate and time - Only incidents changed at or after this time.
- Advanced filter
querytext - A FIQL query for anything the filters don't cover, such as externalNumber==INC42. It is combined with the other filters.
- Include archived
include_archivedtext - Also list archived ones. Defaults to no.One of:
yes,no. - Order
sorttext - 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 many
page_sizenumber - The most to get on this page, 1 to 1000. Defaults to 25.From 1 to 1000.
- Start at
page_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
- Email
emailtext - Only the person with this email address.
- Surname starts with
surnametext - Only persons whose surname starts with this.
- Branch
branchtext - Only persons in this branch.
- Active or archived
statetext - Defaults to active persons only.One of:
active(Active only),archived(Archived only). - Added after
created_afterdate and time - Only persons added at or after this time.
- Advanced filter
querytext - A FIQL query for anything the filters don't cover, such as externalNumber==INC42. It is combined with the other filters.
- How many
page_sizenumber - The most to get on this page, 1 to 1000. Defaults to 25.From 1 to 1000.
- Start at
page_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
- Incident
incidenttextRequired - The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- Minutes
minutesnumberRequired - How many minutes. A negative number takes time off, as long as the total stays above 0.
- Notes
notestext - A note about the time, up to 250 characters.
- Date
entry_datedate and time - When the time was spent. Defaults to now.
- Reason
reasontext - The reason, such as Normal tariff.
- Operator
operatortext - 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
- Incident
incidenttextRequired - 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
- Change
changetextRequired - The change's number, such as C 2311 007, or its id from a trigger or an earlier step.
- Brief description
brief_descriptiontext - A new brief description. Leave blank to keep it.
- Category
categorytext - A new category, by name. Leave blank to keep it.
- Subcategory
subcategorytext - A new subcategory, by name. Leave blank to keep it.
- Priority
prioritytext - A new priority. Leave blank to keep it.
- Impact
impacttext - A new impact. Leave blank to keep it.
- External number
external_numbertext - A new external number. Leave blank to keep it.
- Emergency change
emergencytext - 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
- Incident
incidenttextRequired - The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- Brief description
brief_descriptiontext - A new brief description, up to 80 characters. Leave blank to keep it.
- Category
categorytext - The incident's category. Leave blank to keep it.
- Subcategory
subcategorytext - The subcategory. Its category is filled in for you when it has only one. Leave blank to keep it.
- Call type
call_typetext - The kind of call, such as Question or Malfunction. Leave blank to keep it.
- Entry type
entry_typetext - How it came in, such as Email or Phone. Leave blank to keep it.
- Impact
impacttext - How many it affects. Leave blank to keep it.
- Priority
prioritytext - Its priority. Leave blank to keep it.
- Operator group
operator_grouptext - The operator group to assign it to. Leave blank to keep it.
- Operator
operatortext - The operator to assign it to. Leave blank to keep it.
- Processing status
processing_statustext - Its processing status, such as In progress. Leave blank to keep it.
- Target date
target_datedate and time - When it should be done. Leave blank to keep it.
- External number
external_numbertext - A reference from another system, up to 60 characters. Leave blank to keep it.
- On hold
on_holdtext - Put it on hold, or take it off hold. Leave blank to keep it.One of:
yes,no. - Completed
completedtext - Mark it completed, or not. Leave blank to keep it.One of:
yes,no. - Closed
closedtext - Close it, or reopen it. Leave blank to keep it.One of:
yes,no. - Closure code
closure_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
- Person
persontextRequired - The person's id, from 'List persons', 'Create person' or a trigger.
- Surname
surnametext - A new surname. Leave blank to keep it.
- First name
first_nametext - Their first name, up to 30 characters.
- Email
emailtext - Their email address.
- Phone
phone_numbertext - Their phone number, up to 25 characters.
- Mobile
mobile_numbertext - Their mobile number, up to 25 characters.
- Job title
job_titletext - Their job title.
- Employee number
employee_numbertext - Their employee number.
- Network login name
network_login_nametext - Their network (Windows) login name.
- Branch
branchtext - 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"
}
}