# NFC

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

## Tag types of an organization {#tagTypes-list}

`GET /api/v1/nfc/tag-types`

Scopes: `scans:read`. SDK name: `pb.nfc.tagTypes.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string · max 64 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ENROLLMENT_NOT_FOUND` |  | Check the enrollment id and start a new request if it expired. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_EMPTY` |  | Upload a CSV with a header line and one tag per row. |
| `IMPORT_HEADER` |  | Start the file with a header line naming the uid and key columns. |
| `IMPORT_TOO_MANY` |  | Split the file and import it in parts. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `KEYSET_CHANGED` |  | Fetch the keyset and send the change again. |
| `KEYSET_KEY_INVALID` |  | Send each key as 32 hexadecimal characters. |
| `KEYSET_KEY_NOT_FOUND` |  | Check the key version against the keyset's list and send it again. |
| `KEYSET_KEY_REUSED` |  | Send new keys this organization has never used. |
| `KEYSET_KEY_WEAK` |  | Send two different, randomly generated keys. |
| `KEYSET_NOT_FOUND` |  | Check the keyset id and the key's mode. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `SCANNER_NOT_FOUND` |  | Check the scanner id and the key's mode. |
| `SCANNER_NO_TAGS` |  | Pick a scanner with tag reading on. |
| `SCANNER_OFFLINE` |  | Open the scanner app, then send the request again. |
| `SCANNER_REQUESTS_OFF` |  | Turn on tag requests for the scanner, or pick another. |
| `TAGS_OFF` |  | Turn on tags in the organization's settings. |
| `TAG_ALREADY_ASSIGNED` |  | Fetch the tag and check its holder before reassigning. |
| `TAG_ASSURANCE_LOW` |  | Assign a secure tag type to the pass. |
| `TAG_HOLDER_CHANGED` |  | Fetch the tag and send the request again. |
| `TAG_ID_INVALID` |  | Check the ID against the reader or the supplier's list. |
| `TAG_KEY_UNREADABLE` |  | Retry once; if it persists, send the requestId to support. |
| `TAG_NOT_ASSIGNED` |  | Assign the tag before this action. |
| `TAG_NOT_FOUND` |  | Check the tag id. |
| `TAG_NO_ACCOUNT` |  | Assign the tag to the pass instead. |
| `TAG_POOL_UNSUPPORTED` |  | Assign the tag to a pass or person instead. |
| `TAG_REQUEST_BUSY` |  | Cancel the open request or wait for it to finish. |
| `TAG_SECURE_REQUIRED` |  | Use a Secure (SUN) tag, or lower the session's tag level. |
| `TAG_SYSTEM_DISABLED` |  | Pick a tag system that is available, or contact the platform owner. |
| `TAG_TYPED_OFF` |  | Tap the tag on a scanner, or allow typed IDs on the tag type. |
| `TAG_TYPE_ARCHIVED` |  | Restore the tag type or use another. |
| `TAG_TYPE_CHANGED` |  | Fetch the tag type and send your change again. |
| `TAG_TYPE_CHOOSE` |  | Send `typeId`, or set a default tag type for the organization. |
| `TAG_TYPE_LIMIT` |  | Remove the pass's current tag of this type first, or use another type. |
| `TAG_TYPE_MISMATCH` |  | Choose a tag type that lists this pass's template. |
| `TAG_TYPE_NAME_TAKEN` |  | Choose a different name. |
| `TAG_TYPE_NOT_FOUND` |  | Check the tag type id. |
| `TAG_TYPE_SCOPE` |  | Choose a tag type with the scope you need. |
| `TAG_TYPE_SET` |  | Leave `typeId` out, or change the tag's type in the console first. |
| `TAG_TYPE_SYSTEM` |  | Choose a tag type for this tag's system. |
| `TAG_UNDO_EXPIRED` |  | Add the tag again. |
| `TAG_USE_MISMATCH` |  | Choose a tag type whose use the template accepts. |
| `TEMPLATE_IN_TAG_TYPE` |  | Remove it from the type first. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `VALIDATION` |  | Fix each field in issues and resend. |

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

## Create a tag type {#tagTypes-create}

`POST /api/v1/nfc/tag-types`

Scopes: `scanning:write`. SDK name: `pb.nfc.tagTypes.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | body | string · max 40 | yes |  |
| `use` | body | "member" \| "staff" \| "visitor" | yes |  |
| `scopes` | body | "pass" \| "user" \| "both" |  |  |
| `perPass` | body | integer · ≥ 1 · ≤ 4 |  |  |
| `bindingDays` | body | integer \| null · ≥ 1 · ≤ 3650 |  |  |
| `confirm` | body | "none" \| "staff" \| "manager" |  |  |
| `typed` | body | boolean |  |  |
| `templateIds` | body | string · max 64[] |  |  |
| `system` | body | "uid" \| "sun" |  |  |

Returns `201`.

| Code | Status | Fix |
| --- | --- | --- |
| `ENROLLMENT_NOT_FOUND` |  | Check the enrollment id and start a new request if it expired. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_EMPTY` |  | Upload a CSV with a header line and one tag per row. |
| `IMPORT_HEADER` |  | Start the file with a header line naming the uid and key columns. |
| `IMPORT_TOO_MANY` |  | Split the file and import it in parts. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `KEYSET_CHANGED` |  | Fetch the keyset and send the change again. |
| `KEYSET_KEY_INVALID` |  | Send each key as 32 hexadecimal characters. |
| `KEYSET_KEY_NOT_FOUND` |  | Check the key version against the keyset's list and send it again. |
| `KEYSET_KEY_REUSED` |  | Send new keys this organization has never used. |
| `KEYSET_KEY_WEAK` |  | Send two different, randomly generated keys. |
| `KEYSET_NOT_FOUND` |  | Check the keyset id and the key's mode. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `SCANNER_NOT_FOUND` |  | Check the scanner id and the key's mode. |
| `SCANNER_NO_TAGS` |  | Pick a scanner with tag reading on. |
| `SCANNER_OFFLINE` |  | Open the scanner app, then send the request again. |
| `SCANNER_REQUESTS_OFF` |  | Turn on tag requests for the scanner, or pick another. |
| `TAGS_OFF` |  | Turn on tags in the organization's settings. |
| `TAG_ALREADY_ASSIGNED` |  | Fetch the tag and check its holder before reassigning. |
| `TAG_ASSURANCE_LOW` |  | Assign a secure tag type to the pass. |
| `TAG_HOLDER_CHANGED` |  | Fetch the tag and send the request again. |
| `TAG_ID_INVALID` |  | Check the ID against the reader or the supplier's list. |
| `TAG_KEY_UNREADABLE` |  | Retry once; if it persists, send the requestId to support. |
| `TAG_NOT_ASSIGNED` |  | Assign the tag before this action. |
| `TAG_NOT_FOUND` |  | Check the tag id. |
| `TAG_NO_ACCOUNT` |  | Assign the tag to the pass instead. |
| `TAG_POOL_UNSUPPORTED` |  | Assign the tag to a pass or person instead. |
| `TAG_REQUEST_BUSY` |  | Cancel the open request or wait for it to finish. |
| `TAG_SECURE_REQUIRED` |  | Use a Secure (SUN) tag, or lower the session's tag level. |
| `TAG_SYSTEM_DISABLED` |  | Pick a tag system that is available, or contact the platform owner. |
| `TAG_TYPED_OFF` |  | Tap the tag on a scanner, or allow typed IDs on the tag type. |
| `TAG_TYPE_ARCHIVED` |  | Restore the tag type or use another. |
| `TAG_TYPE_CHANGED` |  | Fetch the tag type and send your change again. |
| `TAG_TYPE_CHOOSE` |  | Send `typeId`, or set a default tag type for the organization. |
| `TAG_TYPE_LIMIT` |  | Remove the pass's current tag of this type first, or use another type. |
| `TAG_TYPE_MISMATCH` |  | Choose a tag type that lists this pass's template. |
| `TAG_TYPE_NAME_TAKEN` |  | Choose a different name. |
| `TAG_TYPE_NOT_FOUND` |  | Check the tag type id. |
| `TAG_TYPE_SCOPE` |  | Choose a tag type with the scope you need. |
| `TAG_TYPE_SET` |  | Leave `typeId` out, or change the tag's type in the console first. |
| `TAG_TYPE_SYSTEM` |  | Choose a tag type for this tag's system. |
| `TAG_UNDO_EXPIRED` |  | Add the tag again. |
| `TAG_USE_MISMATCH` |  | Choose a tag type whose use the template accepts. |
| `TEMPLATE_IN_TAG_TYPE` |  | Remove it from the type first. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/nfc/tag-types" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example",
  "use": "member"
}'
```

## Change a tag type {#tagTypes-update}

`PATCH /api/v1/nfc/tag-types/{id}`

Scopes: `scanning:write`. SDK name: `pb.nfc.tagTypes.update`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `version` | body | integer · ≥ 1 | yes |  |
| `name` | body | string · max 40 |  |  |
| `use` | body | "member" \| "staff" \| "visitor" |  |  |
| `scopes` | body | "pass" \| "user" \| "both" |  |  |
| `perPass` | body | integer · ≥ 1 · ≤ 4 |  |  |
| `bindingDays` | body | integer \| null · ≥ 1 · ≤ 3650 |  |  |
| `confirm` | body | "none" \| "staff" \| "manager" |  |  |
| `typed` | body | boolean |  |  |
| `templateIds` | body | string · max 64[] |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ENROLLMENT_NOT_FOUND` |  | Check the enrollment id and start a new request if it expired. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_EMPTY` |  | Upload a CSV with a header line and one tag per row. |
| `IMPORT_HEADER` |  | Start the file with a header line naming the uid and key columns. |
| `IMPORT_TOO_MANY` |  | Split the file and import it in parts. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `KEYSET_CHANGED` |  | Fetch the keyset and send the change again. |
| `KEYSET_KEY_INVALID` |  | Send each key as 32 hexadecimal characters. |
| `KEYSET_KEY_NOT_FOUND` |  | Check the key version against the keyset's list and send it again. |
| `KEYSET_KEY_REUSED` |  | Send new keys this organization has never used. |
| `KEYSET_KEY_WEAK` |  | Send two different, randomly generated keys. |
| `KEYSET_NOT_FOUND` |  | Check the keyset id and the key's mode. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `SCANNER_NOT_FOUND` |  | Check the scanner id and the key's mode. |
| `SCANNER_NO_TAGS` |  | Pick a scanner with tag reading on. |
| `SCANNER_OFFLINE` |  | Open the scanner app, then send the request again. |
| `SCANNER_REQUESTS_OFF` |  | Turn on tag requests for the scanner, or pick another. |
| `TAGS_OFF` |  | Turn on tags in the organization's settings. |
| `TAG_ALREADY_ASSIGNED` |  | Fetch the tag and check its holder before reassigning. |
| `TAG_ASSURANCE_LOW` |  | Assign a secure tag type to the pass. |
| `TAG_HOLDER_CHANGED` |  | Fetch the tag and send the request again. |
| `TAG_ID_INVALID` |  | Check the ID against the reader or the supplier's list. |
| `TAG_KEY_UNREADABLE` |  | Retry once; if it persists, send the requestId to support. |
| `TAG_NOT_ASSIGNED` |  | Assign the tag before this action. |
| `TAG_NOT_FOUND` |  | Check the tag id. |
| `TAG_NO_ACCOUNT` |  | Assign the tag to the pass instead. |
| `TAG_POOL_UNSUPPORTED` |  | Assign the tag to a pass or person instead. |
| `TAG_REQUEST_BUSY` |  | Cancel the open request or wait for it to finish. |
| `TAG_SECURE_REQUIRED` |  | Use a Secure (SUN) tag, or lower the session's tag level. |
| `TAG_SYSTEM_DISABLED` |  | Pick a tag system that is available, or contact the platform owner. |
| `TAG_TYPED_OFF` |  | Tap the tag on a scanner, or allow typed IDs on the tag type. |
| `TAG_TYPE_ARCHIVED` |  | Restore the tag type or use another. |
| `TAG_TYPE_CHANGED` |  | Fetch the tag type and send your change again. |
| `TAG_TYPE_CHOOSE` |  | Send `typeId`, or set a default tag type for the organization. |
| `TAG_TYPE_LIMIT` |  | Remove the pass's current tag of this type first, or use another type. |
| `TAG_TYPE_MISMATCH` |  | Choose a tag type that lists this pass's template. |
| `TAG_TYPE_NAME_TAKEN` |  | Choose a different name. |
| `TAG_TYPE_NOT_FOUND` |  | Check the tag type id. |
| `TAG_TYPE_SCOPE` |  | Choose a tag type with the scope you need. |
| `TAG_TYPE_SET` |  | Leave `typeId` out, or change the tag's type in the console first. |
| `TAG_TYPE_SYSTEM` |  | Choose a tag type for this tag's system. |
| `TAG_UNDO_EXPIRED` |  | Add the tag again. |
| `TAG_USE_MISMATCH` |  | Choose a tag type whose use the template accepts. |
| `TEMPLATE_IN_TAG_TYPE` |  | Remove it from the type first. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X PATCH "https://passbook.mobile/api/v1/nfc/tag-types/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "version": 1
}'
```

## Archive a tag type; its tags keep working {#tagTypes-archive}

`POST /api/v1/nfc/tag-types/{id}/archive`

Scopes: `scanning:write`. SDK name: `pb.nfc.tagTypes.archive`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ENROLLMENT_NOT_FOUND` |  | Check the enrollment id and start a new request if it expired. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `IMPORT_EMPTY` |  | Upload a CSV with a header line and one tag per row. |
| `IMPORT_HEADER` |  | Start the file with a header line naming the uid and key columns. |
| `IMPORT_TOO_MANY` |  | Split the file and import it in parts. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `KEYSET_CHANGED` |  | Fetch the keyset and send the change again. |
| `KEYSET_KEY_INVALID` |  | Send each key as 32 hexadecimal characters. |
| `KEYSET_KEY_NOT_FOUND` |  | Check the key version against the keyset's list and send it again. |
| `KEYSET_KEY_REUSED` |  | Send new keys this organization has never used. |
| `KEYSET_KEY_WEAK` |  | Send two different, randomly generated keys. |
| `KEYSET_NOT_FOUND` |  | Check the keyset id and the key's mode. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `SCANNER_NOT_FOUND` |  | Check the scanner id and the key's mode. |
| `SCANNER_NO_TAGS` |  | Pick a scanner with tag reading on. |
| `SCANNER_OFFLINE` |  | Open the scanner app, then send the request again. |
| `SCANNER_REQUESTS_OFF` |  | Turn on tag requests for the scanner, or pick another. |
| `TAGS_OFF` |  | Turn on tags in the organization's settings. |
| `TAG_ALREADY_ASSIGNED` |  | Fetch the tag and check its holder before reassigning. |
| `TAG_ASSURANCE_LOW` |  | Assign a secure tag type to the pass. |
| `TAG_HOLDER_CHANGED` |  | Fetch the tag and send the request again. |
| `TAG_ID_INVALID` |  | Check the ID against the reader or the supplier's list. |
| `TAG_KEY_UNREADABLE` |  | Retry once; if it persists, send the requestId to support. |
| `TAG_NOT_ASSIGNED` |  | Assign the tag before this action. |
| `TAG_NOT_FOUND` |  | Check the tag id. |
| `TAG_NO_ACCOUNT` |  | Assign the tag to the pass instead. |
| `TAG_POOL_UNSUPPORTED` |  | Assign the tag to a pass or person instead. |
| `TAG_REQUEST_BUSY` |  | Cancel the open request or wait for it to finish. |
| `TAG_SECURE_REQUIRED` |  | Use a Secure (SUN) tag, or lower the session's tag level. |
| `TAG_SYSTEM_DISABLED` |  | Pick a tag system that is available, or contact the platform owner. |
| `TAG_TYPED_OFF` |  | Tap the tag on a scanner, or allow typed IDs on the tag type. |
| `TAG_TYPE_ARCHIVED` |  | Restore the tag type or use another. |
| `TAG_TYPE_CHANGED` |  | Fetch the tag type and send your change again. |
| `TAG_TYPE_CHOOSE` |  | Send `typeId`, or set a default tag type for the organization. |
| `TAG_TYPE_LIMIT` |  | Remove the pass's current tag of this type first, or use another type. |
| `TAG_TYPE_MISMATCH` |  | Choose a tag type that lists this pass's template. |
| `TAG_TYPE_NAME_TAKEN` |  | Choose a different name. |
| `TAG_TYPE_NOT_FOUND` |  | Check the tag type id. |
| `TAG_TYPE_SCOPE` |  | Choose a tag type with the scope you need. |
| `TAG_TYPE_SET` |  | Leave `typeId` out, or change the tag's type in the console first. |
| `TAG_TYPE_SYSTEM` |  | Choose a tag type for this tag's system. |
| `TAG_UNDO_EXPIRED` |  | Add the tag again. |
| `TAG_USE_MISMATCH` |  | Choose a tag type whose use the template accepts. |
| `TEMPLATE_IN_TAG_TYPE` |  | Remove it from the type first. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `VALIDATION` |  | Fix each field in issues and resend. |

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

## Console only

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

- `GET /api/v1/nfc/passes/{passId}/tags`: Tags that open a pass
- `POST /api/v1/nfc/passes/{passId}/tags`: Put a removed tag back on a pass
- `PATCH /api/v1/nfc/bindings/{bindingId}`: Change what a tag works with
- `DELETE /api/v1/nfc/bindings/{bindingId}`: Remove a tag from its pass or person
- `GET /api/v1/nfc/tags`: List tags
- `GET /api/v1/nfc/tags/{id}`: Get a tag
- `PATCH /api/v1/nfc/tags/{id}`: Rename a tag
- `POST /api/v1/nfc/tags/{id}/retire`: Retire a tag
- `POST /api/v1/nfc/tags/{id}/restore`: Restore a retired or lost tag
- `POST /api/v1/nfc/tags/{id}/lost`: Report a tag lost
- `GET /api/v1/nfc/scanners`: Scanners that can take a tag request
- `POST /api/v1/nfc/passes/{passId}/enrollments`: Ask a scanner to read a tag for a pass
- `GET /api/v1/nfc/passes/{passId}/enrollments/{id}`: A tag request
- `DELETE /api/v1/nfc/passes/{passId}/enrollments/{id}`: Cancel a tag request
- `POST /api/v1/nfc/passes/{passId}/tags/assign`: Assign a typed tag ID or a spare tag to a pass
- `GET /api/v1/nfc/tags/{id}/history`: Every binding a tag has had
- `GET /api/v1/nfc/users/{userId}/tags`: Tags that open a user's passes
- `GET /api/v1/nfc/keysets`: List tag keysets
- `POST /api/v1/nfc/keysets`: Create a tag keyset
- `POST /api/v1/nfc/keysets/{id}/rotate`: Rotate a keyset to a new key version
- `POST /api/v1/nfc/keysets/{id}/keys/{version}/retire`: Retire an old key version
- `POST /api/v1/nfc/keysets/{id}/keys/{version}/revoke`: Revoke a key version: tags on it must be written again
- `POST /api/v1/nfc/keysets/{id}/reenrol`: Move the tags of a keyset to another keyset
- `POST /api/v1/nfc/keysets/{id}/import`: Import supplier-personalised tags (dry run or add)
- `POST /api/v1/nfc/keysets/{id}/disable`: Disable a keyset
