---
title: "Workflow: Tickets"
section: "API Reference"
route: /apiworkflowtickets
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Workflow: Tickets

Tickets are pieces of work raised about an Entity, such as an inspection or a repair. Each ticket has a type, moves through statuses, and sits in a queue that dictates who works on it. The API calls tickets Workflow Items.

Types, statuses, queues and schedules are set up separately, and tickets refer to them by ID. You can read about them in [Workflow: Types and statuses](/apiworkflowtypes), [Workflow: Queues](/apiworkflowqueues) and [Workflow: Schedules](/apiworkflowschedules).

This article will cover how to manage tickets, search them, and work with their attachments and history.

## Data model

Below is the core data model for a ticket.

```typescript
interface ITicket {
    // Unique ID for the ticket. This is the ticket number people see.
    // Exclude this value for new records.
    ID?: number;
    // ID of the ticket's own Entity, which holds the ticket's attribute data.
    // See below for how this works.
    "Entity.ID"?: string;
    // Workflow type ID. Set when the ticket is created.
    "ItemType.ID"?: number;
    // Status ID the ticket is currently in.
    "ItemStatus.ID"?: number;
    // Queue ID the ticket is currently in.
    "Queue.ID"?: number;
    // Text describing the work.
    Description?: string;
    // ISO 8601 date time string the ticket is due by.
    DueDate?: string | null;
    // Whole number priority. Higher and lower meanings are up to you.
    Priority?: number | null;
    // ID of a parent ticket, making this a sub-ticket.
    "Parent.Item.ID"?: number | null;
    // ID of the schedule that raised the ticket. 0 means none.
    "Workflow.Schedule.ID"?: number;
    // ID of a bookmark showing where the work is. Limited to 40 characters.
    "UI.Slide.ID"?: string;
    // ID of a Client File used as the ticket's thumbnail image. Limited to 64 characters.
    "Thumbnail.ClientFile.ID"?: string;
    // ID of the user who raised the ticket, set by the API.
    "CreatedBy.User.ID"?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}
```

Each ticket has its own Entity, created with the ticket. The Entity holds the ticket's attributes, laid out by the Entity Type the workflow type names, so each type of ticket can collect its own data. Comments on a ticket are comments on this Entity.

The Entity the ticket is about is called its subject. It is named by the "Subject.Entity.ID" attribute on the ticket's own Entity.

```typescript
// The ticket's own Entity, with its subject.
{
    "Subject.Entity.ID": "<id of the Entity the ticket is about>",
    // Any other attributes from the Entity Type's schema.
    "inspection": {
        "result": "Pass"
    },
    "Bruce": {
        "EntityType.ID": "<the workflow type's Entity Type>"
    }
}
```

## Who can see a ticket

Power users can see and update every ticket. Other users can see and update the tickets they raised, and the tickets in a queue linked to one of their user groups. A ticket linked to a bookmark is also hidden from users who cannot open that bookmark's Project View.

## Requesting a ticket

### Get ticket by ID

```http
GET https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket to get. |

**Response**

```typescript
// The ticket record, as specified at the top of the article, with two additions.
interface IResponse extends ITicket {
    // The ticket's own Entity.
    Entity?: any;
    // That Entity's Entity Type, including its schema.
    EntityType?: any;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Searching tickets

You can search tickets with any combination of the filters below. A filter can take several values, either by repeating the parameter or as a comma separated list, and a ticket matches when it has any of them.

Results are paged. The first page includes the total count, and "NextPageURL" gives the request for the next page. Set both "pageSize" and "pageIndex" to -1 to get only the count.

### Search tickets

```http
GET https://{accountId}.api.nextspace.host/workflow/itemsquery?pageSize={25}&pageIndex={0}&OrderBy={field}&SortOrder={ASC/DESC}&Search={text}&itemtypeid={type_id}&statusid={status_id}&queueid={queue_id}&statusend={true/false}&assignedtome={true/false}&CreatedByUserID={user_id}&Priority={priority}&ParentItemID={ticket_id}&scheduleid={schedule_id}&DueDateFrom={date}&DueDateTo={date}&SubjectEntityID={entity_id}&SubjectEntityTypeID={entity_type_id}&SlideID={bookmark_id}&Description={text}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `pageSize={25}` | query | no | How many tickets to return per page. Default is 25. |
| `pageIndex={0}` | query | no | Which page to return, starting from 0. |
| `OrderBy={field}` | query | no | Field to sort by. One of ID, Created, Updated, DueDate, Priority, ItemTypeID, ItemStatusID, QueueID, CreatedByUserID, ParentItemID, Description, or RANDOM. |
| `SortOrder={ASC/DESC}` | query | no | Sort direction. |
| `Search={text}` | query | no | Matches text within the description. A whole number also matches the ticket with that ID. |
| `itemtypeid={type_id}` | query | no | Only tickets of these workflow type IDs. |
| `statusid={status_id}` | query | no | Only tickets in these status IDs. |
| `queueid={queue_id}` | query | no | Only tickets in these queue IDs. |
| `statusend={true/false}` | query | no | true for only finished tickets, false for only open tickets. A ticket is finished when its status is an end status. |
| `assignedtome={true/false}` | query | no | true for only tickets in queues linked to one of your user groups. |
| `CreatedByUserID={user_id}` | query | no | Only tickets raised by these user IDs. |
| `Priority={priority}` | query | no | Only tickets with these priorities. |
| `ParentItemID={ticket_id}` | query | no | Only sub-tickets of these ticket IDs. |
| `scheduleid={schedule_id}` | query | no | Only tickets raised by these schedule IDs. |
| `DueDateFrom={date}` | query | no | Only tickets due on or after this ISO 8601 date time. |
| `DueDateTo={date}` | query | no | Only tickets due on or before this ISO 8601 date time. |
| `SubjectEntityID={entity_id}` | query | no | Only tickets about these Entity IDs. |
| `SubjectEntityTypeID={entity_type_id}` | query | no | Only tickets about Entities of these Entity Type IDs. SubjectParentEntityTypeID and SubjectOntologyID filter the same way by parent Entity Type and ontology. |
| `SlideID={bookmark_id}` | query | no | Only tickets linked to these bookmark IDs. |
| `Description={text}` | query | no | Only tickets whose description contains this text. |

**Response**

```typescript
interface IResponse {
    // Array of tickets. See the data model above for the record structure.
    Items: ITicket[];
    // Total matching tickets. Only included on the first page.
    TotalCount?: number;
    // If there are more pages.
    NextPage: boolean;
    // Request URL for the next page.
    NextPageURL?: string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/itemsquery";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Ticket statistics

You can count tickets grouped by the Entity Type of their subject, for example to chart how many open tickets each kind of asset has. The type, status and queue filters work the same way as in the search above.

### Get ticket statistics

```http
GET https://{accountId}.api.nextspace.host/workflow/items/statistics?itemtypeid={type_id}&statusid={status_id}&queueid={queue_id}&$expand={ParentEntityTypes,Ontologies}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `itemtypeid={type_id}` | query | no | Only count tickets of these workflow type IDs. |
| `statusid={status_id}` | query | no | Only count tickets in these status IDs. |
| `queueid={queue_id}` | query | no | Only count tickets in these queue IDs. |
| `$expand={ParentEntityTypes,Ontologies}` | query | no | Also group the counts by parent Entity Type, by ontology, or both. |

**Response**

```typescript
interface IResponse {
    EntityTypes: {
        EntityType: { ID: string; Name?: string; };
        WorkflowItemsCount: number;
    }[];
    // Only included when expanded.
    ParentEntityTypes?: {
        ParentEntityType: { ID: string; Name?: string; };
        WorkflowItemsCount: number;
    }[];
    // Only included when expanded.
    Ontologies?: {
        Ontology: { ID: number; Name?: string; };
        WorkflowItemsCount: number;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/items/statistics";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Creating a ticket

A ticket is created for a workflow type. Its status and queue start as the type's defaults, and its own Entity is created from the attributes you send, using the type's Entity Type.

You can give a different Entity Type in the URL, which needs edit access to that Entity Type. You can also send "Entity.ID" to use an Entity that already exists instead of creating one, which needs edit access to it.

### Create ticket

```http
POST https://{accountId}.api.nextspace.host/workflow/createnew/{type_id}/{entity_type_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{type_id}` | path | yes | The workflow type ID of the new ticket. |
| `{entity_type_id}` | path | no | The Entity Type for the ticket's own Entity. Leave empty to use the workflow type's Entity Type. |

**Request body**

```typescript
interface IBody {
    // Attributes for the ticket's own Entity, including the subject.
    Entity?: any;
    // Use an existing Entity instead of creating one.
    "Entity.ID"?: string;
    Description?: string;
    DueDate?: string;
    Priority?: number;
    "Parent.Item.ID"?: number;
    "Workflow.Schedule.ID"?: number;
    "UI.Slide.ID"?: string;
    "Thumbnail.ClientFile.ID"?: string;
}
```

**Example request body**

```json
{
    "Description": "Replace the damaged valve",
    "Priority": 2,
    "Entity": {
        "Subject.Entity.ID": "your-entity-id"
    }
}
```

**Response**

```typescript
interface IResponse {
    // The ticket's own Entity.
    Entity: any;
    // The new ticket. See the data model above for the record structure.
    WorkflowItem: ITicket;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/createnew/{type_id}/{entity_type_id}";
const method = "post";
const token = "your-token";
const body = {
    "Description": "Replace the damaged valve",
    "Priority": 2,
    "Entity": {
        "Subject.Entity.ID": "your-entity-id"
    }
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Updating a ticket

When updating, only the properties you include are changed. Send null for "DueDate", "Priority", "Parent.Item.ID" or "Workflow.Schedule.ID" to clear it. Changing "ItemStatus.ID" or "Queue.ID" moves the ticket, and users in the new queue's user groups are notified.

Include "Entity" to update the ticket's own Entity at the same time. Its attributes are merged into the existing ones.

The API does not check a status change against the statuses the workflow type allows next, so check them yourself before moving a ticket.

### Update ticket

```http
POST https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket to update. |

**Request body**

```typescript
// Body is the ticket JSON as specified at the top of the article.
// Optionally include "Entity" with attributes to merge into the ticket's own Entity.
```

**Example request body**

```json
{
    "ItemStatus.ID": 3,
    "Entity": {
        "inspection": {
            "result": "Pass"
        }
    }
}
```

**Response**

```typescript
// The ticket record, as specified at the top of the article.
// When "Entity" was sent, the response also includes "Entity" and "EntityType" as in the GET request.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}";
const method = "post";
const token = "your-token";
const body = {
    "ItemStatus.ID": 3,
    "Entity": {
        "inspection": {
            "result": "Pass"
        }
    }
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Deleting a ticket

Deleting a ticket also deletes its own Entity, unless that Entity is also the ticket's subject.

### Delete ticket

```http
DELETE https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Tickets: Attachments

Files attached to a ticket are stored as Entity Attachments on the ticket's own Entity, with the "Document" attachment type. You can list them with the Entity Attachments requests, which you can read about in [Entity Attachments](/apientityattachment).

### Upload attachment

```http
POST https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/uploadAttachment
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket to attach the file to. |

**Request body**

```typescript
// The body must be multipart/form-data, with the file in a part named "file".
```

**Response**

```typescript
// The response is the new Entity Attachment record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/uploadAttachment";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Delete attachment

```http
DELETE https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/attachment/{attachment_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket the attachment belongs to. |
| `{attachment_id}` | path | yes | The ID of the attachment to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/attachment/{attachment_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Delete several attachments

```http
DELETE https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/attachments
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket the attachments belong to. |

**Request body**

```typescript
interface IBody {
    // IDs of the attachments to delete.
    "Attachment.ID": number[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/attachments";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Tickets: History

Every time a ticket is saved, a history record is kept of its type, status, queue and attributes at that moment. Together they show how the ticket moved over time.

Power users can also add, edit and delete history records, for example to backfill work done before the ticket existed.

```typescript
interface ITicketHistory {
    // Unique ID for the history record.
    // Exclude this value for new records.
    ID?: number;
    // ID of the ticket this record belongs to.
    "Workflow.Item.ID"?: number;
    // ISO 8601 date time string of the change.
    DateTime?: string;
    // ID of the user who made the change.
    "UpdatedByUser.ID"?: string;
    // The ticket's type, status and queue IDs after the change.
    "Workflow.ItemType.ID"?: number;
    "Workflow.ItemStatus.ID"?: number;
    "Workflow.Queue.ID"?: number;
    // The ticket's own Entity attributes after the change.
    JSONData?: any;
    // Text describing the change.
    Comment?: string;
}
```

### Get ticket history

```http
GET https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/history
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket to get the history of. |

**Response**

```typescript
interface IResponse {
    // History records, newest first.
    Items: ITicketHistory[];
    TotalCount: number;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/history";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Get history record by ID

```http
GET https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/history/{history_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket the record belongs to. |
| `{history_id}` | path | yes | The ID of the history record to get. |

**Response**

```typescript
// The response is the history record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/history/{history_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Create or update history record

```http
POST https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/history/{history_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket the record belongs to. |
| `{history_id}` | path | no | The ID of the history record to update. Leave out the segment to create a new record. |

**Request body**

```typescript
// Body should be the history record JSON as specified above.
```

**Example request body**

```json
{
    "DateTime": "2026-01-15T09:00:00Z",
    "Workflow.ItemStatus.ID": 2,
    "Comment": "Inspected on site before the ticket was raised"
}
```

**Response**

```typescript
// The response is the history record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/history/{history_id}";
const method = "post";
const token = "your-token";
const body = {
    "DateTime": "2026-01-15T09:00:00Z",
    "Workflow.ItemStatus.ID": 2,
    "Comment": "Inspected on site before the ticket was raised"
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Delete history record

```http
DELETE https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/history/{history_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ticket_id}` | path | yes | The ID of the ticket the record belongs to. |
| `{history_id}` | path | yes | The ID of the history record to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/item/{ticket_id}/history/{history_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apiworkflowtickets
