# TOPdesk

> 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.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/topdesk

## Actions

### Add action to incident

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

**Inputs**

- Incident (`incident`, text, required): The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- Text (`text`, text, required): What to write, as plain text or simple HTML (bold, italic, line breaks).
- Who can see it (`visibility`, text): 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**

- `incident` (object): The incident, after the action was added
- `invisible_for_caller` (true/false): Whether only operators can see it
- `text` (text): The action's text, as sent

**Example output**

```json
{
  "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 (`change`, text, required): The change's number, such as C 2311 007, or its id from a trigger or an earlier step.
- Text (`text`, text, required): What to write, as plain text or simple HTML.
- Who can see it (`visibility`, text): 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_id` (text): The change's id
- `change_number` (text): The change's number
- `note` (object): The note added to the change's progress trail

**Example output**

```json
{
  "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 (`change`, text, required): The change's number, such as C 2311 007, or its id from a trigger or an earlier step.
- Reason (`reason`, text): Why it is archived. Needed only when TOPdesk has no default reason.

**Outputs**

- `change` (object): The change

**Example output**

```json
{
  "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 (`incident`, text, required): The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- Reason (`reason`, text): Why it is archived. Needed only when TOPdesk has no default reason.

**Outputs**

- `incident` (object): The incident

**Example output**

```json
{
  "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 (`person`, text, required): The person's id, from 'List persons', 'Create person' or a trigger.
- Reason (`reason`, text): Why they are archived. Needed only when TOPdesk has no default reason.

**Outputs**

- `person` (object): The person

**Example output**

```json
{
  "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_description`, text, required): What the change is, up to 80 characters.
- Requester (`requester`, text, required): Who asks for it: pick a person, or give their email address.
- Type (`change_type`, text): A simple change, or an extensive one with phases and activities. A template sets its own. One of: `simple`, `extensive`. Default: `simple`.
- Template (`template`, text): A change template to start from.
- Request (`request`, text): What is asked for, in the requester's words.
- Category (`category`, text): The change's category, by name.
- Subcategory (`subcategory`, text): The change's subcategory, by name.
- Priority (`priority`, text): The change's priority.
- Impact (`impact`, text): The change's impact.
- External number (`external_number`, text): A reference from another system.
- Emergency change (`emergency`, text): Whether it is an emergency change. Defaults to no. One of: `yes`, `no`.

**Outputs**

- `change` (object): The change

**Example output**

```json
{
  "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_description`, text, required): What it's about, up to 80 characters, such as Printer on floor 2 is jammed.
- Caller (`caller`, text, required): Who reported it: pick a person, give their email address, or type a name for someone TOPdesk doesn't know.
- Request (`request`, text): What the caller asked or reported, in their words.
- Caller's branch (`caller_branch`, text): The branch of a caller TOPdesk doesn't know. Not needed for a known person.
- Line (`line`, text): First or second line. Leave blank for TOPdesk's default. One of: `firstLine` (First line), `secondLine` (Second line).
- Category (`category`, text): The incident's category.
- Subcategory (`subcategory`, text): The subcategory. Its category is filled in for you when it has only one.
- Call type (`call_type`, text): The kind of call, such as Question or Malfunction.
- Entry type (`entry_type`, text): How it came in, such as Email or Phone.
- Impact (`impact`, text): How many it affects.
- Priority (`priority`, text): Its priority.
- Operator group (`operator_group`, text): The operator group to assign it to.
- Operator (`operator`, text): The operator to assign it to.
- Processing status (`processing_status`, text): Its processing status, such as In progress.
- Target date (`target_date`, date and time): When it should be done.
- External number (`external_number`, text): A reference from another system, up to 60 characters.

**Outputs**

- `incident` (object): The incident

**Example output**

```json
{
  "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 (`surname`, text, required): Their surname, up to 50 characters.
- Branch (`branch`, text, required): The branch they belong to. TOPdesk needs one for every person.
- First name (`first_name`, text): Their first name, up to 30 characters.
- Email (`email`, text): Their email address.
- Phone (`phone_number`, text): Their phone number, up to 25 characters.
- Mobile (`mobile_number`, text): Their mobile number, up to 25 characters.
- Job title (`job_title`, text): Their job title.
- Employee number (`employee_number`, text): Their employee number.
- Network login name (`network_login_name`, text): Their network (Windows) login name.

**Outputs**

- `person` (object): The person

**Example output**

```json
{
  "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 (`change`, text, required): The change's number, such as C 2311 007, or its id from a trigger or an earlier step.

**Outputs**

- `change` (object): The change

**Example output**

```json
{
  "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 (`incident`, text, required): The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.

**Outputs**

- `incident` (object): The incident

**Example output**

```json
{
  "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 (`person`, text, required): The person's id, from 'List persons', 'Create person' or a trigger.

**Outputs**

- `person` (object): The person

**Example output**

```json
{
  "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_type`, text): Only simple or only extensive changes. Leave blank for both. One of: `simple`, `extensive`.
- Open or closed (`open_state`, text): Only open or only closed changes. Leave blank for both. One of: `open` (Open only), `closed` (Closed only).
- Requester (`requester`, text): Only changes this person asked for.
- Created after (`created_after`, date and time): Only changes created at or after this time.
- Changed after (`changed_after`, date and time): Only changes changed at or after this time.
- Include archived (`include_archived`, text): Also list archived ones. Defaults to no. One of: `yes`, `no`.
- Advanced filter (`query`, text): A FIQL query for anything the filters don't cover, such as externalNumber==INC42. It is combined with the other filters.
- Order (`sort`, text): 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_size`, number): The most to get on this page, 1 to 1000. Defaults to 25. From 1 to 1000.
- Start at (`page_start`, number): Where the page starts: 0 for the first, or the 'next_page_start' from the page before. At least 0.

**Outputs**

- `changes` (list): The changes on this page
- `count` (number): How many are on this page
- `has_more` (true/false): Whether there are more after this page
- `next_page_start` (number): The 'Start at' for the next page; 0 when there are no more

**Example output**

```json
{
  "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 (`incident`, text, required): The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- How many (`page_size`, number): The most to get on this page, 1 to 100. Defaults to 25. From 1 to 100.
- Start at (`page_start`, number): Where the page starts: 0 for the first, or the 'next_page_start' from the page before. At least 0.

**Outputs**

- `actions` (list): The incident's actions on this page
- `count` (number): How many are on this page
- `has_more` (true/false): Whether there are more after this page
- `next_page_start` (number): The 'Start at' for the next page; 0 when there are no more

**Example output**

```json
{
  "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_state`, text): Only open or only closed incidents. Leave blank for both. One of: `open` (Open only), `closed` (Closed only).
- Line (`line`, text): 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 (`caller`, text): Only this caller's incidents: pick a person or give their email address.
- Operator groups (`operator_groups`, list): Only incidents assigned to these groups.
- Operators (`operators`, list): Only incidents assigned to these operators.
- Categories (`categories`, list): Only incidents in these categories.
- Processing statuses (`processing_statuses`, list): Only incidents with these processing statuses.
- Registered after (`created_after`, date and time): Only incidents registered at or after this time.
- Registered before (`created_before`, date and time): Only incidents registered before this time.
- Changed after (`changed_after`, date and time): Only incidents changed at or after this time.
- Advanced filter (`query`, text): A FIQL query for anything the filters don't cover, such as externalNumber==INC42. It is combined with the other filters.
- Include archived (`include_archived`, text): Also list archived ones. Defaults to no. One of: `yes`, `no`.
- Order (`sort`, text): 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_size`, number): The most to get on this page, 1 to 1000. Defaults to 25. From 1 to 1000.
- Start at (`page_start`, number): Where the page starts: 0 for the first, or the 'next_page_start' from the page before. At least 0.

**Outputs**

- `count` (number): How many are on this page
- `has_more` (true/false): Whether there are more after this page
- `incidents` (list): The incidents on this page
- `next_page_start` (number): The 'Start at' for the next page; 0 when there are no more

**Example output**

```json
{
  "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 (`email`, text): Only the person with this email address.
- Surname starts with (`surname`, text): Only persons whose surname starts with this.
- Branch (`branch`, text): Only persons in this branch.
- Active or archived (`state`, text): Defaults to active persons only. One of: `active` (Active only), `archived` (Archived only).
- Added after (`created_after`, date and time): Only persons added at or after this time.
- Advanced filter (`query`, text): A FIQL query for anything the filters don't cover, such as externalNumber==INC42. It is combined with the other filters.
- How many (`page_size`, number): The most to get on this page, 1 to 1000. Defaults to 25. From 1 to 1000.
- Start at (`page_start`, number): Where the page starts: 0 for the first, or the 'next_page_start' from the page before. At least 0.

**Outputs**

- `count` (number): How many are on this page
- `has_more` (true/false): Whether there are more after this page
- `next_page_start` (number): The 'Start at' for the next page; 0 when there are no more
- `persons` (list): The persons on this page

**Example output**

```json
{
  "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 (`incident`, text, required): The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- Minutes (`minutes`, number, required): How many minutes. A negative number takes time off, as long as the total stays above 0.
- Notes (`notes`, text): A note about the time, up to 250 characters.
- Date (`entry_date`, date and time): When the time was spent. Defaults to now.
- Reason (`reason`, text): The reason, such as Normal tariff.
- Operator (`operator`, text): Who spent the time. Defaults to the connected operator.

**Outputs**

- `time_spent` (object): The time registered

**Example output**

```json
{
  "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 (`incident`, text, required): The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.

**Outputs**

- `incident` (object): The incident

**Example output**

```json
{
  "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 (`change`, text, required): The change's number, such as C 2311 007, or its id from a trigger or an earlier step.
- Brief description (`brief_description`, text): A new brief description. Leave blank to keep it.
- Category (`category`, text): A new category, by name. Leave blank to keep it.
- Subcategory (`subcategory`, text): A new subcategory, by name. Leave blank to keep it.
- Priority (`priority`, text): A new priority. Leave blank to keep it.
- Impact (`impact`, text): A new impact. Leave blank to keep it.
- External number (`external_number`, text): A new external number. Leave blank to keep it.
- Emergency change (`emergency`, text): Mark it an emergency change, or not. Leave blank to keep it. One of: `yes`, `no`.

**Outputs**

- `change` (object): The change

**Example output**

```json
{
  "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 (`incident`, text, required): The incident's number, such as I 2311 042, or its id from a trigger or an earlier step.
- Brief description (`brief_description`, text): A new brief description, up to 80 characters. Leave blank to keep it.
- Category (`category`, text): The incident's category. Leave blank to keep it.
- Subcategory (`subcategory`, text): The subcategory. Its category is filled in for you when it has only one. Leave blank to keep it.
- Call type (`call_type`, text): The kind of call, such as Question or Malfunction. Leave blank to keep it.
- Entry type (`entry_type`, text): How it came in, such as Email or Phone. Leave blank to keep it.
- Impact (`impact`, text): How many it affects. Leave blank to keep it.
- Priority (`priority`, text): Its priority. Leave blank to keep it.
- Operator group (`operator_group`, text): The operator group to assign it to. Leave blank to keep it.
- Operator (`operator`, text): The operator to assign it to. Leave blank to keep it.
- Processing status (`processing_status`, text): Its processing status, such as In progress. Leave blank to keep it.
- Target date (`target_date`, date and time): When it should be done. Leave blank to keep it.
- External number (`external_number`, text): A reference from another system, up to 60 characters. Leave blank to keep it.
- On hold (`on_hold`, text): Put it on hold, or take it off hold. Leave blank to keep it. One of: `yes`, `no`.
- Completed (`completed`, text): Mark it completed, or not. Leave blank to keep it. One of: `yes`, `no`.
- Closed (`closed`, text): Close it, or reopen it. Leave blank to keep it. One of: `yes`, `no`.
- Closure code (`closure_code`, text): Why it was closed. Leave blank to keep it.

**Outputs**

- `incident` (object): The incident

**Example output**

```json
{
  "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 (`person`, text, required): The person's id, from 'List persons', 'Create person' or a trigger.
- Surname (`surname`, text): A new surname. Leave blank to keep it.
- First name (`first_name`, text): Their first name, up to 30 characters.
- Email (`email`, text): Their email address.
- Phone (`phone_number`, text): Their phone number, up to 25 characters.
- Mobile (`mobile_number`, text): Their mobile number, up to 25 characters.
- Job title (`job_title`, text): Their job title.
- Employee number (`employee_number`, text): Their employee number.
- Network login name (`network_login_name`, text): Their network (Windows) login name.
- Branch (`branch`, text): A new branch. Leave blank to keep it.

**Outputs**

- `person` (object): The person

**Example output**

```json
{
  "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"
  }
}
```
