ReferenceNFC
NFC
4 operations. Send Authorization: Bearer $PASSBOOK_KEY. Markdown
Tag Types
GET
/api/v1/nfc/tag-typesscans:readSDK pb.nfc.tagTypes.list
Query
cursorstring · max 64
limitinteger · ≥ 1 · ≤ 200
Returns
200
Errors
| 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. |
POST
/api/v1/nfc/tag-typesscanning:writeSDK pb.nfc.tagTypes.create
Body
namestring · max 40Required
use"member" | "staff" | "visitor"Required
scopes"pass" | "user" | "both"
perPassinteger · ≥ 1 · ≤ 4
bindingDaysinteger | null · ≥ 1 · ≤ 3650
confirm"none" | "staff" | "manager"
typedboolean
templateIdsstring · max 64[]
system"uid" | "sun"
Returns
201
Errors
| 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. |
PATCH
/api/v1/nfc/tag-types/{id}scanning:writeSDK pb.nfc.tagTypes.update
Path
idstring · max 64Required
Body
versioninteger · ≥ 1Required
namestring · max 40
use"member" | "staff" | "visitor"
scopes"pass" | "user" | "both"
perPassinteger · ≥ 1 · ≤ 4
bindingDaysinteger | null · ≥ 1 · ≤ 3650
confirm"none" | "staff" | "manager"
typedboolean
templateIdsstring · max 64[]
Returns
200
Errors
| 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. |
POST
/api/v1/nfc/tag-types/{id}/archivescanning:writeSDK pb.nfc.tagTypes.archive
Path
idstring · max 64Required
Body
versioninteger · ≥ 1Required
Returns
200
Errors
| 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. |
Console only
Signed-in console sessions only. An API key cannot call these.
GET
/api/v1/nfc/passes/{passId}/tagsTags that open a passPOST
/api/v1/nfc/passes/{passId}/tagsPut a removed tag back on a passPATCH
/api/v1/nfc/bindings/{bindingId}Change what a tag works withDEL
/api/v1/nfc/bindings/{bindingId}Remove a tag from its pass or personGET
/api/v1/nfc/tagsList tagsGET
/api/v1/nfc/tags/{id}Get a tagPATCH
/api/v1/nfc/tags/{id}Rename a tagPOST
/api/v1/nfc/tags/{id}/retireRetire a tagPOST
/api/v1/nfc/tags/{id}/restoreRestore a retired or lost tagPOST
/api/v1/nfc/tags/{id}/lostReport a tag lostGET
/api/v1/nfc/scannersScanners that can take a tag requestPOST
/api/v1/nfc/passes/{passId}/enrollmentsAsk a scanner to read a tag for a passGET
/api/v1/nfc/passes/{passId}/enrollments/{id}A tag requestDEL
/api/v1/nfc/passes/{passId}/enrollments/{id}Cancel a tag requestPOST
/api/v1/nfc/passes/{passId}/tags/assignAssign a typed tag ID or a spare tag to a passGET
/api/v1/nfc/tags/{id}/historyEvery binding a tag has hadGET
/api/v1/nfc/users/{userId}/tagsTags that open a user's passesGET
/api/v1/nfc/keysetsList tag keysetsPOST
/api/v1/nfc/keysetsCreate a tag keysetPOST
/api/v1/nfc/keysets/{id}/rotateRotate a keyset to a new key versionPOST
/api/v1/nfc/keysets/{id}/keys/{version}/retireRetire an old key versionPOST
/api/v1/nfc/keysets/{id}/keys/{version}/revokeRevoke a key version: tags on it must be written againPOST
/api/v1/nfc/keysets/{id}/reenrolMove the tags of a keyset to another keysetPOST
/api/v1/nfc/keysets/{id}/importImport supplier-personalised tags (dry run or add)POST
/api/v1/nfc/keysets/{id}/disableDisable a keyset