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

# List Visitors

> Returns the authenticated customer's registered visitors.

# List Visitors

Returns the list of visitors registered by the authenticated customer. Optionally filter to only upcoming visits.

## Authentication

Requires a valid customer bearer token.

## Query Parameters

<ParamField query="showUpcoming" type="boolean">
  `true` — return only future visits. `false` or omitted — return all visitors.
</ParamField>

<ParamField query="_shape" type="string">
  Comma-separated list of field paths to include in the response. When provided, only the
  specified fields are returned — useful for reducing payload size. Supports nested paths
  using dot notation. Example: `_shape=Records.FullName,Records.ExpectedArrival,Records.Arrived`.
</ParamField>

## Response

Returns a `VisitorList` object containing an array of visitor records.

### Visitor Fields

#### Identity

| Field      | Type     | Description                               |
| ---------- | -------- | ----------------------------------------- |
| `Id`       | `number` | Unique numeric identifier for the visitor |
| `UniqueId` | `string` | Globally unique identifier                |

#### Core

| Field         | Type             | Description                    |
| ------------- | ---------------- | ------------------------------ |
| `FullName`    | `string`         | Visitor's full name            |
| `Email`       | `string`         | Visitor's email address        |
| `PhoneNumber` | `string`         | Visitor's phone number         |
| `Notes`       | `string \| null` | Customer notes about the visit |

#### Schedule

| Field                | Type             | Description                            |
| -------------------- | ---------------- | -------------------------------------- |
| `ExpectedArrival`    | `string \| null` | Expected arrival (business-local time) |
| `UtcExpectedArrival` | `string \| null` | Expected arrival (UTC)                 |
| `ArrivalDate`        | `string \| null` | Actual arrival date (business-local)   |
| `UtcArrivalDate`     | `string \| null` | Actual arrival date (UTC)              |
| `Arrived`            | `boolean`        | Whether the visitor has arrived        |

#### Media

| Field                 | Type             | Description                           |
| --------------------- | ---------------- | ------------------------------------- |
| `GravatarHashedEmail` | `string \| null` | MD5-hashed email for Gravatar lookups |
| `DefaultAvatarUrl`    | `string \| null` | Generated avatar URL from initials    |

#### Timestamps (from base)

| Field          | Type             | Description                             |
| -------------- | ---------------- | --------------------------------------- |
| `CreatedOn`    | `string`         | Date created (business-local time)      |
| `UpdatedOn`    | `string \| null` | Date last updated (business-local time) |
| `CreatedOnUtc` | `string`         | Date created (UTC)                      |
| `UpdatedOnUtc` | `string \| null` | Date last updated (UTC)                 |

## Examples

### Fetch upcoming visitors

```http theme={null}
GET /api/public/visitors/my?showUpcoming=true
Authorization: Bearer {token}
```

## TypeScript Integration

```typescript theme={null}
import endpoints from '@/api/endpoints'

const { resource: visitors } = useTypedData(httpClient, endpoints.visitors.list(true))
```