# Holders

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

## List holder assignments {#list}

`GET /api/v1/holders`

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `email` | query | string · max 254 |  |  |
| `state` | query | "unassigned" \| "waiting" \| "owned" |  |  |
| `cursor` | query | string |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BLOCK_NOT_FOUND` |  | Check the block id and send the request again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `HOLDER_OWNED` |  | Use POST /api/v1/holders/reassign to move it. |
| `HOLDER_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `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. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `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. |

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

## Get a holder assignment and any pending transfer {#retrieve}

`GET /api/v1/holders/{id}`

Scopes: `passes:read`. SDK name: `pb.holders.retrieve`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BLOCK_NOT_FOUND` |  | Check the block id and send the request again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `HOLDER_OWNED` |  | Use POST /api/v1/holders/reassign to move it. |
| `HOLDER_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `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. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `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. |

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

## Set the holder email of an unowned pass {#assign}

`POST /api/v1/holders/assign`

Scopes: `holders:write`. SDK name: `pb.holders.assign`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `passId` | body | string · max 64 | yes |  |
| `email` | body | string · max 254 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BLOCK_NOT_FOUND` |  | Check the block id and send the request again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `HOLDER_OWNED` |  | Use POST /api/v1/holders/reassign to move it. |
| `HOLDER_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `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. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `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. |

```sh
curl -X POST "https://passbook.mobile/api/v1/holders/assign" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "passId": "0193a1b2-7c00-7000-8000-0000000000c1",
  "email": "ada@example.com"
}'
```

## Assign up to 100 holders {#bulkAssign}

`POST /api/v1/holders/assign-bulk`

Scopes: `holders:write`. SDK name: `pb.holders.bulkAssign`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | body | object[] | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BLOCK_NOT_FOUND` |  | Check the block id and send the request again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `HOLDER_OWNED` |  | Use POST /api/v1/holders/reassign to move it. |
| `HOLDER_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `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. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `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. |

```sh
curl -X POST "https://passbook.mobile/api/v1/holders/assign-bulk" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "passId": "0193a1b2-7c00-7000-8000-0000000000c1",
      "email": "ada@example.com"
    }
  ]
}'
```

## Stage a holder reassignment {#reassign}

`POST /api/v1/holders/reassign`

Scopes: `holders:write`. SDK name: `pb.holders.reassign`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `passId` | body | string · max 64 | yes |  |
| `email` | body | string \| null · max 254 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BLOCK_NOT_FOUND` |  | Check the block id and send the request again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `HOLDER_OWNED` |  | Use POST /api/v1/holders/reassign to move it. |
| `HOLDER_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `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. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `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. |

```sh
curl -X POST "https://passbook.mobile/api/v1/holders/reassign" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "passId": "0193a1b2-7c00-7000-8000-0000000000c1",
  "email": "ada@example.com"
}'
```

## Stage removal of the holder {#unassign}

`POST /api/v1/holders/unassign`

Scopes: `holders:write`. SDK name: `pb.holders.unassign`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `passId` | body | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BLOCK_NOT_FOUND` |  | Check the block id and send the request again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `HOLDER_OWNED` |  | Use POST /api/v1/holders/reassign to move it. |
| `HOLDER_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `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. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `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. |

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

## Allow a user to be attached again {#clearBlock}

`POST /api/v1/holders/clear-block`

Scopes: `holders:write`. SDK name: `pb.holders.clearBlock`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `passId` | body | string · max 64 | yes |  |
| `userId` | body | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BLOCK_NOT_FOUND` |  | Check the block id and send the request again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `HOLDER_OWNED` |  | Use POST /api/v1/holders/reassign to move it. |
| `HOLDER_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `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. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `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. |

```sh
curl -X POST "https://passbook.mobile/api/v1/holders/clear-block" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "passId": "0193a1b2-7c00-7000-8000-0000000000c1",
  "userId": "0193a1b2-7c00-7000-8000-0000000000e1"
}'
```

## Offboard a person: void or remove their passes and let go of their tags {#offboard}

`POST /api/v1/offboard`

Scopes: `passes:write`. SDK name: `pb.holders.offboard`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `holderEmail` | body | string · max 254 |  |  |
| `externalId` | body | string · max 200 |  |  |
| `passes` | body | "void" \| "remove" |  |  |
| `tags` | body | "spare" \| "lost" |  |  |
| `dryRun` | body | boolean |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BRAND_IMAGE_NOT_FOUND` |  | Upload the image with PUT /api/v1/orgs/{id}/branding/{slot} and use the URL it returns. |
| `BRAND_MARK_NOT_ALLOWED` |  | Remove the setting, or ask the platform owner to enable it for the organization. |
| `ENTITLEMENTS_CHANGED` |  | Fetch them with GET /api/v1/orgs/{id}/entitlements and send your change again. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDENTITY_NOT_FOUND` |  | Check the id with GET /api/v1/identities. |
| `IMAGE_BYTES` |  | Compress the image and upload it again. |
| `IMAGE_INVALID` |  | Export a standard PNG and upload it again. |
| `IMAGE_NOT_FOUND` |  | Upload one with PUT /api/v1/orgs/{id}/branding/{slot}. |
| `IMAGE_SCALE` |  | Resize so the @2x image is two thirds of the @3x, then upload both. |
| `IMAGE_SIZE` |  | Resize to the size named in issues and upload it again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVITATION_INVALID` |  | Ask an organization admin to send a new invitation with POST /api/v1/orgs/{id}/invitations. |
| `INVITATION_PENDING` |  | Revoke it to send a new one. |
| `LAST_ORG_ADMIN` |  | Make someone else an org admin first. |
| `MEMBERSHIP_CONFLICT` |  | Fetch it with GET /api/v1/orgs/{id}/memberships and send the change again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_CONFLICT` |  | Fetch it with GET /api/v1/orgs/{id} and send the change again. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_PERSONAL_SINGLE_MEMBER` |  | Use a regular organization to work with others. |
| `ORG_SLUG_RESERVED` |  | Choose a different slug. |
| `ORG_SLUG_TAKEN` |  | Choose a different slug. |
| `ORG_STATUS_ALONE` |  | Send the status change in its own request, then the other edits. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `SETTINGS_CHANGED` |  | Fetch them with GET /api/v1/settings and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/offboard" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "holderEmail": "ada@example.com",
  "passes": "void",
  "dryRun": true
}'
```
