# Templates

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

## List templates {#list}

`GET /api/v1/templates`

Lists the organization's templates, newest first. Use `blueprint=1` for starters.

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `includeArchived` | query | "0" \| "1" \| "true" \| "false" |  |  |
| `origin` | query | "baked" \| "uploaded" |  |  |
| `blueprint` | query | "0" \| "1" \| "true" \| "false" |  |  |
| `status` | query | "active" \| "archived" |  |  |
| `q` | query | string · max 100 |  |  |
| `cursor` | query | string |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |

Returns `200`, a `TemplatePage`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "items": [
    {
      "id": "0193a1b2-7c00-7000-8000-0000000000b1",
      "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
      "orgName": "Example Events",
      "slug": "event-ticket",
      "name": "Event ticket",
      "description": "Admission ticket with a seat and a QR code.",
      "origin": "uploaded",
      "status": "active",
      "activeVersion": "3",
      "styles": [
        "eventTicket"
      ],
      "passCount": 128,
      "createdAt": 1764000000000,
      "updatedAt": 1764086400000
    }
  ],
  "nextCursor": null
}
```

## Sample previews for several templates {#listPreviews}

`GET /api/v1/templates/previews`

Scopes: `templates:read`. SDK name: `pb.templates.listPreviews`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ids` | query | string | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

## List release-backed templates available to an organization {#listEligible}

`GET /api/v1/templates/eligible`

Scopes: `templates:read`. SDK name: `pb.templates.listEligible`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mode` | query | "live" \| "test" | yes |  |
| `provider` | query | "apple" \| "google" \| "samsung" | yes |  |
| `purpose` | query | "issue" \| "scan" |  |  |
| `cursor` | query | string · max 64 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X GET "https://passbook.mobile/api/v1/templates/eligible?mode=test&provider=apple" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Get a template {#retrieve}

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

One template with its versions and a sample input. `sample` is a valid `input` for creating a pass.

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

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

Returns `200`, a `TemplateDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000b1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "orgName": "Example Events",
  "slug": "event-ticket",
  "name": "Event ticket",
  "description": "Admission ticket with a seat and a QR code.",
  "origin": "uploaded",
  "status": "active",
  "activeVersion": "3",
  "styles": [
    "eventTicket"
  ],
  "passCount": 128,
  "createdAt": 1764000000000,
  "updatedAt": 1764086400000,
  "sample": {
    "name": "Ada Example",
    "seat": "Row 4, seat 12"
  },
  "versions": [
    {
      "version": "3",
      "createdAt": 1764000000000,
      "createdBy": null,
      "assets": [],
      "report": {
        "ok": true,
        "issues": []
      },
      "active": true,
      "displayOnly": false,
      "passCount": 128
    }
  ]
}
```

## Render pass.json for input {#preview}

`POST /api/v1/templates/{id}/preview`

Scopes: `templates:read`. SDK name: `pb.templates.preview`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `version` | body | string |  |  |
| `orgId` | body | string · max 64 |  |  |
| `input` | body | object |  |  |
| `locale` | body | string · max 35 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Get the JSON Schema of a template's pass input {#retrieveInputSchema}

`GET /api/v1/templates/{id}/input-schema`

Returns the JSON Schema that `input` must satisfy in `POST /passes` for this template's active version. Field labels, groups and order are in the `x-label`, `x-group` and `x-order` keywords. Use it to build a form or generate types.

Scopes: `templates:read`. SDK name: `pb.templates.retrieveInputSchema`.

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

Returns `200`, a `TemplateInputSchema`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

Response example:

```json
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "x-label": "Name"
    },
    "seat": {
      "type": "string",
      "x-label": "Seat"
    }
  },
  "additionalProperties": false
}
```

## What changing the stamp goal does to live passes {#retrieveStampsImpact}

`GET /api/v1/templates/{id}/stamps-impact`

Scopes: `templates:read`. SDK name: `pb.templates.retrieveStampsImpact`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `goal` | query | integer · ≥ 3 · ≤ 20 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X GET "https://passbook.mobile/api/v1/templates/0193a1b2-7c00-7000-8000-0000000000b1/stamps-impact?goal=3" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Set up scanning for a template: its events and a session, once {#setUpScanning}

`POST /api/v1/templates/{id}/scan-setup`

Scopes: `scanning:write`. SDK name: `pb.templates.setUpScanning`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

## The active version or unpublished draft as an uploadable zip {#downloadPackage}

`GET /api/v1/templates/{id}/package`

Scopes: `templates:read`. SDK name: `pb.templates.downloadPackage`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

## List template release candidates {#candidates-list}

`GET /api/v1/templates/{id}/candidates`

Scopes: `templates:read`. SDK name: `pb.templates.candidates.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `mode` | query | "live" \| "test" | yes |  |
| `provider` | query | "apple" \| "google" \| "samsung" | yes |  |
| `cursor` | query | string · max 512 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X GET "https://passbook.mobile/api/v1/templates/0193a1b2-7c00-7000-8000-0000000000b1/candidates?mode=test&provider=apple" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Create a template release candidate {#candidates-create}

`POST /api/v1/templates/{id}/candidates`

Scopes: `templates:write`. SDK name: `pb.templates.candidates.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `orgId` | body | string · max 64 | yes |  |
| `mode` | body | "live" \| "test" | yes |  |
| `provider` | body | "apple" \| "google" \| "samsung" | yes |  |
| `version` | body | string | yes |  |
| `sourceReleaseId` | body | string · max 64 |  |  |
| `projection` | body | any |  |  |

Returns `201`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X POST "https://passbook.mobile/api/v1/templates/0193a1b2-7c00-7000-8000-0000000000b1/candidates" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "mode": "test",
  "provider": "apple",
  "version": "Example"
}'
```

## Approve a template release candidate {#candidates-approve}

`POST /api/v1/templates/{id}/candidates/{candidateId}/approve`

Scopes: `templates:review`. SDK name: `pb.templates.candidates.approve`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `candidateId` | path | string · max 64 | yes |  |
| `orgId` | body | string · max 64 | yes |  |
| `mode` | body | "live" \| "test" | yes |  |
| `provider` | body | "apple" \| "google" \| "samsung" | yes |  |
| `candidateHash` | body | string | yes |  |
| `alone` | body | boolean |  |  |

Returns `201`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X POST "https://passbook.mobile/api/v1/templates/0193a1b2-7c00-7000-8000-0000000000b1/candidates/0193a1b2-7c00-7000-8000-0000000000e1/approve" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "mode": "test",
  "provider": "apple",
  "candidateHash": "Example"
}'
```

## A template's channel policy and what it allows now, in this mode {#channels-retrieve}

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

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

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

## The latest runs that applied saved channel changes to passes, in this mode {#channels-listRuns}

`GET /api/v1/templates/{id}/channels/runs`

Scopes: `templates:read`. SDK name: `pb.templates.channels.listRuns`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

## List template releases {#releases-list}

`GET /api/v1/templates/{id}/releases`

Scopes: `templates:read`. SDK name: `pb.templates.releases.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `mode` | query | "live" \| "test" | yes |  |
| `provider` | query | "apple" \| "google" \| "samsung" | yes |  |
| `cursor` | query | string · max 512 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X GET "https://passbook.mobile/api/v1/templates/0193a1b2-7c00-7000-8000-0000000000b1/releases?mode=test&provider=apple" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Publish an approved template release {#releases-create}

`POST /api/v1/templates/{id}/releases`

Scopes: `templates:publish`. SDK name: `pb.templates.releases.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `orgId` | body | string · max 64 | yes |  |
| `mode` | body | "live" \| "test" | yes |  |
| `provider` | body | "apple" \| "google" \| "samsung" | yes |  |
| `candidateId` | body | string · max 64 | yes |  |
| `approvalId` | body | string · max 64 | yes |  |
| `candidateHash` | body | string | yes |  |
| `expectedGeneration` | body | integer · ≥ 0 | yes |  |

Returns `201`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X POST "https://passbook.mobile/api/v1/templates/0193a1b2-7c00-7000-8000-0000000000b1/releases" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "mode": "test",
  "provider": "apple",
  "candidateId": "0193a1b2-7c00-7000-8000-0000000000e1",
  "approvalId": "0193a1b2-7c00-7000-8000-0000000000e1",
  "candidateHash": "Example",
  "expectedGeneration": 0
}'
```

## What publishing or rolling back to a version changes, and for how many passes {#releases-retrieveImpact}

`GET /api/v1/templates/{id}/releases/impact`

Scopes: `templates:read`. SDK name: `pb.templates.releases.retrieveImpact`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `mode` | query | "live" \| "test" | yes |  |
| `provider` | query | "apple" \| "google" \| "samsung" | yes |  |
| `version` | query | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

```sh
curl -X GET "https://passbook.mobile/api/v1/templates/0193a1b2-7c00-7000-8000-0000000000b1/releases/impact?mode=test&provider=apple&version=Example" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Template version with its validation report {#versions-retrieve}

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

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

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Template asset bytes {#versions-downloadAsset}

`GET /api/v1/templates/{id}/versions/{version}/assets/{name}`

Scopes: `templates:read`. SDK name: `pb.templates.versions.downloadAsset`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `version` | path | string · max 64 | yes |  |
| `name` | path | string · max 200 | yes |  |
| `stamps` | query | integer \| null · ≥ 0 · ≤ 20 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ARCHIVE_TOO_LARGE` |  | Remove unused files and upload an archive under 15 MB. |
| `ASSETS_INVALID` |  | Fix the files named in issues and upload the archive again. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_CONFLICT` |  | Send the request again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `INVALID_INPUT` |  | Fix the inputs named in issues; GET /api/v1/templates/{id}/input-schema lists them. |
| `KEY_CREATOR_GONE` |  | Create a new key with POST /api/v1/api-keys. |
| `KEY_CREATOR_NOT_MEMBER` |  | Create a new key from a current member with POST /api/v1/api-keys. |
| `KEY_TEST_ONLY` |  | Use a pb_test_ key. |
| `MANIFEST_INVALID` |  | Fix the manifest fields listed in issues and upload it again. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_ZIP` |  | Upload the template as a .zip file. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_FILE` |  | Send the archive as multipart form data in the file field. |
| `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. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `STAMPS_ABOVE_MAX` |  | Raise the template's stamp maximum, or redeem stamps first. |
| `STAMPS_NONE` |  | Use a template with stamps. |
| `STAMPS_QUERY` |  | Retry the request. |
| `STAMPS_REDRAW` |  | Make the change in the template designer and publish a new version. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_ASSET_CONFLICT` |  | Upload the template version again. |
| `TEMPLATE_BAKED` |  | Clone it with POST /api/v1/templates/{id}/clone and change the clone. |
| `TEMPLATE_BLUEPRINT_INACTIVE` |  | Pick another. |
| `TEMPLATE_CANDIDATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/candidates. |
| `TEMPLATE_CONFLICT` |  | Fetch it with GET /api/v1/templates/{id} and send your change again. |
| `TEMPLATE_CONTENT_CHANGED` |  | Send the request again to use the current release. |
| `TEMPLATE_EXISTS` |  | Pick another name. |
| `TEMPLATE_IN_USE` |  | Remove it from them first. |
| `TEMPLATE_IS_BLUEPRINT` |  | Use this blueprint to make one first. |
| `TEMPLATE_MODE_MISMATCH` |  | Use a key of the template's mode. |
| `TEMPLATE_NOT_BLUEPRINT` |  | Duplicate a template instead. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_SHAREABLE` |  | Share an upload that no organization has taken. |
| `TEMPLATE_NOT_TESTED` |  | Release it in Test first. |
| `TEMPLATE_ORG_REQUIRED` |  | Assign the template to an organization, then retry. |
| `TEMPLATE_PROVIDER_UNSUPPORTED` |  | Configure the provider for the organization, or release for another provider. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_NOT_FOUND` |  | Check the id with GET /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `TEMPLATE_SLUG_CONFLICT` |  | Send the request again, or choose a different name. |
| `TEMPLATE_USED_BY_OTHER_ORG` |  | Reissue or delete them first. |
| `TEMPLATE_VERSION_CONFLICT` |  | Fetch the template and publish again. |
| `TEMPLATE_VERSION_CONTENT_CONFLICT` |  | Run the sync again. |
| `TEMPLATE_VERSION_NOT_FOUND` |  | Check the version with GET /api/v1/templates/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UPLOAD_NOT_FOUND` |  | Check the id with GET /api/v1/templates/uploads. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `VERSION_INVALID` |  | Use a version number from GET /api/v1/templates/{id}. |
| `WORKFLOW_START` |  | Send the request again. |

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

## Console only

Signed-in console sessions only; an API key cannot call these.

- `DELETE /api/v1/templates/{id}`: Delete or archive an uploaded template (baked: 403 TEMPLATE_BAKED)
- `POST /api/v1/templates/{id}/clone`: Clone into an inactive uploaded draft
- `PUT /api/v1/templates/{id}/manifest`: Save the manifest as an inactive version
- `PUT /api/v1/templates/{id}/channels`: Set a template's channels to on, off or never; dryRun shows the effect
- `POST /api/v1/templates/{id}/versions`: Save an inactive version from JSON; dryRun only validates and builds
- `POST /api/v1/templates/{id}/archive`: Archive an uploaded template
- `POST /api/v1/templates/{id}/restore`: Restore an archived template that never had a release
- `POST /api/v1/templates/{id}/candidates/promote`: Promote a version released in Test to a Live candidate
- `POST /api/v1/templates/{id}/releases/rollback`: Roll back to a prior template release
