NFC

4 operations. Send Authorization: Bearer $PASSBOOK_KEY. Markdown

Tag Types

GET/api/v1/nfc/tag-types
scans:readSDK pb.nfc.tagTypes.list

Query

cursorstring · max 64
limitinteger · ≥ 1 · ≤ 200

Returns

200

Errors

CodeStatusFix
ENROLLMENT_NOT_FOUNDCheck the enrollment id and start a new request if it expired.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
IMPORT_EMPTYUpload a CSV with a header line and one tag per row.
IMPORT_HEADERStart the file with a header line naming the uid and key columns.
IMPORT_TOO_MANYSplit the file and import it in parts.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
KEYSET_CHANGEDFetch the keyset and send the change again.
KEYSET_KEY_INVALIDSend each key as 32 hexadecimal characters.
KEYSET_KEY_NOT_FOUNDCheck the key version against the keyset's list and send it again.
KEYSET_KEY_REUSEDSend new keys this organization has never used.
KEYSET_KEY_WEAKSend two different, randomly generated keys.
KEYSET_NOT_FOUNDCheck the keyset id and the key's mode.
MISSING_SCOPECreate a key with the scope the operation lists under security.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_NOT_FOUNDCheck the id with GET /api/v1/passes and the key's mode.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
SCANNER_NOT_FOUNDCheck the scanner id and the key's mode.
SCANNER_NO_TAGSPick a scanner with tag reading on.
SCANNER_OFFLINEOpen the scanner app, then send the request again.
SCANNER_REQUESTS_OFFTurn on tag requests for the scanner, or pick another.
TAGS_OFFTurn on tags in the organization's settings.
TAG_ALREADY_ASSIGNEDFetch the tag and check its holder before reassigning.
TAG_ASSURANCE_LOWAssign a secure tag type to the pass.
TAG_HOLDER_CHANGEDFetch the tag and send the request again.
TAG_ID_INVALIDCheck the ID against the reader or the supplier's list.
TAG_KEY_UNREADABLERetry once; if it persists, send the requestId to support.
TAG_NOT_ASSIGNEDAssign the tag before this action.
TAG_NOT_FOUNDCheck the tag id.
TAG_NO_ACCOUNTAssign the tag to the pass instead.
TAG_POOL_UNSUPPORTEDAssign the tag to a pass or person instead.
TAG_REQUEST_BUSYCancel the open request or wait for it to finish.
TAG_SECURE_REQUIREDUse a Secure (SUN) tag, or lower the session's tag level.
TAG_SYSTEM_DISABLEDPick a tag system that is available, or contact the platform owner.
TAG_TYPED_OFFTap the tag on a scanner, or allow typed IDs on the tag type.
TAG_TYPE_ARCHIVEDRestore the tag type or use another.
TAG_TYPE_CHANGEDFetch the tag type and send your change again.
TAG_TYPE_CHOOSESend `typeId`, or set a default tag type for the organization.
TAG_TYPE_LIMITRemove the pass's current tag of this type first, or use another type.
TAG_TYPE_MISMATCHChoose a tag type that lists this pass's template.
TAG_TYPE_NAME_TAKENChoose a different name.
TAG_TYPE_NOT_FOUNDCheck the tag type id.
TAG_TYPE_SCOPEChoose a tag type with the scope you need.
TAG_TYPE_SETLeave `typeId` out, or change the tag's type in the console first.
TAG_TYPE_SYSTEMChoose a tag type for this tag's system.
TAG_UNDO_EXPIREDAdd the tag again.
TAG_USE_MISMATCHChoose a tag type whose use the template accepts.
TEMPLATE_IN_TAG_TYPERemove it from the type first.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNKNOWN_TEMPLATEUse template ids from GET /api/v1/templates.
VALIDATIONFix each field in issues and resend.
POST/api/v1/nfc/tag-types
scanning: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

CodeStatusFix
ENROLLMENT_NOT_FOUNDCheck the enrollment id and start a new request if it expired.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
IMPORT_EMPTYUpload a CSV with a header line and one tag per row.
IMPORT_HEADERStart the file with a header line naming the uid and key columns.
IMPORT_TOO_MANYSplit the file and import it in parts.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
KEYSET_CHANGEDFetch the keyset and send the change again.
KEYSET_KEY_INVALIDSend each key as 32 hexadecimal characters.
KEYSET_KEY_NOT_FOUNDCheck the key version against the keyset's list and send it again.
KEYSET_KEY_REUSEDSend new keys this organization has never used.
KEYSET_KEY_WEAKSend two different, randomly generated keys.
KEYSET_NOT_FOUNDCheck the keyset id and the key's mode.
MISSING_SCOPECreate a key with the scope the operation lists under security.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_NOT_FOUNDCheck the id with GET /api/v1/passes and the key's mode.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
SCANNER_NOT_FOUNDCheck the scanner id and the key's mode.
SCANNER_NO_TAGSPick a scanner with tag reading on.
SCANNER_OFFLINEOpen the scanner app, then send the request again.
SCANNER_REQUESTS_OFFTurn on tag requests for the scanner, or pick another.
TAGS_OFFTurn on tags in the organization's settings.
TAG_ALREADY_ASSIGNEDFetch the tag and check its holder before reassigning.
TAG_ASSURANCE_LOWAssign a secure tag type to the pass.
TAG_HOLDER_CHANGEDFetch the tag and send the request again.
TAG_ID_INVALIDCheck the ID against the reader or the supplier's list.
TAG_KEY_UNREADABLERetry once; if it persists, send the requestId to support.
TAG_NOT_ASSIGNEDAssign the tag before this action.
TAG_NOT_FOUNDCheck the tag id.
TAG_NO_ACCOUNTAssign the tag to the pass instead.
TAG_POOL_UNSUPPORTEDAssign the tag to a pass or person instead.
TAG_REQUEST_BUSYCancel the open request or wait for it to finish.
TAG_SECURE_REQUIREDUse a Secure (SUN) tag, or lower the session's tag level.
TAG_SYSTEM_DISABLEDPick a tag system that is available, or contact the platform owner.
TAG_TYPED_OFFTap the tag on a scanner, or allow typed IDs on the tag type.
TAG_TYPE_ARCHIVEDRestore the tag type or use another.
TAG_TYPE_CHANGEDFetch the tag type and send your change again.
TAG_TYPE_CHOOSESend `typeId`, or set a default tag type for the organization.
TAG_TYPE_LIMITRemove the pass's current tag of this type first, or use another type.
TAG_TYPE_MISMATCHChoose a tag type that lists this pass's template.
TAG_TYPE_NAME_TAKENChoose a different name.
TAG_TYPE_NOT_FOUNDCheck the tag type id.
TAG_TYPE_SCOPEChoose a tag type with the scope you need.
TAG_TYPE_SETLeave `typeId` out, or change the tag's type in the console first.
TAG_TYPE_SYSTEMChoose a tag type for this tag's system.
TAG_UNDO_EXPIREDAdd the tag again.
TAG_USE_MISMATCHChoose a tag type whose use the template accepts.
TEMPLATE_IN_TAG_TYPERemove it from the type first.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNKNOWN_TEMPLATEUse template ids from GET /api/v1/templates.
VALIDATIONFix 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

CodeStatusFix
ENROLLMENT_NOT_FOUNDCheck the enrollment id and start a new request if it expired.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
IMPORT_EMPTYUpload a CSV with a header line and one tag per row.
IMPORT_HEADERStart the file with a header line naming the uid and key columns.
IMPORT_TOO_MANYSplit the file and import it in parts.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
KEYSET_CHANGEDFetch the keyset and send the change again.
KEYSET_KEY_INVALIDSend each key as 32 hexadecimal characters.
KEYSET_KEY_NOT_FOUNDCheck the key version against the keyset's list and send it again.
KEYSET_KEY_REUSEDSend new keys this organization has never used.
KEYSET_KEY_WEAKSend two different, randomly generated keys.
KEYSET_NOT_FOUNDCheck the keyset id and the key's mode.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_NOT_FOUNDCheck the id with GET /api/v1/passes and the key's mode.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
SCANNER_NOT_FOUNDCheck the scanner id and the key's mode.
SCANNER_NO_TAGSPick a scanner with tag reading on.
SCANNER_OFFLINEOpen the scanner app, then send the request again.
SCANNER_REQUESTS_OFFTurn on tag requests for the scanner, or pick another.
TAGS_OFFTurn on tags in the organization's settings.
TAG_ALREADY_ASSIGNEDFetch the tag and check its holder before reassigning.
TAG_ASSURANCE_LOWAssign a secure tag type to the pass.
TAG_HOLDER_CHANGEDFetch the tag and send the request again.
TAG_ID_INVALIDCheck the ID against the reader or the supplier's list.
TAG_KEY_UNREADABLERetry once; if it persists, send the requestId to support.
TAG_NOT_ASSIGNEDAssign the tag before this action.
TAG_NOT_FOUNDCheck the tag id.
TAG_NO_ACCOUNTAssign the tag to the pass instead.
TAG_POOL_UNSUPPORTEDAssign the tag to a pass or person instead.
TAG_REQUEST_BUSYCancel the open request or wait for it to finish.
TAG_SECURE_REQUIREDUse a Secure (SUN) tag, or lower the session's tag level.
TAG_SYSTEM_DISABLEDPick a tag system that is available, or contact the platform owner.
TAG_TYPED_OFFTap the tag on a scanner, or allow typed IDs on the tag type.
TAG_TYPE_ARCHIVEDRestore the tag type or use another.
TAG_TYPE_CHANGEDFetch the tag type and send your change again.
TAG_TYPE_CHOOSESend `typeId`, or set a default tag type for the organization.
TAG_TYPE_LIMITRemove the pass's current tag of this type first, or use another type.
TAG_TYPE_MISMATCHChoose a tag type that lists this pass's template.
TAG_TYPE_NAME_TAKENChoose a different name.
TAG_TYPE_NOT_FOUNDCheck the tag type id.
TAG_TYPE_SCOPEChoose a tag type with the scope you need.
TAG_TYPE_SETLeave `typeId` out, or change the tag's type in the console first.
TAG_TYPE_SYSTEMChoose a tag type for this tag's system.
TAG_UNDO_EXPIREDAdd the tag again.
TAG_USE_MISMATCHChoose a tag type whose use the template accepts.
TEMPLATE_IN_TAG_TYPERemove it from the type first.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNKNOWN_TEMPLATEUse template ids from GET /api/v1/templates.
VALIDATIONFix each field in issues and resend.
POST/api/v1/nfc/tag-types/{id}/archive
scanning:writeSDK pb.nfc.tagTypes.archive

Path

idstring · max 64Required

Body

versioninteger · ≥ 1Required

Returns

200

Errors

CodeStatusFix
ENROLLMENT_NOT_FOUNDCheck the enrollment id and start a new request if it expired.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
IMPORT_EMPTYUpload a CSV with a header line and one tag per row.
IMPORT_HEADERStart the file with a header line naming the uid and key columns.
IMPORT_TOO_MANYSplit the file and import it in parts.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
KEYSET_CHANGEDFetch the keyset and send the change again.
KEYSET_KEY_INVALIDSend each key as 32 hexadecimal characters.
KEYSET_KEY_NOT_FOUNDCheck the key version against the keyset's list and send it again.
KEYSET_KEY_REUSEDSend new keys this organization has never used.
KEYSET_KEY_WEAKSend two different, randomly generated keys.
KEYSET_NOT_FOUNDCheck the keyset id and the key's mode.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_NOT_FOUNDCheck the id with GET /api/v1/passes and the key's mode.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
SCANNER_NOT_FOUNDCheck the scanner id and the key's mode.
SCANNER_NO_TAGSPick a scanner with tag reading on.
SCANNER_OFFLINEOpen the scanner app, then send the request again.
SCANNER_REQUESTS_OFFTurn on tag requests for the scanner, or pick another.
TAGS_OFFTurn on tags in the organization's settings.
TAG_ALREADY_ASSIGNEDFetch the tag and check its holder before reassigning.
TAG_ASSURANCE_LOWAssign a secure tag type to the pass.
TAG_HOLDER_CHANGEDFetch the tag and send the request again.
TAG_ID_INVALIDCheck the ID against the reader or the supplier's list.
TAG_KEY_UNREADABLERetry once; if it persists, send the requestId to support.
TAG_NOT_ASSIGNEDAssign the tag before this action.
TAG_NOT_FOUNDCheck the tag id.
TAG_NO_ACCOUNTAssign the tag to the pass instead.
TAG_POOL_UNSUPPORTEDAssign the tag to a pass or person instead.
TAG_REQUEST_BUSYCancel the open request or wait for it to finish.
TAG_SECURE_REQUIREDUse a Secure (SUN) tag, or lower the session's tag level.
TAG_SYSTEM_DISABLEDPick a tag system that is available, or contact the platform owner.
TAG_TYPED_OFFTap the tag on a scanner, or allow typed IDs on the tag type.
TAG_TYPE_ARCHIVEDRestore the tag type or use another.
TAG_TYPE_CHANGEDFetch the tag type and send your change again.
TAG_TYPE_CHOOSESend `typeId`, or set a default tag type for the organization.
TAG_TYPE_LIMITRemove the pass's current tag of this type first, or use another type.
TAG_TYPE_MISMATCHChoose a tag type that lists this pass's template.
TAG_TYPE_NAME_TAKENChoose a different name.
TAG_TYPE_NOT_FOUNDCheck the tag type id.
TAG_TYPE_SCOPEChoose a tag type with the scope you need.
TAG_TYPE_SETLeave `typeId` out, or change the tag's type in the console first.
TAG_TYPE_SYSTEMChoose a tag type for this tag's system.
TAG_UNDO_EXPIREDAdd the tag again.
TAG_USE_MISMATCHChoose a tag type whose use the template accepts.
TEMPLATE_IN_TAG_TYPERemove it from the type first.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNKNOWN_TEMPLATEUse template ids from GET /api/v1/templates.
VALIDATIONFix 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 pass
POST/api/v1/nfc/passes/{passId}/tagsPut a removed tag back on a pass
PATCH/api/v1/nfc/bindings/{bindingId}Change what a tag works with
DEL/api/v1/nfc/bindings/{bindingId}Remove a tag from its pass or person
GET/api/v1/nfc/tagsList 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}/retireRetire a tag
POST/api/v1/nfc/tags/{id}/restoreRestore a retired or lost tag
POST/api/v1/nfc/tags/{id}/lostReport a tag lost
GET/api/v1/nfc/scannersScanners that can take a tag request
POST/api/v1/nfc/passes/{passId}/enrollmentsAsk a scanner to read a tag for a pass
GET/api/v1/nfc/passes/{passId}/enrollments/{id}A tag request
DEL/api/v1/nfc/passes/{passId}/enrollments/{id}Cancel a tag request
POST/api/v1/nfc/passes/{passId}/tags/assignAssign a typed tag ID or a spare tag to a pass
GET/api/v1/nfc/tags/{id}/historyEvery binding a tag has had
GET/api/v1/nfc/users/{userId}/tagsTags that open a user's passes
GET/api/v1/nfc/keysetsList tag keysets
POST/api/v1/nfc/keysetsCreate a tag keyset
POST/api/v1/nfc/keysets/{id}/rotateRotate a keyset to a new key version
POST/api/v1/nfc/keysets/{id}/keys/{version}/retireRetire an old key version
POST/api/v1/nfc/keysets/{id}/keys/{version}/revokeRevoke a key version: tags on it must be written again
POST/api/v1/nfc/keysets/{id}/reenrolMove the tags of a keyset to another keyset
POST/api/v1/nfc/keysets/{id}/importImport supplier-personalised tags (dry run or add)
POST/api/v1/nfc/keysets/{id}/disableDisable a keyset