# Passes

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

## List passes {#list}

`GET /api/v1/passes`

Lists passes, newest first. Filter by template, status, holder email or `externalId`; page with `cursor`.

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `templateId` | query | string · max 64 |  |  |
| `connectionId` | query | string · max 64 |  |  |
| `importId` | query | string · max 64 |  |  |
| `status` | query | "active" \| "voided" \| "removed" |  |  |
| `holderEmail` | query | string · max 254 |  |  |
| `holderState` | query | "unassigned" \| "waiting" \| "owned" |  |  |
| `onDevice` | query | "true" \| "false" |  |  |
| `q` | query | string · max 200 |  |  |
| `externalId` | query | string · max 200 |  |  |
| `scan` | query | string · max 200 |  |  |
| `match` | query | string · max 2000 |  |  |
| `cursor` | query | string · max 512 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |

Returns `200`, a `PassPage`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X GET "https://passbook.mobile/api/v1/passes?limit=25" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "items": [
    {
      "id": "0193a1b2-7c00-7000-8000-0000000000c1",
      "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
      "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
      "templateVersion": "3",
      "identityId": "0193a1b2-7c00-7000-8000-0000000000d1",
      "serial": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
      "title": "Ada Example",
      "subtitle": "Row 4, seat 12",
      "externalId": "booking_8841",
      "status": "active",
      "mode": "test",
      "version": 1,
      "connectionId": null,
      "externalRef": null,
      "syncErrorCode": null,
      "holderEmail": "ada@example.com",
      "holderState": "waiting",
      "ownerUserId": null,
      "deviceCount": 0,
      "removedAt": null,
      "modifiedAt": 1764000000000,
      "createdAt": 1764000000000
    }
  ],
  "nextCursor": null
}
```

## Create a pass {#create}

`POST /api/v1/passes`

Creates a pass from a template. `input` holds the template's fields; see `sample` on the template. Send an `Idempotency-Key` header to retry safely. Set `sendEmail` with `holderEmail` to email the pass.

Scopes: `passes:write`. Idempotent with an `Idempotency-Key` header. SDK name: `pb.passes.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string · max 200 |  | 1 to 200 characters. A retry with the same key and body returns the first result. |
| `templateId` | body | string · max 64 | yes |  |
| `input` | body | object | yes | The template's fields. GET /templates/{id}/input-schema returns the schema. |
| `mode` | body | "live" \| "test" |  |  |
| `templateVersion` | body | string |  |  |
| `releaseId` | body | string · max 64 |  |  |
| `releaseGeneration` | body | integer |  |  |
| `identityId` | body | string · max 64 |  |  |
| `holderEmail` | body | string · max 254 |  |  |
| `externalId` | body | string · max 200 |  | Your own key for the pass, any time. Filter with GET /passes?externalId=. Unique per org and mode only if the template says so. |
| `serial` | body | string · ^[A-Za-z0-9._~-]{1,100}$ |  | Sets the Wallet serial. Honored only on the organization's own signing identity; the platform identity picks its own. |
| `connectionId` | body | string · max 64 |  | Binds the pass to a connection. Send with externalRef. |
| `externalRef` | body | string · max 500 |  | The upstream record id, for passes created by a connection. Send with connectionId. |
| `sendEmail` | body | boolean |  |  |

Returns `201`, a `PassDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X POST "https://passbook.mobile/api/v1/passes" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "input": {
    "eventName": "Harbor Night",
    "venueName": "Harbor Hall",
    "venueRegion": "Cupertino, CA",
    "startsAt": "2030-06-01T19:00:00-07:00",
    "endsAt": "2030-06-01T22:00:00-07:00",
    "attendee": "Ada Example",
    "ticketId": "TICKET-0001"
  },
  "holderEmail": "ada@example.com",
  "externalId": "booking_8841",
  "sendEmail": true
}'
```

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000c1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "templateVersion": "3",
  "identityId": "0193a1b2-7c00-7000-8000-0000000000d1",
  "serial": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
  "title": "Harbor Night",
  "subtitle": "Ada Example",
  "externalId": "booking_8841",
  "status": "active",
  "mode": "test",
  "version": 1,
  "connectionId": null,
  "externalRef": null,
  "syncErrorCode": null,
  "holderEmail": "ada@example.com",
  "holderState": "waiting",
  "ownerUserId": null,
  "deviceCount": 0,
  "removedAt": null,
  "modifiedAt": 1764000000000,
  "createdAt": 1764000000000,
  "reissueRequired": false,
  "ownerName": null,
  "ownerEmail": null,
  "personalization": {
    "eventName": "Harbor Night",
    "venueName": "Harbor Hall",
    "venueRegion": "Cupertino, CA",
    "startsAt": "2030-06-01T19:00:00-07:00",
    "endsAt": "2030-06-01T22:00:00-07:00",
    "attendee": "Ada Example",
    "ticketId": "TICKET-0001"
  },
  "fieldSources": {
    "eventName": "manual",
    "venueName": "manual",
    "venueRegion": "manual",
    "startsAt": "manual",
    "endsAt": "manual",
    "attendee": "manual",
    "ticketId": "manual"
  },
  "registrations": 0,
  "lastRefreshedAt": null,
  "versions": [
    {
      "version": 1,
      "templateVersion": "3",
      "cause": "create",
      "source": null,
      "actorType": "api_key",
      "actorId": null,
      "createdAt": 1764000000000,
      "purged": false
    }
  ],
  "deliveries": [],
  "warnings": [],
  "passJson": {
    "formatVersion": 1,
    "passTypeIdentifier": "pass.example.wallet",
    "serialNumber": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
    "organizationName": "Example Events",
    "description": "Event ticket",
    "eventTicket": {
      "primaryFields": [
        {
          "key": "event",
          "label": "Event",
          "value": "Harbor Night"
        }
      ]
    }
  },
  "assetBaseUrl": "https://wallet.example.com/assets/0193a1b2-7c00-7000-8000-0000000000c1/",
  "assetNames": [
    "icon.png",
    "icon@2x.png",
    "logo.png"
  ],
  "blockedUsers": [],
  "downloadUrl": "https://wallet.example.com/p/0193a1b2-7c00-7000-8000-0000000000c1.pkpass",
  "publicUrl": "https://wallet.example.com/p/xK3v9QmT2Lw8",
  "email": {
    "outcome": "queued"
  }
}
```

## Get a pass {#retrieve}

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

One pass with its fields, links and channels.

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

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

Returns `200`, a `PassDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000c1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "templateVersion": "3",
  "identityId": "0193a1b2-7c00-7000-8000-0000000000d1",
  "serial": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
  "title": "Ada Example",
  "subtitle": "Row 4, seat 12",
  "externalId": "booking_8841",
  "status": "active",
  "mode": "test",
  "version": 1,
  "connectionId": null,
  "externalRef": null,
  "syncErrorCode": null,
  "holderEmail": "ada@example.com",
  "holderState": "waiting",
  "ownerUserId": null,
  "deviceCount": 0,
  "removedAt": null,
  "modifiedAt": 1764000000000,
  "createdAt": 1764000000000,
  "reissueRequired": false,
  "ownerName": null,
  "ownerEmail": null,
  "personalization": {
    "name": "Ada Example",
    "seat": "Row 4, seat 12"
  },
  "fieldSources": {
    "name": "manual",
    "seat": "manual"
  },
  "registrations": 0,
  "lastRefreshedAt": null,
  "versions": [
    {
      "version": 1,
      "templateVersion": "3",
      "cause": "create",
      "source": null,
      "actorType": "api_key",
      "actorId": null,
      "createdAt": 1764000000000,
      "purged": false
    }
  ],
  "deliveries": [],
  "warnings": [],
  "passJson": {
    "formatVersion": 1,
    "passTypeIdentifier": "pass.example.wallet",
    "serialNumber": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
    "organizationName": "Example Events",
    "description": "Event ticket",
    "eventTicket": {
      "primaryFields": [
        {
          "key": "name",
          "label": "Guest",
          "value": "Ada Example"
        }
      ]
    }
  },
  "assetBaseUrl": "https://wallet.example.com/assets/0193a1b2-7c00-7000-8000-0000000000c1/",
  "assetNames": [
    "icon.png",
    "icon@2x.png",
    "logo.png"
  ],
  "blockedUsers": [],
  "downloadUrl": "https://wallet.example.com/p/0193a1b2-7c00-7000-8000-0000000000c1.pkpass",
  "publicUrl": "https://wallet.example.com/p/xK3v9QmT2Lw8"
}
```

## Update a pass {#update}

`PATCH /api/v1/passes/{id}`

Changes a pass's fields. Send `If-Match` with the current `version`; a stale version is `412 VERSION_CONFLICT`. Installed passes update in Wallet.

Scopes: `passes:write`. SDK name: `pb.passes.update`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `input` | body | object |  |  |
| `templateVersion` | body | string |  |  |
| `externalId` | body | string \| null · max 200 |  |  |
| `resetToConnection` | body | string[] |  |  |
| `notify` | body | boolean |  |  |

Returns `200`, a `PassDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_CONFLICT` |  | GET the pass, apply your change to it, and resend with the new version. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X PATCH "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "seat": "Row 5, seat 3"
  },
  "notify": true
}'
```

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000c1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "templateVersion": "3",
  "identityId": "0193a1b2-7c00-7000-8000-0000000000d1",
  "serial": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
  "title": "Ada Example",
  "subtitle": "Row 4, seat 12",
  "externalId": "booking_8841",
  "status": "active",
  "mode": "test",
  "version": 2,
  "connectionId": null,
  "externalRef": null,
  "syncErrorCode": null,
  "holderEmail": "ada@example.com",
  "holderState": "waiting",
  "ownerUserId": null,
  "deviceCount": 0,
  "removedAt": null,
  "modifiedAt": 1764000000000,
  "createdAt": 1764000000000,
  "reissueRequired": false,
  "ownerName": null,
  "ownerEmail": null,
  "personalization": {
    "name": "Ada Example",
    "seat": "Row 5, seat 3"
  },
  "fieldSources": {
    "name": "manual",
    "seat": "manual"
  },
  "registrations": 0,
  "lastRefreshedAt": null,
  "versions": [
    {
      "version": 1,
      "templateVersion": "3",
      "cause": "create",
      "source": null,
      "actorType": "api_key",
      "actorId": null,
      "createdAt": 1764000000000,
      "purged": false
    }
  ],
  "deliveries": [],
  "warnings": [],
  "passJson": {
    "formatVersion": 1,
    "passTypeIdentifier": "pass.example.wallet",
    "serialNumber": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
    "organizationName": "Example Events",
    "description": "Event ticket",
    "eventTicket": {
      "primaryFields": [
        {
          "key": "name",
          "label": "Guest",
          "value": "Ada Example"
        }
      ]
    }
  },
  "assetBaseUrl": "https://wallet.example.com/assets/0193a1b2-7c00-7000-8000-0000000000c1/",
  "assetNames": [
    "icon.png",
    "icon@2x.png",
    "logo.png"
  ],
  "blockedUsers": [],
  "downloadUrl": "https://wallet.example.com/p/0193a1b2-7c00-7000-8000-0000000000c1.pkpass",
  "publicUrl": "https://wallet.example.com/p/xK3v9QmT2Lw8",
  "email": {
    "outcome": "queued"
  }
}
```

## Delete a pass {#delete}

`DELETE /api/v1/passes/{id}`

Deletes the pass record. To take a pass out of Wallet and keep the record, use remove.

Scopes: `passes:write`. SDK name: `pb.passes.delete`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "ok": true
}
```

## Void a pass {#void}

`POST /api/v1/passes/{id}/void`

Voids a pass. Wallet shows it as void and scans are refused. Undo with unvoid.

Scopes: `passes:write`. SDK name: `pb.passes.void`.

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

Returns `200`, a `PassSummary`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000c1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "templateVersion": "3",
  "identityId": "0193a1b2-7c00-7000-8000-0000000000d1",
  "serial": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
  "title": "Ada Example",
  "subtitle": "Row 4, seat 12",
  "externalId": "booking_8841",
  "status": "voided",
  "mode": "test",
  "version": 2,
  "connectionId": null,
  "externalRef": null,
  "syncErrorCode": null,
  "holderEmail": "ada@example.com",
  "holderState": "waiting",
  "ownerUserId": null,
  "deviceCount": 0,
  "removedAt": null,
  "modifiedAt": 1764000000000,
  "createdAt": 1764000000000
}
```

## Unvoid a pass {#unvoid}

`POST /api/v1/passes/{id}/unvoid`

Undoes a void.

Scopes: `passes:write`. SDK name: `pb.passes.unvoid`.

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

Returns `200`, a `PassSummary`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000c1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "templateVersion": "3",
  "identityId": "0193a1b2-7c00-7000-8000-0000000000d1",
  "serial": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
  "title": "Ada Example",
  "subtitle": "Row 4, seat 12",
  "externalId": "booking_8841",
  "status": "active",
  "mode": "test",
  "version": 3,
  "connectionId": null,
  "externalRef": null,
  "syncErrorCode": null,
  "holderEmail": "ada@example.com",
  "holderState": "waiting",
  "ownerUserId": null,
  "deviceCount": 0,
  "removedAt": null,
  "modifiedAt": 1764000000000,
  "createdAt": 1764000000000
}
```

## Rebuild from the connection and re-push {#refresh}

`POST /api/v1/passes/{id}/refresh`

Scopes: `passes:write`. SDK name: `pb.passes.refresh`.

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

Returns `202`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Rotate the download link {#rotateLink}

`POST /api/v1/passes/{id}/rotate-link`

Replaces the download and public links. The old links stop working.

Scopes: `passes:write`. SDK name: `pb.passes.rotateLink`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "downloadUrl": "https://wallet.example.com/p/0193a1b2-7c00-7000-8000-0000000000c1.pkpass",
  "publicUrl": "https://wallet.example.com/p/xK3v9QmT2Lw8"
}
```

## Mint a new scan code; the old code stops working {#rotateCode}

`POST /api/v1/passes/{id}/new-code`

Mints a new scan code. The old code stops working.

Scopes: `passes:write`. SDK name: `pb.passes.rotateCode`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "ok": true
}
```

## Email the pass to the holder {#sendEmail}

`POST /api/v1/passes/{id}/resend-email`

Emails the pass link to the holder, or to `to` when given. Send an `Idempotency-Key` header to retry safely.

Scopes: `passes:write`. Idempotent with an `Idempotency-Key` header. SDK name: `pb.passes.sendEmail`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `Idempotency-Key` | header | string · max 200 |  | 1 to 200 characters. A retry with the same key and body returns the first result. |
| `to` | body | string · max 254 |  |  |
| `attach` | body | boolean |  |  |

Returns `202`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/resend-email" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "ada@example.com",
  "attach": true
}'
```

Response example:

```json
{
  "ok": true
}
```

## Match photo file names to passes by External ID or serial {#matchPhotos}

`POST /api/v1/passes/photos/match`

Scopes: `passes:write`. SDK name: `pb.passes.matchPhotos`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `keys` | body | string · max 200[] | yes |  |
| `orgId` | body | string · max 64 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/photos/match" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "keys": [
    "Example"
  ]
}'
```

## Renew the term of a pass {#renew}

`POST /api/v1/passes/{id}/renew`

Scopes: `passes:write`. SDK name: `pb.passes.renew`.

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

Returns `200`, a `PassDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Void, email or remove up to 100 passes of one org {#bulkApply}

`POST /api/v1/passes/bulk`

Scopes: `passes:write`. Idempotent with an `Idempotency-Key` header. SDK name: `pb.passes.bulkApply`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string · max 200 |  | 1 to 200 characters. A retry with the same key and body returns the first result. |
| `action` | body | "void" \| "send_email" \| "remove" | yes |  |
| `ids` | body | string · max 64[] | yes |  |
| `message` | body | string · max 200 |  |  |
| `orgId` | body | string · max 64 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/bulk" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "void",
  "ids": [
    "0193a1b2-7c00-7000-8000-0000000000e1"
  ]
}'
```

## Rebuild passes of a template in your org; a key needs passes:write {#bulkReissue}

`POST /api/v1/passes/bulk-reissue`

Scopes: `passes:write`. SDK name: `pb.passes.bulkReissue`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `templateId` | body | string · max 64 |  |  |
| `version` | body | string |  |  |
| `orgId` | body | string · max 64 |  |  |
| `cause` | body | "template_upgrade" \| "resign" |  |  |
| `identityId` | body | string · max 64 |  |  |

Returns `202`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/bulk-reissue" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "cause": "template_upgrade"
}'
```

## Turn channels on, off or back to the template for up to 100 passes {#bulkUpdateChannels}

`POST /api/v1/passes/bulk/channels`

Scopes: `passes:write`. SDK name: `pb.passes.bulkUpdateChannels`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `action` | body | "on" \| "off" \| "reset" | yes |  |
| `channels` | body | "mobile" \| "apple" \| "google" \| "samsung" \| "paper" \| "nfc"[] | yes |  |
| `ids` | body | string · max 64[] | yes |  |
| `notify` | body | boolean |  |  |
| `replaceCodes` | body | boolean |  |  |
| `dryRun` | body | boolean |  |  |
| `orgId` | body | string · max 64 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/bulk/channels" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "on",
  "channels": [
    "mobile"
  ],
  "ids": [
    "0193a1b2-7c00-7000-8000-0000000000e1"
  ]
}'
```

## Remove from Wallet: publish a voided, expired final version {#remove}

`POST /api/v1/passes/{id}/remove`

Removes the pass from Wallet by publishing a voided, expired final version. The record stays; undo with restore. `message` shows on the lock screen.

Scopes: `passes:write`. SDK name: `pb.passes.remove`.

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

Returns `200`, a `PassSummary`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000c1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "templateVersion": "3",
  "identityId": "0193a1b2-7c00-7000-8000-0000000000d1",
  "serial": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
  "title": "Ada Example",
  "subtitle": "Row 4, seat 12",
  "externalId": "booking_8841",
  "status": "voided",
  "mode": "test",
  "version": 2,
  "connectionId": null,
  "externalRef": null,
  "syncErrorCode": null,
  "holderEmail": "ada@example.com",
  "holderState": "waiting",
  "ownerUserId": null,
  "deviceCount": 0,
  "removedAt": 1764000000000,
  "modifiedAt": 1764000000000,
  "createdAt": 1764000000000
}
```

## Undo a removal {#restore}

`POST /api/v1/passes/{id}/restore`

Undoes a removal and publishes the pass again.

Scopes: `passes:write`. SDK name: `pb.passes.restore`.

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

Returns `200`, a `PassSummary`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000c1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "templateVersion": "3",
  "identityId": "0193a1b2-7c00-7000-8000-0000000000d1",
  "serial": "3f9c2d6a-5b1e-4c7a-9d20-8a41e6b7c0f2",
  "title": "Ada Example",
  "subtitle": "Row 4, seat 12",
  "externalId": "booking_8841",
  "status": "active",
  "mode": "test",
  "version": 3,
  "connectionId": null,
  "externalRef": null,
  "syncErrorCode": null,
  "holderEmail": "ada@example.com",
  "holderState": "waiting",
  "ownerUserId": null,
  "deviceCount": 0,
  "removedAt": null,
  "modifiedAt": 1764000000000,
  "createdAt": 1764000000000
}
```

## Get local provider instance status for a pass {#retrieveProviderStatus}

`GET /api/v1/wallet-providers/passes/{id}`

Scopes: `passes:read`. SDK name: `pb.passes.retrieveProviderStatus`.

| 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. |
| `GOOGLE_CALLBACK_INVALID` |  | Send callbacks only from Google; check the callback URL set in Google Wallet. |
| `GOOGLE_CALLBACK_UNAVAILABLE` |  | Retry with backoff; Google resends failed callbacks. |
| `GOOGLE_ISSUER_NOT_OWNED` |  | Share an issuer your Google account owns, then send the request again. |
| `GOOGLE_ISSUER_NOT_SHARED` |  | Share the issuer in the Google Pay and Wallet console, then send the request again. |
| `GOOGLE_UNAVAILABLE` |  | Send the request again in a minute. |
| `IAM_BAD_ACCOUNT` |  | Send the request again; contact support if it repeats. |
| `IAM_BAD_KEY` |  | Send the request again; contact support if it repeats. |
| `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. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `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. |
| `SAMSUNG_FIELDS_INVALID` |  | Send callbacks only from Samsung Wallet; check the callback setup. |
| `SAMSUNG_UNAUTHENTICATED` |  | Check the Samsung Wallet partner credentials stored for the organization. |
| `SAMSUNG_UNAVAILABLE` |  | Retry with backoff. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_SELF_APPROVAL` |  | Have a different member approve the candidate. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WALLET_ACCOUNT_CONFLICT` |  | Fetch it again and send your change. |
| `WALLET_ACCOUNT_INSTANCES_ACTIVE` |  | Retire all provider instances, then revoke the account. |
| `WALLET_ACCOUNT_MOVED` |  | List accounts with GET /api/v1/wallet-providers/accounts and use the current one. |
| `WALLET_ART_MISMATCH` |  | Replace the image with one at the size shown in issues. |
| `WALLET_CREDENTIALS_INVALID` |  | Fix the credentials named in issues and send them again. |
| `WALLET_CREDENTIALS_UNAVAILABLE` |  | Retry with backoff. |
| `WALLET_ENROLMENT_HELD` |  | Ask the platform owner to release the hold. |
| `WALLET_ENROLMENT_PREREQUISITE` |  | Finish the steps listed in the response, then retry. |
| `WALLET_IDENTITY_IMMUTABLE` |  | Create a new account for the new identity. |
| `WALLET_IMAGE_NOT_FOUND` |  | Rebuild the wallet projection and use the new image URL. |
| `WALLET_ISSUER_CLAIMED` |  | Use a different issuer. |
| `WALLET_ISSUER_EXISTS` |  | Attach it as a shared issuer instead. |
| `WALLET_ISSUER_NOT_WAITING` |  | Check the issuer status before completing it. |
| `WALLET_KEY_HELD` |  | Move the credential to the new key, then send the request again. |
| `WALLET_MODE_MISMATCH` |  | Use a key of the same mode as the request. |
| `WALLET_OFFER_NOT_FOUND` |  | Request a new offer for the pass. |
| `WALLET_PLATFORM_CREDENTIAL_MISSING` |  | Ask the platform owner to add it, then send the request again. |
| `WALLET_PROJECTION_BLOCKED` |  | Fix the problems the response lists and build the projection again. |
| `WALLET_PROJECTION_CONFLICT` |  | Fetch the candidate again and send your request. |
| `WALLET_PROJECTION_NOT_FOUND` |  | Check the id and create a candidate if it expired. |
| `WALLET_PROJECTION_SCHEMA` |  | Create a new candidate from the current release. |
| `WALLET_PROJECTION_UNSUPPORTED` |  | Remove the unsupported features or release without this provider. |
| `WALLET_RUN_BUSY` |  | Send the request again in a minute. |
| `WALLET_VERIFICATION_CONFLICT` |  | Wait for it to finish, then verify again if needed. |

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

## Sync log and activity of a pass, newest first {#activity-list}

`GET /api/v1/passes/{id}/events`

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `cursor` | query | string · max 512 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |
| `kind` | query | string · max 600 |  |  |
| `group` | query | "delivery" \| "devices" \| "changes" \| "scans" |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Per-pass image overrides {#assets-list}

`GET /api/v1/passes/{id}/assets`

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

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Upload an image override {#assets-upload}

`PUT /api/v1/passes/{id}/assets/{name}`

Scopes: `passes:write`. SDK name: `pb.passes.assets.upload`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `name` | path | string · ^[a-zA-Z]+(?:@[23]x)?\.png$ | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X PUT "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/assets/icon.png" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @image.png
```

## Remove an image override {#assets-delete}

`DELETE /api/v1/passes/{id}/assets/{name}`

Scopes: `passes:write`. SDK name: `pb.passes.assets.delete`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `name` | path | string · ^[a-zA-Z]+(?:@[23]x)?\.png$ | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X DELETE "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/assets/icon.png" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## A pass's channels: effective state, source and overrides {#channels-retrieve}

`GET /api/v1/passes/{id}/channels`

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

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Override channels for one pass; null returns a channel to its template {#channels-update}

`PUT /api/v1/passes/{id}/channels`

Scopes: `passes:write`. SDK name: `pb.passes.channels.update`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `channels` | body | object | yes |  |
| · `mobile` | body | "on" \| "off" \| null |  |  |
| · `apple` | body | "on" \| "off" \| null |  |  |
| · `google` | body | "on" \| "off" \| null |  |  |
| · `samsung` | body | "on" \| "off" \| null |  |  |
| · `paper` | body | "on" \| "off" \| null |  |  |
| · `nfc` | body | "on" \| "off" \| null |  |  |
| `notify` | body | boolean |  |  |
| `replaceCodes` | body | boolean |  |  |
| `orgId` | body | string · max 64 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X PUT "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/channels" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channels": {
    "apple": "on",
    "google": "off"
  },
  "notify": false
}'
```

## Pass check-in rules {#checkInRules-retrieve}

`GET /api/v1/passes/{id}/check-in`

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

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Set pass check-in rules {#checkInRules-update}

`PUT /api/v1/passes/{id}/check-in`

Scopes: `passes:write`. SDK name: `pb.passes.checkInRules.update`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `rules` | body | object | yes |  |
| · `mode` | body | "single" \| "daily" \| "unlimited" \| "in_out" |  |  |
| · `eventId` | body | string \| null · max 64 |  |  |
| · `validFrom` | body | integer \| null · ≥ 0 |  |  |
| · `validUntil` | body | integer \| null · ≥ 0 |  |  |
| · `durationMinutes` | body | integer \| null · ≥ 1 · ≤ 5256000 |  |  |
| · `durationFrom` | body | "first_scan" \| "issued" |  |  |
| · `days` | body | integer \| null · ≥ 1 · ≤ 366 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Bind a pass to a connection ref, or unbind it {#connection-update}

`PUT /api/v1/passes/{id}/connection`

Scopes: `passes:write`. SDK name: `pb.passes.connection.update`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `connectionId` | body | string \| null · max 64 | yes |  |
| `externalRef` | body | string \| null · max 500 | yes |  |
| `resetFieldSources` | body | boolean |  |  |

Returns `200`, a `PassDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X PUT "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/connection" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connectionId": "0193a1b2-7c00-7000-8000-0000000000e1",
  "externalRef": "Example"
}'
```

## Devices of a pass with their sync status {#devices-list}

`GET /api/v1/passes/{id}/devices`

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

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Member photo settings {#memberPhoto-retrieve}

`GET /api/v1/passes/{id}/member-photo`

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

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Upload a member photo {#memberPhoto-upload}

`PUT /api/v1/passes/{id}/member-photo`

Scopes: `passes:write`. SDK name: `pb.passes.memberPhoto.upload`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `png` | body | string · max 1400000 | yes |  |
| `includeInPass` | body | boolean |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X PUT "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/member-photo" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "png": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAGUlEQVR42mOQz3/9nxLMMGrAqAGjBgwXAwCBLngfV/beKAAAAABJRU5ErkJggg=="
}'
```

## Set Wallet photo inclusion {#memberPhoto-update}

`PATCH /api/v1/passes/{id}/member-photo`

Scopes: `passes:write`. SDK name: `pb.passes.memberPhoto.update`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X PATCH "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/member-photo" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "includeInPass": false
}'
```

## Remove a member photo {#memberPhoto-delete}

`DELETE /api/v1/passes/{id}/member-photo`

Scopes: `passes:write`. SDK name: `pb.passes.memberPhoto.delete`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X DELETE "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/member-photo" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Private member photo {#memberPhoto-download}

`GET /api/v1/passes/{id}/member-photo/image`

Scopes: `passes:read`. SDK name: `pb.passes.memberPhoto.download`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## A pass's prints, newest first; codes are never listed {#prints-list}

`GET /api/v1/passes/{id}/prints`

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

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Print a ticket; an earlier print of the pass is voided {#prints-create}

`POST /api/v1/passes/{id}/prints`

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

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Void a printed ticket {#prints-void}

`POST /api/v1/passes/{id}/prints/{printId}/void`

Scopes: `passes:write`. SDK name: `pb.passes.prints.void`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## The print page of the active print, for staff {#prints-retrievePage}

`GET /api/v1/passes/{id}/print`

Scopes: `passes:read`. SDK name: `pb.passes.prints.retrievePage`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## The PDF of the active print, for staff {#prints-downloadPdf}

`GET /api/v1/passes/{id}/print/pdf`

Scopes: `passes:read`. SDK name: `pb.passes.prints.downloadPdf`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## A template image of the print page, for staff {#prints-downloadAsset}

`GET /api/v1/passes/{id}/print/assets/{name}`

Scopes: `passes:read`. SDK name: `pb.passes.prints.downloadAsset`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X GET "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/print/assets/icon.png" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Add stamps or redeem the reward on a stamp card {#stamps-apply}

`POST /api/v1/passes/{id}/stamps`

Scopes: `passes:write`. SDK name: `pb.passes.stamps.apply`.

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

Returns `200`, a `PassDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## A retained version, for rendering {#versions-retrieve}

`GET /api/v1/passes/{id}/versions/{version}`

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `version` | path | integer \| null |  |  |

Returns `200`, a `PassDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Diff two versions {#versions-diff}

`GET /api/v1/passes/{id}/diff`

Scopes: `passes:read`. SDK name: `pb.passes.versions.diff`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `from` | query | integer \| null |  |  |
| `to` | query | integer \| null |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ASSET_DIMENSIONS` |  | Resize the image to the size named in issues and upload it again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `ASSET_NOT_PNG` |  | Re-export the image as a standard RGB or RGBA PNG and upload it again. |
| `ASSET_SIZE` |  | Compress the image below 1 MB and upload it again. |
| `ASSET_SLOT` |  | Use a slot name from the pass type's image slots in the request path. |
| `BULK_RUN_ACTIVE` |  | Wait for the running job to finish, then start the new one. |
| `BUNDLE_TOO_LARGE` |  | Split the passes across smaller bundles. |
| `CONNECTION_ORG` |  | Use a connection id from your own organization's GET /api/v1/connections. |
| `CONNECTION_TRANSFER_PENDING` |  | Wait for the transfer to finish, then send the request again. |
| `CREATE_STALE` |  | Look the pass up by externalId with GET /api/v1/passes and update it instead of creating it again. |
| `CREDENTIAL_REF_KEYSET_CONFIG_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `DEVICE_TOKEN_UNAVAILABLE` |  | Retry the request; if it persists, send the requestId to support. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `EXTERNAL_ID_TAKEN` |  | Send a new externalId, or PATCH the existing pass. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IDEMPOTENCY_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `IDEMPOTENCY_KEY_INVALID` |  | Send a unique string of 1 to 200 characters, such as a UUID. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IF_MATCH_INVALID` |  | Send the version from the last GET, for example If-Match: 3. |
| `IMPORT_BUSY` |  | Wait for it to finish with GET /api/v1/pass-imports/{id}, then retry. |
| `IMPORT_COLUMN_MISSING` |  | Add the column to the file, or change the mapping, then check again. |
| `IMPORT_EXPIRED` |  | Upload the file again with POST /api/v1/pass-imports. |
| `IMPORT_FILE_GONE` |  | Upload it again. |
| `IMPORT_HAS_ERRORS` |  | Fix the rows listed in GET /api/v1/pass-imports/{id}/errors.csv, or skip them, then commit again. |
| `IMPORT_HEADER_TOO_LONG` |  | Shorten the header and upload the file again. |
| `IMPORT_ID_TAKEN` |  | Check the import again with POST /api/v1/pass-imports/{id}/check, then commit. |
| `IMPORT_NOT_FOUND` |  | Check the id with GET /api/v1/pass-imports. |
| `IMPORT_PASS_CHANGED` |  | Remove the pass on its own with POST /api/v1/passes/{id}/remove. |
| `IMPORT_PLAN_INVALID` |  | Fix the mapping entries named in issues and check again. |
| `IMPORT_ROW_UNRESERVED` |  | Retry the commit; if it persists, send the requestId to support. |
| `IMPORT_STATE` |  | Check its state with GET /api/v1/pass-imports/{id} and call the action that state allows. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `JOIN_NOT_READY` |  | Publish the template, then enable the link with PUT /api/v1/join-links/{templateId}. |
| `MATCH_NEEDS_TEMPLATE` |  | Send orgId and templateId with the input filter. |
| `MEMBER_PHOTO_CHANGED` |  | Fetch the pass with GET /api/v1/passes/{id} and save the photo again. |
| `MEMBER_PHOTO_DIMENSIONS` |  | Crop the photo to a 270 by 270 pixel square and upload it again. |
| `MEMBER_PHOTO_ENCODING` |  | Send the photo as a PNG or JPEG file. |
| `MEMBER_PHOTO_NOT_FOUND` |  | Add one with PUT /api/v1/passes/{id}/member-photo. |
| `MEMBER_PHOTO_STYLE` |  | Use a template of that style, or remove the strip image. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_MISMATCH` |  | Use objects and a key of the same mode. |
| `NEW_CODE_UNSUPPORTED` |  | Reissue the pass with POST /api/v1/passes/bulk-reissue instead of requesting a new code. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_ACCESS_CHANGED` |  | Check access with GET /api/v1/api-keys/me, then send the request again. |
| `ORG_FORBIDDEN` |  | Use a key scoped to this organization, or a platform key for platform-wide lists. |
| `ORG_MIXED` |  | Send ids from one organization per request. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_CONNECTION_MISMATCH` |  | Link it with PUT /api/v1/passes/{id}/connection, then send the request again. |
| `PASS_FILE_MISSING` |  | Rebuild it with POST /api/v1/passes/{id}/refresh. |
| `PASS_INPUT_INVALID` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `PASS_INVALID` |  | Fix the problems named in issues in the template or inputs. |
| `PASS_NOT_ACTIVE` |  | Restore or unvoid the pass first, or use an active one. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PASS_REF_TAKEN` |  | Use a different ref, or update the existing pass. |
| `PASS_REISSUE_REQUIRED` |  | Reissue it with POST /api/v1/passes/bulk-reissue. |
| `PASS_REMOVED` |  | Restore it with POST /api/v1/passes/{id}/restore, then send the request again. |
| `PASS_TRANSFER_NOT_FOUND` |  | Check the transfer id. |
| `PASS_TRANSFER_PENDING` |  | Try again shortly. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `SCAN_EVENT_NOT_FOUND` |  | Check the event id with GET /api/v1/scan/events. |
| `SCAN_WINDOW_INVALID` |  | Set an end after the start, or fix the template's dates. |
| `SERIAL_TAKEN` |  | Send a different serial, or leave it out to have one generated. |
| `SESSION_REQUIRED` |  | Do it in the console, or sign in as the account that started it. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_CARD_FULL` |  | Redeem the reward, then add stamps. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_NO_REWARD` |  | Add stamps until the card is full, then redeem. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TERM_MANAGED` |  | Change the term in the connected system. |
| `TERM_NONE` |  | Renew only passes whose template defines a term. |
| `TERM_NOT_STARTED` |  | Renew after the term starts. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/passes/{id}. |
| `VERSION_PURGED` |  | Request a newer version. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X GET "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/diff?from=1&to=1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```
