# Visitors

Scanning · PassBook API reference. Authenticate with `Authorization: Bearer $PASSBOOK_KEY`.

## List visitors for a day {#list}

`GET /api/v1/visitors`

Scopes: `passes:read`. SDK name: `pb.visitors.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tab` | query | "today" \| "upcoming" \| "past" |  |  |
| `dayStart` | query | integer \| null · ≥ 0 |  |  |
| `dayEnd` | query | integer \| null · ≥ 0 |  |  |
| `cursor` | query | string · max 512 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_INSIDE` |  | Do nothing; check occupancy before marking out. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VISITOR_CHANGED` |  | Fetch the visitor list with GET /api/v1/visitors and send your change again. |
| `VISITOR_HOST_NOTICE_FAILED` |  | Send the request again; the visit is still recorded. |
| `VISITOR_HOST_UNKNOWN` |  | Choose a host from GET /api/v1/visitors/hosts. |
| `VISITOR_IN` |  | Check them out first. |
| `VISITOR_NOT_FOUND` |  | Check the id with GET /api/v1/visitors. |
| `VISITOR_NOT_IN` |  | Check them in before this action. |
| `VISITOR_OUT` |  | Do nothing; check status with GET /api/v1/visitors. |
| `VISITOR_RESEND_LIMIT` |  | Contact the host another way. |
| `VISITOR_TEMPLATE_MISSING` |  | Set up the visitor template in the console, then retry. |

```sh
curl -X GET "https://passbook.mobile/api/v1/visitors?dayStart=1764000000000&dayEnd=1764086400000" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Invite a visitor: a visitor pass with a host {#create}

`POST /api/v1/visitors`

Scopes: `passes:write`. SDK name: `pb.visitors.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | body | string · max 64 | yes |  |
| `name` | body | string · max 80 | yes |  |
| `windowFrom` | body | integer · ≥ 0 | yes |  |
| `windowUntil` | body | integer · ≥ 0 | yes |  |
| `email` | body | string · max 254 |  |  |
| `hostUserId` | body | string · max 64 |  |  |
| `hostName` | body | string · max 80 |  |  |
| `hostEmail` | body | string · max 254 |  |  |
| `note` | body | string · max 100 |  |  |
| `templateId` | body | string · max 64 |  |  |

Returns `201`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_INSIDE` |  | Do nothing; check occupancy before marking out. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VISITOR_CHANGED` |  | Fetch the visitor list with GET /api/v1/visitors and send your change again. |
| `VISITOR_HOST_NOTICE_FAILED` |  | Send the request again; the visit is still recorded. |
| `VISITOR_HOST_UNKNOWN` |  | Choose a host from GET /api/v1/visitors/hosts. |
| `VISITOR_IN` |  | Check them out first. |
| `VISITOR_NOT_FOUND` |  | Check the id with GET /api/v1/visitors. |
| `VISITOR_NOT_IN` |  | Check them in before this action. |
| `VISITOR_OUT` |  | Do nothing; check status with GET /api/v1/visitors. |
| `VISITOR_RESEND_LIMIT` |  | Contact the host another way. |
| `VISITOR_TEMPLATE_MISSING` |  | Set up the visitor template in the console, then retry. |

```sh
curl -X POST "https://passbook.mobile/api/v1/visitors" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "name": "Ada Example",
  "hostName": "Grace Host",
  "hostEmail": "grace@example.com",
  "windowFrom": 1764000000000,
  "windowUntil": 1764086400000
}'
```

## People who can host a visitor: the org members {#listHosts}

`GET /api/v1/visitors/hosts`

Scopes: `passes:read`. SDK name: `pb.visitors.listHosts`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string · max 512 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_INSIDE` |  | Do nothing; check occupancy before marking out. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VISITOR_CHANGED` |  | Fetch the visitor list with GET /api/v1/visitors and send your change again. |
| `VISITOR_HOST_NOTICE_FAILED` |  | Send the request again; the visit is still recorded. |
| `VISITOR_HOST_UNKNOWN` |  | Choose a host from GET /api/v1/visitors/hosts. |
| `VISITOR_IN` |  | Check them out first. |
| `VISITOR_NOT_FOUND` |  | Check the id with GET /api/v1/visitors. |
| `VISITOR_NOT_IN` |  | Check them in before this action. |
| `VISITOR_OUT` |  | Do nothing; check status with GET /api/v1/visitors. |
| `VISITOR_RESEND_LIMIT` |  | Contact the host another way. |
| `VISITOR_TEMPLATE_MISSING` |  | Set up the visitor template in the console, then retry. |

```sh
curl -X GET "https://passbook.mobile/api/v1/visitors/hosts" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Check a visitor out {#checkOut}

`POST /api/v1/visitors/{id}/check-out`

Scopes: `passes:write`. SDK name: `pb.visitors.checkOut`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NOT_INSIDE` |  | Do nothing; check occupancy before marking out. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VISITOR_CHANGED` |  | Fetch the visitor list with GET /api/v1/visitors and send your change again. |
| `VISITOR_HOST_NOTICE_FAILED` |  | Send the request again; the visit is still recorded. |
| `VISITOR_HOST_UNKNOWN` |  | Choose a host from GET /api/v1/visitors/hosts. |
| `VISITOR_IN` |  | Check them out first. |
| `VISITOR_NOT_FOUND` |  | Check the id with GET /api/v1/visitors. |
| `VISITOR_NOT_IN` |  | Check them in before this action. |
| `VISITOR_OUT` |  | Do nothing; check status with GET /api/v1/visitors. |
| `VISITOR_RESEND_LIMIT` |  | Contact the host another way. |
| `VISITOR_TEMPLATE_MISSING` |  | Set up the visitor template in the console, then retry. |

```sh
curl -X POST "https://passbook.mobile/api/v1/visitors/0193a1b2-7c00-7000-8000-0000000000e1/check-out" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Cancel a visit and void its pass {#cancel}

`POST /api/v1/visitors/{id}/cancel`

Scopes: `passes:write`. SDK name: `pb.visitors.cancel`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NOT_INSIDE` |  | Do nothing; check occupancy before marking out. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VISITOR_CHANGED` |  | Fetch the visitor list with GET /api/v1/visitors and send your change again. |
| `VISITOR_HOST_NOTICE_FAILED` |  | Send the request again; the visit is still recorded. |
| `VISITOR_HOST_UNKNOWN` |  | Choose a host from GET /api/v1/visitors/hosts. |
| `VISITOR_IN` |  | Check them out first. |
| `VISITOR_NOT_FOUND` |  | Check the id with GET /api/v1/visitors. |
| `VISITOR_NOT_IN` |  | Check them in before this action. |
| `VISITOR_OUT` |  | Do nothing; check status with GET /api/v1/visitors. |
| `VISITOR_RESEND_LIMIT` |  | Contact the host another way. |
| `VISITOR_TEMPLATE_MISSING` |  | Set up the visitor template in the console, then retry. |

```sh
curl -X POST "https://passbook.mobile/api/v1/visitors/0193a1b2-7c00-7000-8000-0000000000e1/cancel" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Send the host their arrival email again {#sendHostEmail}

`POST /api/v1/visitors/{id}/host-email`

Scopes: `passes:write`. SDK name: `pb.visitors.sendHostEmail`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `timeZone` | body | string · max 64 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NOT_INSIDE` |  | Do nothing; check occupancy before marking out. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VISITOR_CHANGED` |  | Fetch the visitor list with GET /api/v1/visitors and send your change again. |
| `VISITOR_HOST_NOTICE_FAILED` |  | Send the request again; the visit is still recorded. |
| `VISITOR_HOST_UNKNOWN` |  | Choose a host from GET /api/v1/visitors/hosts. |
| `VISITOR_IN` |  | Check them out first. |
| `VISITOR_NOT_FOUND` |  | Check the id with GET /api/v1/visitors. |
| `VISITOR_NOT_IN` |  | Check them in before this action. |
| `VISITOR_OUT` |  | Do nothing; check status with GET /api/v1/visitors. |
| `VISITOR_RESEND_LIMIT` |  | Contact the host another way. |
| `VISITOR_TEMPLATE_MISSING` |  | Set up the visitor template in the console, then retry. |

```sh
curl -X POST "https://passbook.mobile/api/v1/visitors/0193a1b2-7c00-7000-8000-0000000000e1/host-email" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```
