---
title: "Workflow: Types and statuses"
section: "API Reference"
route: /apiworkflowtypes
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Workflow: Types and statuses

Every ticket has a workflow type and a status. The type says what kind of work it is, such as an inspection or a repair, and which statuses that work moves through. Statuses are shared across the account, and each type picks the ones it uses and the moves allowed between them.

This article will cover how to manage statuses and types, and how a type's status flow is set. You can read about tickets in [Workflow: Tickets](/apiworkflowtickets).

## Statuses

Below is the data model for a status. A ticket is finished when its status is an end status.

```typescript
interface IStatus {
    // Unique ID for the status.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Limited to 30 characters.
    DisplayName: string;
    // Description of what the status means.
    Description?: string;
    // css colour used for the status. Limited to 12 characters. Eg: "#8F8".
    Color?: string;
    // If true then a ticket in this status is finished.
    // Default is false.
    IsEnd?: boolean;
    // "E" for an end status, "P" for a status where work is still in progress.
    // Default is "P". Set it to match "IsEnd", as Operator reads this one.
    Type?: "E" | "P";
    // Only returned when requesting a type's statuses.
    // The status IDs a ticket of that type can move to next from this status.
    "NextStatus.ID"?: number[];
}
```

### Get a list of statuses

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

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

**Response**

```typescript
interface IResponse {
    Items: IStatus[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/statuses";
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 status by ID

```http
GET https://{accountId}.api.nextspace.host/workflow/status/{status_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. |
| `{status_id}` | path | yes | The ID of the status to get. |

**Response**

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

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/status/{status_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);
});
```

You can create a status by setting the ID as '0', or update one by its ID. When updating, only the properties you include are changed.

### Create or update status

```http
POST https://{accountId}.api.nextspace.host/workflow/status/{status_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. |
| `{status_id}` | path | yes | The ID of the status to update. Set as 0 to create a new record. |

**Request body**

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

**Example request body**

```json
{
    "DisplayName": "Complete",
    "Color": "#8F8",
    "IsEnd": true,
    "Type": "E"
}
```

**Response**

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

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/status/{status_id}";
const method = "post";
const token = "your-token";
const body = {
    "DisplayName": "Complete",
    "Color": "#8F8",
    "IsEnd": true,
    "Type": "E"
};

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);
});
```

A status cannot be deleted while a ticket, schedule or type still uses it.

### Delete status

```http
DELETE https://{accountId}.api.nextspace.host/workflow/status/{status_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. |
| `{status_id}` | path | yes | The ID of the status to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/status/{status_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);
});
```

## Types

Below is the data model for a type. When a ticket is created, it starts in the type's default status and queue, and its own Entity is created with the type's Entity Type.

```typescript
interface IType {
    // Unique ID for the type.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Limited to 30 characters.
    DisplayName: string;
    // Description of what the type is for.
    Description?: string;
    // css colour used for the type. Limited to 12 characters.
    Color?: string;
    // Status ID new tickets start in.
    "Default.Status.ID"?: number;
    // Queue ID new tickets start in.
    "Default.Queue.ID"?: number;
    // Entity Type ID for each ticket's own Entity, which sets the attributes a ticket collects.
    // Limited to 64 characters.
    "Default.EntityType.ID"?: string;
    // The statuses this type uses and the moves allowed between them.
    // See the Types: Status flow section below.
    StatusSettingsDiagram?: IStatusDiagram;
    Settings?: {
        AutoCleanup?: {
            // Deletes tickets that have sat in an end status, untouched, for this many days.
            DeleteClosed?: {
                Enabled: boolean;
                // At least 1 when enabled.
                Days: number;
            };
        };
    };
}
```

### Get a list of types

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

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

**Response**

```typescript
interface IResponse {
    Items: IType[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/types";
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 type by ID

```http
GET https://{accountId}.api.nextspace.host/workflow/type/{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 ID of the type to get. |

**Response**

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

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/type/{type_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);
});
```

You can create a type by setting the ID as '0', or update one by its ID. When updating, only the properties you include are changed.

### Create or update type

```http
POST https://{accountId}.api.nextspace.host/workflow/type/{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>".
- 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. |
| `{type_id}` | path | yes | The ID of the type to update. Set as 0 to create a new record. |

**Request body**

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

**Example request body**

```json
{
    "DisplayName": "Inspection",
    "Default.Status.ID": 5,
    "Default.Queue.ID": 1,
    "Default.EntityType.ID": "your-entity-type-id"
}
```

**Response**

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

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/type/{type_id}";
const method = "post";
const token = "your-token";
const body = {
    "DisplayName": "Inspection",
    "Default.Status.ID": 5,
    "Default.Queue.ID": 1,
    "Default.EntityType.ID": "your-entity-type-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);
});
```

Deleting a type also deletes every ticket and schedule of that type. Its Entity Type is deleted too, when it holds nothing but those tickets and no other type uses it.

### Delete type

```http
DELETE https://{accountId}.api.nextspace.host/workflow/type/{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>".
- 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. |
| `{type_id}` | path | yes | The ID of the type to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/type/{type_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);
});
```

## Types: Status flow

A type's "StatusSettingsDiagram" is the flow chart Operator draws for it. Each shape is a status the type uses, and each connection is a move allowed from one status to another.

Saving a type with a diagram replaces its statuses and allowed moves with the ones in the diagram, so always send the whole diagram.

```typescript
interface IStatusDiagram {
    // The statuses the type uses.
    Shapes: {
        // Status ID.
        Key: number;
        // Status name shown on the shape.
        Text?: string;
        // Where the shape is drawn, in pixels.
        Position?: { X: number; Y: number; };
        Size?: { Width: number; Height: number; };
        Shape?: "Circle";
        Color?: string;
    }[];
    // The moves allowed between statuses.
    Connections: {
        // Shape is the status ID. Socket is the side of the shape the line is drawn from: "L", "R", "T" or "B".
        From: { Shape: number; Socket?: string; };
        To: { Shape: number; Socket?: string; };
    }[];
}
```

Here is a flow where a ticket moves from "In progress" (4) to "Testing" (6), and from there to either "Complete" (7) or "Failed" (8).

```typescript
{
    Shapes: [
        { Key: 4, Text: "In progress", Position: { X: 100, Y: 200 } },
        { Key: 6, Text: "Testing", Position: { X: 350, Y: 200 } },
        { Key: 7, Text: "Complete", Position: { X: 600, Y: 100 } },
        { Key: 8, Text: "Failed", Position: { X: 600, Y: 300 } }
    ],
    Connections: [
        { From: { Shape: 4, Socket: "R" }, To: { Shape: 6, Socket: "L" } },
        { From: { Shape: 6, Socket: "R" }, To: { Shape: 7, Socket: "L" } },
        { From: { Shape: 6, Socket: "R" }, To: { Shape: 8, Socket: "L" } }
    ]
}
```

## Types: Enabled statuses

You can request the statuses a type uses, each with the status IDs a ticket can move to next. Use this to offer only the allowed moves, as the API does not check them when a ticket is updated.

### Get a type's statuses

```http
GET https://{accountId}.api.nextspace.host/workflow/type/{type_id}/statuses
```

**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 ID of the type to get the statuses of. |

**Response**

```typescript
interface IResponse {
    // Statuses as specified above, each with "NextStatus.ID".
    Items: IStatus[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/type/{type_id}/statuses";
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);
});
```

You can also add or remove statuses without changing the diagram. These do not change the allowed moves, and the next save of the type with a diagram replaces them.

### Add statuses to a type

```http
POST https://{accountId}.api.nextspace.host/workflow/type/{type_id}/status/add
```

**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. |
| `{type_id}` | path | yes | The ID of the type to add the statuses to. |

**Request body**

```typescript
interface IBody {
    "WorkflowStatus.ID": number[];
}
```

**Example request body**

```json
{
    "WorkflowStatus.ID": [
        4,
        6
    ]
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/type/{type_id}/status/add";
const method = "post";
const token = "your-token";
const body = {
    "WorkflowStatus.ID": [
        4,
        6
    ]
};

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);
});
```

### Remove statuses from a type

```http
POST https://{accountId}.api.nextspace.host/workflow/type/{type_id}/status/remove
```

**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. |
| `{type_id}` | path | yes | The ID of the type to remove the statuses from. |

**Request body**

```typescript
interface IBody {
    "WorkflowStatus.ID": number[];
}
```

**Example request body**

```json
{
    "WorkflowStatus.ID": [
        8
    ]
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/workflow/type/{type_id}/status/remove";
const method = "post";
const token = "your-token";
const body = {
    "WorkflowStatus.ID": [
        8
    ]
};

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/apiworkflowtypes
