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

# Visitors

> List, inspect and create the people who chat with a workspace.

Commands for the people who chat with a workspace. The API calls this
resource a contact; the CLI calls it a visitor. For fields and response
details, see the [Contacts API reference](https://apidocs.neetochat.com/api-reference/contacts/list.md).

Samples on this page use `--json`, which is the format you get when output is
piped as well. On a terminal without that flag the same data prints as a table.
See [Output formats](https://apidocs.neetochat.com/cli/output-formats.md).

## List visitors

Visitors in the workspace, oldest first. `--email` and `--user-identifier`
are not unique: the chat widget creates a separate visitor for each browser a
person chats from, so either filter can return more than one match.

```bash theme={"system"}
neetochat visitors list --json
```

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--email` | `string` | | | Filter by email (not unique; may match more than one visitor) |
| `--page` | `int` | | `0` | Page number |
| `--page-size` | `int` | | `0` | Items per page (max 100) |
| `--user-identifier` | `string` | | | Filter by user identifier |

```json theme={"system"}
{
  "data": [
    {
      "id": "2c79a334-0bc8-44e4-9504-331f59d400ab",
      "name": "Sam Brown",
      "email": "sam@example.com",
      "phone_number": null,
      "user_identifier": "customer-1042",
      "traits": {
        "plan": "Pro"
      },
      "created_at": "2026-10-08T14:35:46.785Z",
      "updated_at": "2026-10-08T14:35:46.785Z",
      "field_values": []
    }
  ],
  "breadcrumbs": [
    {
      "label": "Show",
      "command": "neetochat visitors show <id>"
    }
  ],
  "pagination": {
    "current_page_number": 1,
    "total_pages": 1,
    "total_records": 1,
    "page_size": 30
  }
}
```

## Show a visitor

One visitor by id, when you already have it and want the full record.

```bash theme={"system"}
neetochat visitors show 2c79a334-0bc8-44e4-9504-331f59d400ab --json
```

**Required arguments:**

| Argument | Description |
| - | - |
| `<id>` | The visitor's UUID, from `neetochat visitors list`. |

This command takes no flags of its own.

```json theme={"system"}
{
  "data": {
    "contact": {
      "id": "2c79a334-0bc8-44e4-9504-331f59d400ab",
      "name": "Sam Brown",
      "email": "sam@example.com",
      "phone_number": null,
      "user_identifier": "customer-1042",
      "traits": {
        "plan": "Pro"
      },
      "created_at": "2026-10-08T14:35:46.785Z",
      "updated_at": "2026-10-08T14:35:46.785Z",
      "field_values": []
    }
  },
  "breadcrumbs": [
    {
      "label": "List",
      "command": "neetochat visitors list"
    }
  ]
}
```

## Create a visitor

Adds a visitor to the workspace. Every field is optional; the name defaults
to `Visitor` when left out.

```bash theme={"system"}
neetochat visitors create \
  --name "Sam Brown" \
  --email sam@example.com \
  --user-identifier customer-1042 \
  --trait plan=Pro
```

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--name` | `string` | | | Visitor name |
| `--email` | `string` | | | Visitor email |
| `--phone-number` | `string` | | | Visitor phone number |
| `--user-identifier` | `string` | | | Visitor identifier from your own system |
| `--trait` | `stringToString` | | `[]` | Visitor trait as key=value (repeat the flag for more than one) |
| `--field` | `stringToString` | | `[]` | Custom field value as field-id=value (repeat the flag for more than one) |

```json theme={"system"}
{
  "data": {
    "contact": {
      "id": "2c79a334-0bc8-44e4-9504-331f59d400ab",
      "name": "Sam Brown",
      "email": "sam@example.com",
      "phone_number": null,
      "user_identifier": "customer-1042",
      "traits": {
        "plan": "Pro"
      },
      "created_at": "2026-10-08T14:35:46.785Z",
      "updated_at": "2026-10-08T14:35:46.785Z",
      "field_values": []
    }
  },
  "breadcrumbs": [
    {
      "label": "Show",
      "command": "neetochat visitors show <id>"
    }
  ]
}
```

`--trait` sets a free-form custom attribute and can be repeated for more than
one, for example `--trait plan=Pro --trait country=US`. `--field` sets a value
for one of the workspace's contact fields instead, keyed by the field's UUID
rather than its name: `--field 7f1f1f36-1f0f-4a0e-9b1f-2b0f3c4d5e6f=Enterprise`.

> [!TIP]
>
> With `--quiet` the command prints only the new record's identifier, which is
> convenient in a script.


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