> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.neetodesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tickets

> List, view, create, and update tickets, and manage their comments and drafts.

A ticket is the central work item in NeetoDesk. For fields and response details, see the [API reference](/api/tickets/list).

Everywhere a ticket ID is taken, the CLI accepts either the ticket's UUID or its
workspace-scoped number, so `neetodesk tickets show 1042` and
`neetodesk tickets show 0f1e4c9a-6d3b-4f92-8a71-25b0c8d4e6f3` do the same thing. The number is
the one shown in the web app, and is usually the easier of the two to type.

## List tickets

This command lists the tickets you can access. Use this when you want to triage a queue. Narrow it to the statuses you care about with a comma-separated `--status`.

```bash theme={"system"}
neetodesk tickets list --status open,pending --page-size 25
```

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--status` | `string` | | | Filter by status (comma-separated, e.g. open,pending) |
| `--customer-id` | `string` | | | Filter by customer ID |
| `--customer-email` | `string` | | | Filter by customer email |
| `--assignee-id` | `string` | | | Filter by assignee ID |
| `--assignee-email` | `string` | | | Filter by assignee email |
| `--field-name` | `string` | | | Custom ticket field to filter by, used with --field-value |
| `--field-value` | `string` | | | Value the custom ticket field must have, used with --field-name |
| `--range-type` | `string` | | | Date range type (e.g. last\_7\_days, last\_30\_days, custom) |
| `--start-date` | `string` | | | Start date for custom range (YYYY-MM-DD) |
| `--end-date` | `string` | | | End date for custom range (YYYY-MM-DD) |
| `--sort` | `string` | | `created_at` | Sort field: created\_at or updated\_at |
| `--order` | `string` | | `desc` | Sort direction: asc or desc |
| `--page` | `int` | | `0` | Page number |
| `--page-size` | `int` | | `0` | Items per page (max 100) |

```json Sample output (--json) theme={"system"}
{
  "data": [
    {
      "id": "0f1e4c9a-6d3b-4f92-8a71-25b0c8d4e6f3",
      "number": 1042,
      "subject": "Refund not received",
      "description": "The card was charged twice on 2 August.",
      "priority": "high",
      "status": "open",
      "category": "Billing",
      "sub_category_one": null,
      "sub_category_two": null,
      "created_at": "2026-08-03T09:14:22.000Z",
      "updated_at": "2026-08-03T11:02:41.000Z",
      "external_id": null,
      "source": null,
      "group": "Payments",
      "tags": ["refund"],
      "assignee": {
        "id": "7b2c1d40-5e6f-4a81-9c23-0d4e5f6a7b8c",
        "name": "Oliver Smith",
        "email": "oliver.smith@example.com"
      },
      "customer": {
        "id": "c4d5e6f7-8a9b-40c1-b2d3-e4f5a6b7c8d9",
        "name": "Sam Smith",
        "email": "customer@example.com",
        "phone_numbers": []
      },
      "fields": []
    }
  ],
  "breadcrumbs": [
    { "label": "Show", "command": "neetodesk tickets show <ticket-number>" },
    { "label": "Update", "command": "neetodesk tickets update <ticket-number>" }
  ],
  "pagination": {
    "total_records": 137,
    "total_pages": 6,
    "current_page_number": 1,
    "page_size": 25
  }
}
```

`assignee` and `customer` are left out when the ticket has none, and `fields` lists the custom
ticket fields as `field_name` and `field_value` pairs.

## Show a ticket

This command shows one ticket in full, including its description and the agent, customer, group, and tags it is associated with. Use this when you want to read a ticket before you act on it. The record has the same fields as a `tickets list` entry and sits under
a `ticket` key in `data`.

```bash theme={"system"}
neetodesk tickets show 1042
```

**Required arguments:**

* `<id>` - Ticket number or UUID

## Create a ticket

This command opens a ticket on behalf of a customer, identified by their email address. Use this when a request reaches you outside NeetoDesk. The description
becomes the ticket's first comment. If no customer with that email exists, one is created.

```bash theme={"system"}
neetodesk tickets create \
  --email customer@example.com \
  --subject "Refund not received" \
  --description "The card was charged twice on 2 August." \
  --priority high \
  --assignee-email oliver.smith@example.com
```

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--agent-id` | `string` | | | Agent ID to assign |
| `--assignee-email` | `string` | | | Agent email to assign |
| `--attach` | `stringArray` | | `[]` | Path to a file to attach (repeat the flag for more than one) |
| `--category` | `string` | | | Ticket category |
| `--description` | `string` | Yes | | Ticket description |
| `--email` | `string` | Yes | | Customer email |
| `--group-id` | `string` | | | Group ID to assign |
| `--name` | `string` | | | Customer name |
| `--priority` | `string` | | | Ticket priority (low, medium, high, urgent) |
| `--status` | `string` | | | Ticket status |
| `--subject` | `string` | Yes | | Ticket subject |

`--attach` attaches a file to the ticket's first comment. Repeat the flag for more than one
file. Every file is uploaded before the ticket is created, so a file that cannot be read or
uploaded fails the command and creates nothing. The CLI does not delete the files it had
already uploaded before the failure; they are left unattached and reclaimed automatically, so
re-running the command is safe.

```bash theme={"system"}
neetodesk tickets create \
  --email customer@example.com \
  --subject "Printer is jammed" \
  --description "Photo and log attached." \
  --attach ~/Desktop/printer.png \
  --attach ~/Desktop/error-log.txt
```

The response carries only the new ticket's identifiers and its URL in the web app. With
`--quiet` just the `id` is printed.

```json Sample output (--json) theme={"system"}
{
  "data": {
    "ticket": {
      "id": "0f1e4c9a-6d3b-4f92-8a71-25b0c8d4e6f3",
      "number": 1042,
      "url": "https://acme.neetodesk.com/admin/tickets/1042"
    }
  },
  "breadcrumbs": [
    { "label": "Show", "command": "neetodesk tickets show <ticket-number>" }
  ]
}
```

## Update a ticket

This command changes a ticket's subject, description, status, priority, category, assignee, or group, and adds files with `--attach`. Use this when you triage or resolve a ticket. Pass only the flags you want to change; the rest are left as they
are. The updated ticket comes back in full under a `ticket` key in `data`.

```bash theme={"system"}
neetodesk tickets update 1042 --status resolved --priority low

neetodesk tickets update 1042 --attach ~/Desktop/replacement-part.pdf
```

**Required arguments:**

* `<id>` - Ticket number or UUID

`--attach` adds each file to the ticket's opening message, beside the files already there, and
repeats for more than one file. A ticket that has no opening message cannot take files this
way; add them with [`tickets comments create --attach`](#create-a-comment) instead.
Attaching applies the workspace attachment limit, 10 MB by default, which is smaller than the
50 MB upload limit, so a file between the two uploads and is then refused.

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--agent-id` | `string` | | | Agent ID to assign |
| `--assignee-email` | `string` | | | Agent email to assign |
| `--attach` | `stringArray` | | `[]` | Path to a file to attach (repeat the flag for more than one) |
| `--category` | `string` | | | Ticket category |
| `--description` | `string` | | | Ticket description |
| `--group-id` | `string` | | | Group ID to assign |
| `--priority` | `string` | | | Ticket priority |
| `--status` | `string` | | | Ticket status |
| `--subject` | `string` | | | Ticket subject |

```json Sample output (--json) theme={"system"}
{
  "data": {
    "ticket": {
      "id": "0f1e4c9a-6d3b-4f92-8a71-25b0c8d4e6f3",
      "number": 1042,
      "subject": "Refund not received",
      "description": "The card was charged twice on 2 August.",
      "priority": "low",
      "status": "resolved",
      "category": "Billing",
      "sub_category_one": null,
      "sub_category_two": null,
      "created_at": "2026-08-03T09:14:22.000Z",
      "updated_at": "2026-08-03T11:02:41.000Z",
      "external_id": null,
      "source": null,
      "group": "Payments",
      "tags": ["refund"],
      "assignee": {
        "id": "7b2c1d40-5e6f-4a81-9c23-0d4e5f6a7b8c",
        "name": "Oliver Smith",
        "email": "oliver.smith@example.com"
      },
      "customer": {
        "id": "c4d5e6f7-8a9b-40c1-b2d3-e4f5a6b7c8d9",
        "name": "Sam Smith",
        "email": "customer@example.com",
        "phone_numbers": []
      },
      "fields": []
    }
  }
}
```

## List comments

This command lists a ticket's comments in the order they were added, each with its type, author, and body. Use this when you want to read the conversation on a ticket.

```bash theme={"system"}
neetodesk tickets comments list 1042
```

**Required arguments:**

* `<ticket-id>` - Ticket number or UUID

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--page` | `int` | | `0` | Page number |
| `--page-size` | `int` | | `0` | Items per page (max 100) |

```json Sample output (--json) theme={"system"}
{
  "data": [
    {
      "id": "3a9d7e21-4b8c-4d15-9e73-6f2a1b0c8d94",
      "created_at": "2026-08-03T11:02:41.000Z",
      "comment_type": "reply",
      "content": "<p>We have issued the refund.</p>",
      "author": {
        "id": "7b2c1d40-5e6f-4a81-9c23-0d4e5f6a7b8c",
        "name": "Oliver Smith",
        "email": "oliver.smith@example.com",
        "type": "agent"
      },
      "attachments": []
    }
  ],
  "breadcrumbs": [
    { "label": "Show", "command": "neetodesk tickets comments show 1042 <comment-id>" }
  ],
  "pagination": {
    "total_records": 3,
    "total_pages": 1,
    "current_page_number": 1,
    "page_size": 30
  }
}
```

A comment the system wrote has an `author` of type `system` with no id or email. Each entry in
`attachments` carries the file's `id`, `filename`, and `url`.

## Show a comment

This command shows one comment on a ticket, under a `comment` key in `data`. Use this when you want a single comment after finding its ID from `tickets comments list`.

```bash theme={"system"}
neetodesk tickets comments show 1042 3a9d7e21-4b8c-4d15-9e73-6f2a1b0c8d94
```

**Required arguments:**

* `<ticket-id>` - Ticket number or UUID
* `<comment-id>` - Comment UUID

## Create a comment

This command adds a comment to a ticket. Use this when you want to answer the customer or leave an internal note. A `reply` is published on the ticket where the customer reads it; a
`note` stays internal to the workspace. The comment is attributed to you, the signed-in user.
The new comment comes back under a `comment` key in `data`, and `--quiet` prints just its `id`.

```bash theme={"system"}
neetodesk tickets comments create 1042 \
  --content "<p>We have issued the refund.</p>" \
  --comment-type reply
```

**Required arguments:**

* `<ticket-id>` - Ticket number or UUID

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--attach` | `stringArray` | | `[]` | Path to a file to attach (repeat the flag for more than one) |
| `--comment-type` | `string` | | `reply` | Comment type: reply or note |
| `--content` | `string` | Yes | | Comment content (HTML) |

`--attach` attaches a file to the comment, and the flag repeats for more than one file. As with
`tickets create`, every file is uploaded first, so a file that cannot be read or uploaded fails
the command and adds no comment.

```bash theme={"system"}
neetodesk tickets comments create 1042 \
  --content "<p>Here is the replacement part.</p>" \
  --attach ~/Desktop/part-diagram.pdf
```

Use [`attachments upload`](/cli-reference/attachments#upload-a-file) when the file has to be
attached by a later call than the one that uploads it.

`tickets drafts create --attach` keeps a file on a draft until the draft is sent.

## Create a draft

This command saves an unsent draft on a ticket, replacing whichever draft the ticket already holds of that
type. A reply drafted for an agent, named with `--author-email`, gets that agent's saved
signature appended. Use this when a reply needs review before it is sent.

```bash theme={"system"}
neetodesk tickets drafts create 1042 \
  --content "<p>Checking with the payments team.</p>" \
  --author-email oliver.smith@example.com
```

**Required arguments:**

* `<ticket-id>` - Ticket number or UUID

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--attach` | `stringArray` | | `[]` | Path to a file to attach (repeat the flag for more than one) |
| `--author-email` | `string` | | | Author agent email |
| `--comment-type` | `string` | | `reply` | Draft type: reply or note |
| `--content` | `string` | Yes | | Draft content (HTML) |

```json Sample output (--json) theme={"system"}
{
  "data": {
    "draft": {
      "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "comment_type": "reply",
      "created_at": "2026-08-03T11:20:05.000Z",
      "updated_at": "2026-08-03T11:20:05.000Z",
      "content": "<p>Checking with the payments team.</p>"
    }
  }
}
```

The CLI can write drafts but not read them back.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.