ReferenceScanning

Till API

3 operations. Send Authorization: Bearer $PASSBOOK_KEY. Markdown

POST/api/v1/scan/resolve
scans:writeSDK pb.terminal.resolve

Body

idempotencyKeystringRequired
inputobject | object | objectRequired
clientTsinteger · ≥ 0Required
dayStartinteger · ≥ 0
scopeobject
orgIdstring · max 64Required
timeZonestring · max 64Required
setupIdstring · max 64
eventIdstring · max 64
templateIdsstring · max 64[]

Returns

200 ScanOutcome

Errors

CodeStatusFix
ACTOR_CHANGEDCheck the key's scopes and organization with GET /api/v1/api-keys/me, then send the request again.
ADMITS_TOO_MANYShorten admits so it names fewer pass types, then send the request again.
API_KEY_NO_APPROVALApprove on a paired scanner with a staff PIN.
API_KEY_ORG_REQUIREDCall scan endpoints with a key scoped to one organization.
API_KEY_ROUTECall this route from a paired scanner or a signed-in session.
ASSET_NOT_FOUNDCheck the image name or id and that it belongs to this organization.
BLUEPRINT_NOT_SCANNABLECreate a template from the blueprint with POST /api/v1/templates/{id}/use, then set up scanning on it.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
CSRF_ORIGINCall the API server-side with an API key in the Authorization header instead of from a browser page.
DEVICE_REQUIREDName the terminal in the device header on scan calls; open live connections from a paired scanner.
ENROLLMENT_ENDEDStart a new enrollment request.
ENROLLMENT_NOT_FOUNDCheck the enrollment id and start a new request if it expired.
EVENT_ARCHIVEDUse an event that is not archived, or create a new one.
EVENT_IN_USEEnd or change the sessions that use the event, then send the request again.
EVENT_MATCH_INPUTSet the match input to a single-value input from GET /api/v1/templates/{id}/input-schema.
EVENT_NEEDS_CAPACITYSet the event's capacity, then send the request again.
EVENT_NOT_FOUNDCheck the id with GET /api/v1/scan/events.
EVENT_TEMPLATE_NO_CHECK_INPick a template that defines check-in, or add the action to this one.
EVENT_TEMPLATE_RELEASE_REQUIREDApprove a release for the template with POST /api/v1/templates/{id}/releases, then retry.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
GROUP_ENTRY_ONLYUse check in all only on an entry scanner.
IDEMPOTENCY_KEY_REUSEDUse a new key for a new request; resend the identical request to replay.
IMAGE_NOT_FOUNDUpload one with PUT /api/v1/orgs/{id}/branding/{slot}.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
INVALID_CURSORPass the nextCursor from the previous page unchanged, or drop it to start over.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOTE_CAPDelete an old note before adding another.
NOTE_DEVICE_CAPAdd the note from another device or wait until tomorrow.
NOTE_HELDAsk an org admin to release the hold. Adding a note still works.
NOTE_NOT_FOUNDCheck the note id.
NOTE_ROLESign in as Desk staff or a manager with the staff PIN.
NOT_INSIDEDo nothing; check occupancy before marking out.
OFFLINE_OFFTurn on offline scanning for the session, or scan online.
OFFLINE_TOO_BIGNarrow the session to fewer events or pass types.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
ORG_REQUIREDSend orgId with the request, or use a key scoped to one organization.
PAIRING_INVALIDCreate a new pairing code and enter it again.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
PASS_NOT_FOUNDCheck the id with GET /api/v1/passes and the key's mode.
PHOTO_PASS_INACTIVEUse an active pass.
PHOTO_ROLESign in as Desk staff with the staff PIN.
PIN_GENERATION_FAILEDRetry the request.
PIN_INVALIDEnter the correct PIN; repeated misses lock the entry for a while.
PIN_MANAGER_REQUIREDName a manager in the request.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
ROLE_NOT_ALLOWEDChange the role from the scanner's setup in the admin console.
ROLL_CALL_ENDEDStart a new roll call.
ROLL_CALL_NOT_FOUNDCheck the roll call id.
ROLL_CALL_NO_PLACESTurn on occupancy tracking for the session, then start the roll call.
ROLL_CALL_NO_SESSIONAssign the scanner to a session in the admin console, then start the roll call.
ROLL_CALL_TOO_LARGEMark people out in bulk before starting the roll call.
SAMPLE_TEST_ONLYRequest sample passes from a test-mode scanner.
SCANNER_ADMIN_ROLEUse a browser device for admin sign-in.
SCANNER_ADMIN_SETUP_EXISTSUse the existing admin setup.
SCANNER_ADMIN_USERCreate it signed in as that admin, and leave out another user.
SCANNER_CANNOT_SCANAssign events only to scanning devices.
SCANNER_CHANGEDFetch the scanner and send your change again.
SCANNER_EXPIREDPair the scanner again.
SCANNER_NAME_TAKENChoose a different name.
SCANNER_NOT_FOUNDCheck the scanner id and the key's mode.
SCANNER_NOT_PAIRABLEUse the pairing method for this device type.
SCANNER_NOT_TERMINALCreate a token only for a till scanner.
SCANNER_REPAIRPair the scanner again with a new code.
SCANNER_REVOKEDPair a new scanner.
SCANNER_ROLE_INVALIDChoose a role the device supports.
SCANNER_SETUP_EXISTSUse the existing setup or give the new one another name.
SCANNER_UNASSIGNEDChoose what it accepts, then send the request again.
SCANNER_UNAUTHENTICATEDPair the scanner, then sign in with the staff PIN.
SCANNER_WATCH_INVALIDChoose at least one scanner or session to follow.
SCANNER_WATCH_MODEMove them to the same mode, or choose others.
SCANNER_WATCH_NOT_FOUNDRemove it from the watch list.
SCANNING_DEVICE_CHANGEDFetch the device and send your change again.
SCANNING_DEVICE_NOT_FOUNDCheck the device id.
SCANNING_HOLD_RANGEOpen scanning for at most 24 hours.
SCANNING_HOURS_NONEPause the session instead, or add scanning hours.
SCANNING_SESSION_CHANGEDFetch the session and send your change again.
SCANNING_SESSION_CLOSEDWait for the next opening, or open it for a while.
SCANNING_SESSION_CONFIG_REQUIREDChange the settings on the session, not on the device.
SCANNING_SESSION_COUNTS_UNAVAILABLERetry with backoff.
SCANNING_SESSION_MODEOpen the device in the session's mode.
SCANNING_SESSION_NOT_FOUNDCheck the session id.
SCANNING_SESSION_OPENDo nothing; close it first to change how long it stays open.
SCANNING_SESSION_PAUSEDResume the session, then scan again.
SCANNING_SESSION_SCOPE_INVALIDCorrect the session's scope and settings, then add the device.
SCANNING_SESSION_SETTINGS_INVALIDCorrect the session's settings, then retry.
SCAN_ACCESS_CHANGEDReload the session and send the request again.
SCAN_ADMIN_SETUP_REQUIREDChoose the admin setup in the console, then retry.
SCAN_BODY_INVALIDSend a JSON body with Content-Type: application/json.
SCAN_CONFIG_CHANGEDReload the scanner and scan again.
SCAN_COUNTS_UNAVAILABLERetry with backoff.
SCAN_CREDENTIAL_CHANGEDReconnect the scanner so it picks up the new credential.
SCAN_DISPLAY_PREVIEW_NOT_FOUNDCreate the preview again and use its new id.
SCAN_EVENT_CHANGEDFetch the event with GET /api/v1/scan/events and send your change again.
SCAN_EXPORT_RANGEExport up to 92 days per request.
SCAN_EXPORT_TOO_LARGENarrow the date range or filters and export in parts.
SCAN_HISTORY_UNAVAILABLERetry with backoff.
SCAN_IN_PROGRESSWait a moment and resend the identical request.
SCAN_KEY_REUSEDUse a new unique request key for each action.
SCAN_LIVE_ORIGINOpen the screen on the PassBook site.
SCAN_LOOKUP_DISABLEDTurn on lookup in the scanner's settings.
SCAN_MARK_OUT_INVALIDCheck who is inside, then mark out someone who is.
SCAN_MODE_MISMATCHUse a key and objects of the same mode.
SCAN_NOT_FOUNDCheck the scan id and the scanner's mode.
SCAN_NO_SESSIONAssign the scanner to a session in the admin console.
SCAN_OVERRIDE_FORBIDDENDo not retry; no one can let this person in.
SCAN_OVERRIDE_INVALIDOverride only scans that were refused for an overridable reason.
SCAN_OVERRIDE_NOTE_CLOSEDAdd the note when you override, not afterwards.
SCAN_OVERRIDE_TAKENDo nothing; check the scan's history.
SCAN_PASS_CHANGEDScan the pass again.
SCAN_SCOPE_NOT_ALLOWEDLeave out the scope; a paired scanner uses its own.
SCAN_SCOPE_REQUIREDSend orgId, or use a key scoped to one organization.
SCAN_SEARCH_FORBIDDENSearch by pass id or code, or sign in as an administrator.
SCAN_SETTINGS_INVALIDCorrect the settings named in issues, then retry.
SCAN_SETUP_CONFLICTRemove the template from the other session, or reuse that session.
SCAN_STAFF_CHANGEDFetch the staff list and send the request again.
SCAN_STAFF_CURSORDrop the cursor and list again from the start.
SCAN_STAFF_NOT_FOUNDCheck the id with the scanner's staff list.
SCAN_SUMMARY_SESSION_FORBIDDENSign in with a manager PIN.
SCAN_SURFACE_UNSUPPORTEDUse a screen device for displays.
SCAN_TOO_MANY_MISSESWait a few minutes, then scan again.
SCAN_TOO_MANY_OVERRIDESWait for the next hour, or ask a manager.
SCAN_UNDO_EXPIREDCorrect the record by other means, such as marking the person out.
SCAN_UNDO_FORBIDDENAsk a manager, or the operator who made the scan, to undo it.
SCREEN_ONLYUse a scanner device for scanning.
SCREEN_REQUIREDChoose a screen view for the device in Scanning.
SESSION_OPEN_FORBIDDENSign in with a manager PIN, then open it.
STAFF_NAME_REQUIREDSend staffId with the PIN.
STAFF_NAME_TAKENChoose a different name.
STAFF_REQUIREDSign in with a staff PIN, then retry.
STAFF_SIGN_IN_DISABLEDTurn on staff sign-in in the scanner's settings.
STAFF_SIGN_IN_UNAVAILABLEPair the scanner, then sign in.
TAG_APPROVAL_REQUIREDHave a manager approve it with their PIN.
TAG_ASSIGN_FORBIDDENTurn on assigning in the scanner's settings, or sign in as Desk or above.
TAG_CARD_AMBIGUOUSScan the card again, or assign the tag to a pass directly.
TAG_CHECK_FAILEDUse a different tag.
TAG_HOLDER_CHANGEDFetch the tag and send the request again.
TAG_LIMITRelease unused tags, or ask the platform owner to raise the limit.
TAG_NOT_FOUNDCheck the tag id.
TAG_NO_ACCOUNTAssign the tag to the pass instead.
TAG_PASS_NOT_ACCEPTEDAdd the pass's template or event to the scanner's session.
TAG_POOL_UNSUPPORTEDAssign the tag to a pass or person instead.
TAG_REQUEST_EXPIREDCreate a new tag request.
TAG_SCANNER_ONLYAssign the tag from a paired scanner.
TAG_SUN_REPLAYTap the tag again for a fresh read.
TAG_UID_RANDOMUse a tag with a fixed ID.
TAG_UNDO_EXPIREDAdd the tag again.
TAG_UNDO_FORBIDDENUndo on that scanner, or have an admin remove the tag.
TAG_UNREADABLEHold the tag steady, or use another tag.
TEMPLATE_ARCHIVEDRestore it with POST /api/v1/templates/{id}/restore, or use another template.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_NOT_RELEASEDRelease the template with POST /api/v1/templates/{id}/releases.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TERMINAL_NOT_FOUNDUse a terminal id from the key's terminals.
TERMINAL_ONLYName one of the key's terminals in the device header.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNDO_SUPERSEDEDUndo the latest scan instead.
UNDO_UNCONFIRMEDCheck the scan's state, then retry once; if it persists, send the requestId to support.
UNLOCK_REQUIREDEnter a staff PIN.
USER_NOT_FOUNDCheck the id with GET /api/v1/users.
VALIDATIONFix each field in issues and resend.
ZONE_ARCHIVEDUse a zone that is not archived.
ZONE_CYCLEChoose a parent outside the zone.
ZONE_DEPTHMove the zone higher in the tree.
ZONE_EVENT_SESSIONUse a zone session, or remove the zones.
ZONE_KEY_TAKENChoose a different key.
ZONE_NAME_TAKENChoose a different name.
ZONE_NOT_FOUNDCheck the zone id.
POST/api/v1/scan/actions
scans:writeSDK pb.terminal.act

Body

idempotencyKeystringRequired
inputobject | object | objectRequired
clientTsinteger · ≥ 0Required
actionIdstring · max 32 | "auto"Required
dayStartinteger · ≥ 0
scopeobject
orgIdstring · max 64Required
timeZonestring · max 64Required
setupIdstring · max 64
eventIdstring · max 64
templateIdsstring · max 64[]
amountnumber
valueany
direction"in" | "out"
overrideOfstring · max 64
confirmedboolean
expectedVersioninteger
group"bundle"
approvalobject
pinstring · ^\d{6}$Required
staffIdstring · max 64

Returns

200 ScanOutcome

Errors

CodeStatusFix
ACTOR_CHANGEDCheck the key's scopes and organization with GET /api/v1/api-keys/me, then send the request again.
ADMITS_TOO_MANYShorten admits so it names fewer pass types, then send the request again.
API_KEY_NO_APPROVALApprove on a paired scanner with a staff PIN.
API_KEY_ORG_REQUIREDCall scan endpoints with a key scoped to one organization.
API_KEY_ROUTECall this route from a paired scanner or a signed-in session.
ASSET_NOT_FOUNDCheck the image name or id and that it belongs to this organization.
BLUEPRINT_NOT_SCANNABLECreate a template from the blueprint with POST /api/v1/templates/{id}/use, then set up scanning on it.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
CSRF_ORIGINCall the API server-side with an API key in the Authorization header instead of from a browser page.
DEVICE_REQUIREDName the terminal in the device header on scan calls; open live connections from a paired scanner.
ENROLLMENT_ENDEDStart a new enrollment request.
ENROLLMENT_NOT_FOUNDCheck the enrollment id and start a new request if it expired.
EVENT_ARCHIVEDUse an event that is not archived, or create a new one.
EVENT_IN_USEEnd or change the sessions that use the event, then send the request again.
EVENT_MATCH_INPUTSet the match input to a single-value input from GET /api/v1/templates/{id}/input-schema.
EVENT_NEEDS_CAPACITYSet the event's capacity, then send the request again.
EVENT_NOT_FOUNDCheck the id with GET /api/v1/scan/events.
EVENT_TEMPLATE_NO_CHECK_INPick a template that defines check-in, or add the action to this one.
EVENT_TEMPLATE_RELEASE_REQUIREDApprove a release for the template with POST /api/v1/templates/{id}/releases, then retry.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
GROUP_ENTRY_ONLYUse check in all only on an entry scanner.
IDEMPOTENCY_KEY_REUSEDUse a new key for a new request; resend the identical request to replay.
IMAGE_NOT_FOUNDUpload one with PUT /api/v1/orgs/{id}/branding/{slot}.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
INVALID_CURSORPass the nextCursor from the previous page unchanged, or drop it to start over.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOTE_CAPDelete an old note before adding another.
NOTE_DEVICE_CAPAdd the note from another device or wait until tomorrow.
NOTE_HELDAsk an org admin to release the hold. Adding a note still works.
NOTE_NOT_FOUNDCheck the note id.
NOTE_ROLESign in as Desk staff or a manager with the staff PIN.
NOT_INSIDEDo nothing; check occupancy before marking out.
OFFLINE_OFFTurn on offline scanning for the session, or scan online.
OFFLINE_TOO_BIGNarrow the session to fewer events or pass types.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
ORG_REQUIREDSend orgId with the request, or use a key scoped to one organization.
PAIRING_INVALIDCreate a new pairing code and enter it again.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
PASS_NOT_FOUNDCheck the id with GET /api/v1/passes and the key's mode.
PHOTO_PASS_INACTIVEUse an active pass.
PHOTO_ROLESign in as Desk staff with the staff PIN.
PIN_GENERATION_FAILEDRetry the request.
PIN_INVALIDEnter the correct PIN; repeated misses lock the entry for a while.
PIN_MANAGER_REQUIREDName a manager in the request.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
ROLE_NOT_ALLOWEDChange the role from the scanner's setup in the admin console.
ROLL_CALL_ENDEDStart a new roll call.
ROLL_CALL_NOT_FOUNDCheck the roll call id.
ROLL_CALL_NO_PLACESTurn on occupancy tracking for the session, then start the roll call.
ROLL_CALL_NO_SESSIONAssign the scanner to a session in the admin console, then start the roll call.
ROLL_CALL_TOO_LARGEMark people out in bulk before starting the roll call.
SAMPLE_TEST_ONLYRequest sample passes from a test-mode scanner.
SCANNER_ADMIN_ROLEUse a browser device for admin sign-in.
SCANNER_ADMIN_SETUP_EXISTSUse the existing admin setup.
SCANNER_ADMIN_USERCreate it signed in as that admin, and leave out another user.
SCANNER_CANNOT_SCANAssign events only to scanning devices.
SCANNER_CHANGEDFetch the scanner and send your change again.
SCANNER_EXPIREDPair the scanner again.
SCANNER_NAME_TAKENChoose a different name.
SCANNER_NOT_FOUNDCheck the scanner id and the key's mode.
SCANNER_NOT_PAIRABLEUse the pairing method for this device type.
SCANNER_NOT_TERMINALCreate a token only for a till scanner.
SCANNER_REPAIRPair the scanner again with a new code.
SCANNER_REVOKEDPair a new scanner.
SCANNER_ROLE_INVALIDChoose a role the device supports.
SCANNER_SETUP_EXISTSUse the existing setup or give the new one another name.
SCANNER_UNASSIGNEDChoose what it accepts, then send the request again.
SCANNER_UNAUTHENTICATEDPair the scanner, then sign in with the staff PIN.
SCANNER_WATCH_INVALIDChoose at least one scanner or session to follow.
SCANNER_WATCH_MODEMove them to the same mode, or choose others.
SCANNER_WATCH_NOT_FOUNDRemove it from the watch list.
SCANNING_DEVICE_CHANGEDFetch the device and send your change again.
SCANNING_DEVICE_NOT_FOUNDCheck the device id.
SCANNING_HOLD_RANGEOpen scanning for at most 24 hours.
SCANNING_HOURS_NONEPause the session instead, or add scanning hours.
SCANNING_SESSION_CHANGEDFetch the session and send your change again.
SCANNING_SESSION_CLOSEDWait for the next opening, or open it for a while.
SCANNING_SESSION_CONFIG_REQUIREDChange the settings on the session, not on the device.
SCANNING_SESSION_COUNTS_UNAVAILABLERetry with backoff.
SCANNING_SESSION_MODEOpen the device in the session's mode.
SCANNING_SESSION_NOT_FOUNDCheck the session id.
SCANNING_SESSION_OPENDo nothing; close it first to change how long it stays open.
SCANNING_SESSION_PAUSEDResume the session, then scan again.
SCANNING_SESSION_SCOPE_INVALIDCorrect the session's scope and settings, then add the device.
SCANNING_SESSION_SETTINGS_INVALIDCorrect the session's settings, then retry.
SCAN_ACCESS_CHANGEDReload the session and send the request again.
SCAN_ADMIN_SETUP_REQUIREDChoose the admin setup in the console, then retry.
SCAN_BODY_INVALIDSend a JSON body with Content-Type: application/json.
SCAN_CONFIG_CHANGEDReload the scanner and scan again.
SCAN_COUNTS_UNAVAILABLERetry with backoff.
SCAN_CREDENTIAL_CHANGEDReconnect the scanner so it picks up the new credential.
SCAN_DISPLAY_PREVIEW_NOT_FOUNDCreate the preview again and use its new id.
SCAN_EVENT_CHANGEDFetch the event with GET /api/v1/scan/events and send your change again.
SCAN_EXPORT_RANGEExport up to 92 days per request.
SCAN_EXPORT_TOO_LARGENarrow the date range or filters and export in parts.
SCAN_HISTORY_UNAVAILABLERetry with backoff.
SCAN_IN_PROGRESSWait a moment and resend the identical request.
SCAN_KEY_REUSEDUse a new unique request key for each action.
SCAN_LIVE_ORIGINOpen the screen on the PassBook site.
SCAN_LOOKUP_DISABLEDTurn on lookup in the scanner's settings.
SCAN_MARK_OUT_INVALIDCheck who is inside, then mark out someone who is.
SCAN_MODE_MISMATCHUse a key and objects of the same mode.
SCAN_NOT_FOUNDCheck the scan id and the scanner's mode.
SCAN_NO_SESSIONAssign the scanner to a session in the admin console.
SCAN_OVERRIDE_FORBIDDENDo not retry; no one can let this person in.
SCAN_OVERRIDE_INVALIDOverride only scans that were refused for an overridable reason.
SCAN_OVERRIDE_NOTE_CLOSEDAdd the note when you override, not afterwards.
SCAN_OVERRIDE_TAKENDo nothing; check the scan's history.
SCAN_PASS_CHANGEDScan the pass again.
SCAN_SCOPE_NOT_ALLOWEDLeave out the scope; a paired scanner uses its own.
SCAN_SCOPE_REQUIREDSend orgId, or use a key scoped to one organization.
SCAN_SEARCH_FORBIDDENSearch by pass id or code, or sign in as an administrator.
SCAN_SETTINGS_INVALIDCorrect the settings named in issues, then retry.
SCAN_SETUP_CONFLICTRemove the template from the other session, or reuse that session.
SCAN_STAFF_CHANGEDFetch the staff list and send the request again.
SCAN_STAFF_CURSORDrop the cursor and list again from the start.
SCAN_STAFF_NOT_FOUNDCheck the id with the scanner's staff list.
SCAN_SUMMARY_SESSION_FORBIDDENSign in with a manager PIN.
SCAN_SURFACE_UNSUPPORTEDUse a screen device for displays.
SCAN_TOO_MANY_MISSESWait a few minutes, then scan again.
SCAN_TOO_MANY_OVERRIDESWait for the next hour, or ask a manager.
SCAN_UNDO_EXPIREDCorrect the record by other means, such as marking the person out.
SCAN_UNDO_FORBIDDENAsk a manager, or the operator who made the scan, to undo it.
SCREEN_ONLYUse a scanner device for scanning.
SCREEN_REQUIREDChoose a screen view for the device in Scanning.
SESSION_OPEN_FORBIDDENSign in with a manager PIN, then open it.
STAFF_NAME_REQUIREDSend staffId with the PIN.
STAFF_NAME_TAKENChoose a different name.
STAFF_REQUIREDSign in with a staff PIN, then retry.
STAFF_SIGN_IN_DISABLEDTurn on staff sign-in in the scanner's settings.
STAFF_SIGN_IN_UNAVAILABLEPair the scanner, then sign in.
TAG_APPROVAL_REQUIREDHave a manager approve it with their PIN.
TAG_ASSIGN_FORBIDDENTurn on assigning in the scanner's settings, or sign in as Desk or above.
TAG_CARD_AMBIGUOUSScan the card again, or assign the tag to a pass directly.
TAG_CHECK_FAILEDUse a different tag.
TAG_HOLDER_CHANGEDFetch the tag and send the request again.
TAG_LIMITRelease unused tags, or ask the platform owner to raise the limit.
TAG_NOT_FOUNDCheck the tag id.
TAG_NO_ACCOUNTAssign the tag to the pass instead.
TAG_PASS_NOT_ACCEPTEDAdd the pass's template or event to the scanner's session.
TAG_POOL_UNSUPPORTEDAssign the tag to a pass or person instead.
TAG_REQUEST_EXPIREDCreate a new tag request.
TAG_SCANNER_ONLYAssign the tag from a paired scanner.
TAG_SUN_REPLAYTap the tag again for a fresh read.
TAG_UID_RANDOMUse a tag with a fixed ID.
TAG_UNDO_EXPIREDAdd the tag again.
TAG_UNDO_FORBIDDENUndo on that scanner, or have an admin remove the tag.
TAG_UNREADABLEHold the tag steady, or use another tag.
TEMPLATE_ARCHIVEDRestore it with POST /api/v1/templates/{id}/restore, or use another template.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_NOT_RELEASEDRelease the template with POST /api/v1/templates/{id}/releases.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TERMINAL_NOT_FOUNDUse a terminal id from the key's terminals.
TERMINAL_ONLYName one of the key's terminals in the device header.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNDO_SUPERSEDEDUndo the latest scan instead.
UNDO_UNCONFIRMEDCheck the scan's state, then retry once; if it persists, send the requestId to support.
UNLOCK_REQUIREDEnter a staff PIN.
USER_NOT_FOUNDCheck the id with GET /api/v1/users.
VALIDATIONFix each field in issues and resend.
ZONE_ARCHIVEDUse a zone that is not archived.
ZONE_CYCLEChoose a parent outside the zone.
ZONE_DEPTHMove the zone higher in the tree.
ZONE_EVENT_SESSIONUse a zone session, or remove the zones.
ZONE_KEY_TAKENChoose a different key.
ZONE_NAME_TAKENChoose a different name.
ZONE_NOT_FOUNDCheck the zone id.

Scans

POST/api/v1/scan/scans/{scanId}/undo
scans:writeSDK pb.terminal.scans.undo

Path

scanIdstring · max 64Required

Body

idempotencyKeystringRequired
scopeobject
orgIdstring · max 64Required
timeZonestring · max 64Required
setupIdstring · max 64
eventIdstring · max 64
templateIdsstring · max 64[]
approvalobject
pinstring · ^\d{6}$Required
staffIdstring · max 64

Returns

200 ScanOutcome

Errors

CodeStatusFix
ACTOR_CHANGEDCheck the key's scopes and organization with GET /api/v1/api-keys/me, then send the request again.
ADMITS_TOO_MANYShorten admits so it names fewer pass types, then send the request again.
API_KEY_NO_APPROVALApprove on a paired scanner with a staff PIN.
API_KEY_ORG_REQUIREDCall scan endpoints with a key scoped to one organization.
API_KEY_ROUTECall this route from a paired scanner or a signed-in session.
ASSET_NOT_FOUNDCheck the image name or id and that it belongs to this organization.
BLUEPRINT_NOT_SCANNABLECreate a template from the blueprint with POST /api/v1/templates/{id}/use, then set up scanning on it.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
CSRF_ORIGINCall the API server-side with an API key in the Authorization header instead of from a browser page.
DEVICE_REQUIREDName the terminal in the device header on scan calls; open live connections from a paired scanner.
ENROLLMENT_ENDEDStart a new enrollment request.
ENROLLMENT_NOT_FOUNDCheck the enrollment id and start a new request if it expired.
EVENT_ARCHIVEDUse an event that is not archived, or create a new one.
EVENT_IN_USEEnd or change the sessions that use the event, then send the request again.
EVENT_MATCH_INPUTSet the match input to a single-value input from GET /api/v1/templates/{id}/input-schema.
EVENT_NEEDS_CAPACITYSet the event's capacity, then send the request again.
EVENT_NOT_FOUNDCheck the id with GET /api/v1/scan/events.
EVENT_TEMPLATE_NO_CHECK_INPick a template that defines check-in, or add the action to this one.
EVENT_TEMPLATE_RELEASE_REQUIREDApprove a release for the template with POST /api/v1/templates/{id}/releases, then retry.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
GROUP_ENTRY_ONLYUse check in all only on an entry scanner.
IDEMPOTENCY_KEY_REUSEDUse a new key for a new request; resend the identical request to replay.
IMAGE_NOT_FOUNDUpload one with PUT /api/v1/orgs/{id}/branding/{slot}.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
INVALID_CURSORPass the nextCursor from the previous page unchanged, or drop it to start over.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOTE_CAPDelete an old note before adding another.
NOTE_DEVICE_CAPAdd the note from another device or wait until tomorrow.
NOTE_HELDAsk an org admin to release the hold. Adding a note still works.
NOTE_NOT_FOUNDCheck the note id.
NOTE_ROLESign in as Desk staff or a manager with the staff PIN.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
NOT_INSIDEDo nothing; check occupancy before marking out.
OFFLINE_OFFTurn on offline scanning for the session, or scan online.
OFFLINE_TOO_BIGNarrow the session to fewer events or pass types.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
ORG_REQUIREDSend orgId with the request, or use a key scoped to one organization.
PAIRING_INVALIDCreate a new pairing code and enter it again.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
PASS_NOT_FOUNDCheck the id with GET /api/v1/passes and the key's mode.
PHOTO_PASS_INACTIVEUse an active pass.
PHOTO_ROLESign in as Desk staff with the staff PIN.
PIN_GENERATION_FAILEDRetry the request.
PIN_INVALIDEnter the correct PIN; repeated misses lock the entry for a while.
PIN_MANAGER_REQUIREDName a manager in the request.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
ROLE_NOT_ALLOWEDChange the role from the scanner's setup in the admin console.
ROLL_CALL_ENDEDStart a new roll call.
ROLL_CALL_NOT_FOUNDCheck the roll call id.
ROLL_CALL_NO_PLACESTurn on occupancy tracking for the session, then start the roll call.
ROLL_CALL_NO_SESSIONAssign the scanner to a session in the admin console, then start the roll call.
ROLL_CALL_TOO_LARGEMark people out in bulk before starting the roll call.
SAMPLE_TEST_ONLYRequest sample passes from a test-mode scanner.
SCANNER_ADMIN_ROLEUse a browser device for admin sign-in.
SCANNER_ADMIN_SETUP_EXISTSUse the existing admin setup.
SCANNER_ADMIN_USERCreate it signed in as that admin, and leave out another user.
SCANNER_CANNOT_SCANAssign events only to scanning devices.
SCANNER_CHANGEDFetch the scanner and send your change again.
SCANNER_EXPIREDPair the scanner again.
SCANNER_NAME_TAKENChoose a different name.
SCANNER_NOT_FOUNDCheck the scanner id and the key's mode.
SCANNER_NOT_PAIRABLEUse the pairing method for this device type.
SCANNER_NOT_TERMINALCreate a token only for a till scanner.
SCANNER_REPAIRPair the scanner again with a new code.
SCANNER_REVOKEDPair a new scanner.
SCANNER_ROLE_INVALIDChoose a role the device supports.
SCANNER_SETUP_EXISTSUse the existing setup or give the new one another name.
SCANNER_UNASSIGNEDChoose what it accepts, then send the request again.
SCANNER_UNAUTHENTICATEDPair the scanner, then sign in with the staff PIN.
SCANNER_WATCH_INVALIDChoose at least one scanner or session to follow.
SCANNER_WATCH_MODEMove them to the same mode, or choose others.
SCANNER_WATCH_NOT_FOUNDRemove it from the watch list.
SCANNING_DEVICE_CHANGEDFetch the device and send your change again.
SCANNING_DEVICE_NOT_FOUNDCheck the device id.
SCANNING_HOLD_RANGEOpen scanning for at most 24 hours.
SCANNING_HOURS_NONEPause the session instead, or add scanning hours.
SCANNING_SESSION_CHANGEDFetch the session and send your change again.
SCANNING_SESSION_CLOSEDWait for the next opening, or open it for a while.
SCANNING_SESSION_CONFIG_REQUIREDChange the settings on the session, not on the device.
SCANNING_SESSION_COUNTS_UNAVAILABLERetry with backoff.
SCANNING_SESSION_MODEOpen the device in the session's mode.
SCANNING_SESSION_NOT_FOUNDCheck the session id.
SCANNING_SESSION_OPENDo nothing; close it first to change how long it stays open.
SCANNING_SESSION_PAUSEDResume the session, then scan again.
SCANNING_SESSION_SCOPE_INVALIDCorrect the session's scope and settings, then add the device.
SCANNING_SESSION_SETTINGS_INVALIDCorrect the session's settings, then retry.
SCAN_ACCESS_CHANGEDReload the session and send the request again.
SCAN_ADMIN_SETUP_REQUIREDChoose the admin setup in the console, then retry.
SCAN_BODY_INVALIDSend a JSON body with Content-Type: application/json.
SCAN_CONFIG_CHANGEDReload the scanner and scan again.
SCAN_COUNTS_UNAVAILABLERetry with backoff.
SCAN_CREDENTIAL_CHANGEDReconnect the scanner so it picks up the new credential.
SCAN_DISPLAY_PREVIEW_NOT_FOUNDCreate the preview again and use its new id.
SCAN_EVENT_CHANGEDFetch the event with GET /api/v1/scan/events and send your change again.
SCAN_EXPORT_RANGEExport up to 92 days per request.
SCAN_EXPORT_TOO_LARGENarrow the date range or filters and export in parts.
SCAN_HISTORY_UNAVAILABLERetry with backoff.
SCAN_IN_PROGRESSWait a moment and resend the identical request.
SCAN_KEY_REUSEDUse a new unique request key for each action.
SCAN_LIVE_ORIGINOpen the screen on the PassBook site.
SCAN_LOOKUP_DISABLEDTurn on lookup in the scanner's settings.
SCAN_MARK_OUT_INVALIDCheck who is inside, then mark out someone who is.
SCAN_MODE_MISMATCHUse a key and objects of the same mode.
SCAN_NOT_FOUNDCheck the scan id and the scanner's mode.
SCAN_NO_SESSIONAssign the scanner to a session in the admin console.
SCAN_OVERRIDE_FORBIDDENDo not retry; no one can let this person in.
SCAN_OVERRIDE_INVALIDOverride only scans that were refused for an overridable reason.
SCAN_OVERRIDE_NOTE_CLOSEDAdd the note when you override, not afterwards.
SCAN_OVERRIDE_TAKENDo nothing; check the scan's history.
SCAN_PASS_CHANGEDScan the pass again.
SCAN_SCOPE_NOT_ALLOWEDLeave out the scope; a paired scanner uses its own.
SCAN_SCOPE_REQUIREDSend orgId, or use a key scoped to one organization.
SCAN_SEARCH_FORBIDDENSearch by pass id or code, or sign in as an administrator.
SCAN_SETTINGS_INVALIDCorrect the settings named in issues, then retry.
SCAN_SETUP_CONFLICTRemove the template from the other session, or reuse that session.
SCAN_STAFF_CHANGEDFetch the staff list and send the request again.
SCAN_STAFF_CURSORDrop the cursor and list again from the start.
SCAN_STAFF_NOT_FOUNDCheck the id with the scanner's staff list.
SCAN_SUMMARY_SESSION_FORBIDDENSign in with a manager PIN.
SCAN_SURFACE_UNSUPPORTEDUse a screen device for displays.
SCAN_TOO_MANY_MISSESWait a few minutes, then scan again.
SCAN_TOO_MANY_OVERRIDESWait for the next hour, or ask a manager.
SCAN_UNDO_EXPIREDCorrect the record by other means, such as marking the person out.
SCAN_UNDO_FORBIDDENAsk a manager, or the operator who made the scan, to undo it.
SCREEN_ONLYUse a scanner device for scanning.
SCREEN_REQUIREDChoose a screen view for the device in Scanning.
SESSION_OPEN_FORBIDDENSign in with a manager PIN, then open it.
STAFF_NAME_REQUIREDSend staffId with the PIN.
STAFF_NAME_TAKENChoose a different name.
STAFF_REQUIREDSign in with a staff PIN, then retry.
STAFF_SIGN_IN_DISABLEDTurn on staff sign-in in the scanner's settings.
STAFF_SIGN_IN_UNAVAILABLEPair the scanner, then sign in.
TAG_APPROVAL_REQUIREDHave a manager approve it with their PIN.
TAG_ASSIGN_FORBIDDENTurn on assigning in the scanner's settings, or sign in as Desk or above.
TAG_CARD_AMBIGUOUSScan the card again, or assign the tag to a pass directly.
TAG_CHECK_FAILEDUse a different tag.
TAG_HOLDER_CHANGEDFetch the tag and send the request again.
TAG_LIMITRelease unused tags, or ask the platform owner to raise the limit.
TAG_NOT_FOUNDCheck the tag id.
TAG_NO_ACCOUNTAssign the tag to the pass instead.
TAG_PASS_NOT_ACCEPTEDAdd the pass's template or event to the scanner's session.
TAG_POOL_UNSUPPORTEDAssign the tag to a pass or person instead.
TAG_REQUEST_EXPIREDCreate a new tag request.
TAG_SCANNER_ONLYAssign the tag from a paired scanner.
TAG_SUN_REPLAYTap the tag again for a fresh read.
TAG_UID_RANDOMUse a tag with a fixed ID.
TAG_UNDO_EXPIREDAdd the tag again.
TAG_UNDO_FORBIDDENUndo on that scanner, or have an admin remove the tag.
TAG_UNREADABLEHold the tag steady, or use another tag.
TEMPLATE_ARCHIVEDRestore it with POST /api/v1/templates/{id}/restore, or use another template.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_NOT_RELEASEDRelease the template with POST /api/v1/templates/{id}/releases.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TERMINAL_NOT_FOUNDUse a terminal id from the key's terminals.
TERMINAL_ONLYName one of the key's terminals in the device header.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNDO_SUPERSEDEDUndo the latest scan instead.
UNDO_UNCONFIRMEDCheck the scan's state, then retry once; if it persists, send the requestId to support.
UNLOCK_REQUIREDEnter a staff PIN.
USER_NOT_FOUNDCheck the id with GET /api/v1/users.
VALIDATIONFix each field in issues and resend.
ZONE_ARCHIVEDUse a zone that is not archived.
ZONE_CYCLEChoose a parent outside the zone.
ZONE_DEPTHMove the zone higher in the tree.
ZONE_EVENT_SESSIONUse a zone session, or remove the zones.
ZONE_KEY_TAKENChoose a different key.
ZONE_NAME_TAKENChoose a different name.
ZONE_NOT_FOUNDCheck the zone id.