# Scans

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

## List scans (admins) or the scan feed {#list}

`GET /api/v1/scans`

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string · max 512 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 100 |  |  |
| `q` | query | string · max 80 |  |  |
| `scannerId` | query | string · max 64 |  |  |
| `staffId` | query | string · max 64 |  |  |
| `eventId` | query | string · max 64 |  |  |
| `templateId` | query | string · max 64 |  |  |
| `passId` | query | string · max 64 |  |  |
| `outcome` | query | "ok" \| "heads_up" \| "refused" \| "undone" |  |  |
| `reason` | query | "not_found" \| "code_replaced" \| "ambiguous" \| "test_pass" \| "live_pass" \| "not_accepted" \| "wrong_event" \| "removed" \| "voided" \| "expired" \| "no_balance" \| "card_full" \| "managed_elsewhere" \| "limit_reached" \| "zone_not_included" \| "outside_hours" \| "guest_expired" \| "guest_visits_used" \| "suspended" \| "tag_lost" \| "tag_not_allowed" \| "tag_invalid" \| "tag_expired" \| "channel_off" \| "print_replaced" \| "print_voided" \| "already_done" \| "cooldown" \| "not_yet_valid" \| "ended" \| "capacity_full" \| "check_required" \| "needs_approval" \| "stale" \| "in_progress" \| "still_inside" \| "not_inside" \| "choose" |  |  |
| `from` | query | integer \| null · ≥ 0 |  |  |
| `to` | query | integer \| null · ≥ 0 |  |  |
| `createdAfter` | query | integer \| null · ≥ 0 |  |  |
| `createdBefore` | query | integer \| null · ≥ 0 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `ACTOR_CHANGED` |  | Check the key's scopes and organization with GET /api/v1/api-keys/me, then send the request again. |
| `ADMITS_TOO_MANY` |  | Shorten admits so it names fewer pass types, then send the request again. |
| `API_KEY_NO_APPROVAL` |  | Approve on a paired scanner with a staff PIN. |
| `API_KEY_ORG_REQUIRED` |  | Call scan endpoints with a key scoped to one organization. |
| `API_KEY_ROUTE` |  | Call this route from a paired scanner or a signed-in session. |
| `ASSET_NOT_FOUND` |  | Check the image name or id and that it belongs to this organization. |
| `BLUEPRINT_NOT_SCANNABLE` |  | Create a template from the blueprint with POST /api/v1/templates/{id}/use, then set up scanning on it. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `CSRF_ORIGIN` |  | Call the API server-side with an API key in the Authorization header instead of from a browser page. |
| `DEVICE_REQUIRED` |  | Name the terminal in the device header on scan calls; open live connections from a paired scanner. |
| `ENROLLMENT_ENDED` |  | Start a new enrollment request. |
| `ENROLLMENT_NOT_FOUND` |  | Check the enrollment id and start a new request if it expired. |
| `EVENT_ARCHIVED` |  | Use an event that is not archived, or create a new one. |
| `EVENT_IN_USE` |  | End or change the sessions that use the event, then send the request again. |
| `EVENT_MATCH_INPUT` |  | Set the match input to a single-value input from GET /api/v1/templates/{id}/input-schema. |
| `EVENT_NEEDS_CAPACITY` |  | Set the event's capacity, then send the request again. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `EVENT_TEMPLATE_NO_CHECK_IN` |  | Pick a template that defines check-in, or add the action to this one. |
| `EVENT_TEMPLATE_RELEASE_REQUIRED` |  | Approve a release for the template with POST /api/v1/templates/{id}/releases, then retry. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `GROUP_ENTRY_ONLY` |  | Use check in all only on an entry scanner. |
| `IDEMPOTENCY_KEY_REUSED` |  | Use a new key for a new request; resend the identical request to replay. |
| `IMAGE_NOT_FOUND` |  | Upload one with PUT /api/v1/orgs/{id}/branding/{slot}. |
| `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. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOTE_CAP` |  | Delete an old note before adding another. |
| `NOTE_DEVICE_CAP` |  | Add the note from another device or wait until tomorrow. |
| `NOTE_HELD` |  | Ask an org admin to release the hold. Adding a note still works. |
| `NOTE_NOT_FOUND` |  | Check the note id. |
| `NOTE_ROLE` |  | Sign in as Desk staff or a manager with the staff PIN. |
| `NOT_INSIDE` |  | Do nothing; check occupancy before marking out. |
| `OFFLINE_OFF` |  | Turn on offline scanning for the session, or scan online. |
| `OFFLINE_TOO_BIG` |  | Narrow the session to fewer events or pass types. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `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. |
| `PAIRING_INVALID` |  | Create a new pairing code and enter it again. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `PHOTO_PASS_INACTIVE` |  | Use an active pass. |
| `PHOTO_ROLE` |  | Sign in as Desk staff with the staff PIN. |
| `PIN_GENERATION_FAILED` |  | Retry the request. |
| `PIN_INVALID` |  | Enter the correct PIN; repeated misses lock the entry for a while. |
| `PIN_MANAGER_REQUIRED` |  | Name a manager in the request. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `ROLE_NOT_ALLOWED` |  | Change the role from the scanner's setup in the admin console. |
| `ROLL_CALL_ENDED` |  | Start a new roll call. |
| `ROLL_CALL_NOT_FOUND` |  | Check the roll call id. |
| `ROLL_CALL_NO_PLACES` |  | Turn on occupancy tracking for the session, then start the roll call. |
| `ROLL_CALL_NO_SESSION` |  | Assign the scanner to a session in the admin console, then start the roll call. |
| `ROLL_CALL_TOO_LARGE` |  | Mark people out in bulk before starting the roll call. |
| `SAMPLE_TEST_ONLY` |  | Request sample passes from a test-mode scanner. |
| `SCANNER_ADMIN_ROLE` |  | Use a browser device for admin sign-in. |
| `SCANNER_ADMIN_SETUP_EXISTS` |  | Use the existing admin setup. |
| `SCANNER_ADMIN_USER` |  | Create it signed in as that admin, and leave out another user. |
| `SCANNER_CANNOT_SCAN` |  | Assign events only to scanning devices. |
| `SCANNER_CHANGED` |  | Fetch the scanner and send your change again. |
| `SCANNER_EXPIRED` |  | Pair the scanner again. |
| `SCANNER_NAME_TAKEN` |  | Choose a different name. |
| `SCANNER_NOT_FOUND` |  | Check the scanner id and the key's mode. |
| `SCANNER_NOT_PAIRABLE` |  | Use the pairing method for this device type. |
| `SCANNER_NOT_TERMINAL` |  | Create a token only for a till scanner. |
| `SCANNER_REPAIR` |  | Pair the scanner again with a new code. |
| `SCANNER_REVOKED` |  | Pair a new scanner. |
| `SCANNER_ROLE_INVALID` |  | Choose a role the device supports. |
| `SCANNER_SETUP_EXISTS` |  | Use the existing setup or give the new one another name. |
| `SCANNER_UNASSIGNED` |  | Choose what it accepts, then send the request again. |
| `SCANNER_UNAUTHENTICATED` |  | Pair the scanner, then sign in with the staff PIN. |
| `SCANNER_WATCH_INVALID` |  | Choose at least one scanner or session to follow. |
| `SCANNER_WATCH_MODE` |  | Move them to the same mode, or choose others. |
| `SCANNER_WATCH_NOT_FOUND` |  | Remove it from the watch list. |
| `SCANNING_DEVICE_CHANGED` |  | Fetch the device and send your change again. |
| `SCANNING_DEVICE_NOT_FOUND` |  | Check the device id. |
| `SCANNING_HOLD_RANGE` |  | Open scanning for at most 24 hours. |
| `SCANNING_HOURS_NONE` |  | Pause the session instead, or add scanning hours. |
| `SCANNING_SESSION_CHANGED` |  | Fetch the session and send your change again. |
| `SCANNING_SESSION_CLOSED` |  | Wait for the next opening, or open it for a while. |
| `SCANNING_SESSION_CONFIG_REQUIRED` |  | Change the settings on the session, not on the device. |
| `SCANNING_SESSION_COUNTS_UNAVAILABLE` |  | Retry with backoff. |
| `SCANNING_SESSION_MODE` |  | Open the device in the session's mode. |
| `SCANNING_SESSION_NOT_FOUND` |  | Check the session id. |
| `SCANNING_SESSION_OPEN` |  | Do nothing; close it first to change how long it stays open. |
| `SCANNING_SESSION_PAUSED` |  | Resume the session, then scan again. |
| `SCANNING_SESSION_SCOPE_INVALID` |  | Correct the session's scope and settings, then add the device. |
| `SCANNING_SESSION_SETTINGS_INVALID` |  | Correct the session's settings, then retry. |
| `SCAN_ACCESS_CHANGED` |  | Reload the session and send the request again. |
| `SCAN_ADMIN_SETUP_REQUIRED` |  | Choose the admin setup in the console, then retry. |
| `SCAN_BODY_INVALID` |  | Send a JSON body with Content-Type: application/json. |
| `SCAN_CONFIG_CHANGED` |  | Reload the scanner and scan again. |
| `SCAN_COUNTS_UNAVAILABLE` |  | Retry with backoff. |
| `SCAN_CREDENTIAL_CHANGED` |  | Reconnect the scanner so it picks up the new credential. |
| `SCAN_DISPLAY_PREVIEW_NOT_FOUND` |  | Create the preview again and use its new id. |
| `SCAN_EVENT_CHANGED` |  | Fetch the event with GET /api/v1/scan/events and send your change again. |
| `SCAN_EXPORT_RANGE` |  | Export up to 92 days per request. |
| `SCAN_EXPORT_TOO_LARGE` |  | Narrow the date range or filters and export in parts. |
| `SCAN_HISTORY_UNAVAILABLE` |  | Retry with backoff. |
| `SCAN_IN_PROGRESS` |  | Wait a moment and resend the identical request. |
| `SCAN_KEY_REUSED` |  | Use a new unique request key for each action. |
| `SCAN_LIVE_ORIGIN` |  | Open the screen on the PassBook site. |
| `SCAN_LOOKUP_DISABLED` |  | Turn on lookup in the scanner's settings. |
| `SCAN_MARK_OUT_INVALID` |  | Check who is inside, then mark out someone who is. |
| `SCAN_MODE_MISMATCH` |  | Use a key and objects of the same mode. |
| `SCAN_NOT_FOUND` |  | Check the scan id and the scanner's mode. |
| `SCAN_NO_SESSION` |  | Assign the scanner to a session in the admin console. |
| `SCAN_OVERRIDE_FORBIDDEN` |  | Do not retry; no one can let this person in. |
| `SCAN_OVERRIDE_INVALID` |  | Override only scans that were refused for an overridable reason. |
| `SCAN_OVERRIDE_NOTE_CLOSED` |  | Add the note when you override, not afterwards. |
| `SCAN_OVERRIDE_TAKEN` |  | Do nothing; check the scan's history. |
| `SCAN_PASS_CHANGED` |  | Scan the pass again. |
| `SCAN_SCOPE_NOT_ALLOWED` |  | Leave out the scope; a paired scanner uses its own. |
| `SCAN_SCOPE_REQUIRED` |  | Send orgId, or use a key scoped to one organization. |
| `SCAN_SEARCH_FORBIDDEN` |  | Search by pass id or code, or sign in as an administrator. |
| `SCAN_SETTINGS_INVALID` |  | Correct the settings named in issues, then retry. |
| `SCAN_SETUP_CONFLICT` |  | Remove the template from the other session, or reuse that session. |
| `SCAN_STAFF_CHANGED` |  | Fetch the staff list and send the request again. |
| `SCAN_STAFF_CURSOR` |  | Drop the cursor and list again from the start. |
| `SCAN_STAFF_NOT_FOUND` |  | Check the id with the scanner's staff list. |
| `SCAN_SUMMARY_SESSION_FORBIDDEN` |  | Sign in with a manager PIN. |
| `SCAN_SURFACE_UNSUPPORTED` |  | Use a screen device for displays. |
| `SCAN_TOO_MANY_MISSES` |  | Wait a few minutes, then scan again. |
| `SCAN_TOO_MANY_OVERRIDES` |  | Wait for the next hour, or ask a manager. |
| `SCAN_UNDO_EXPIRED` |  | Correct the record by other means, such as marking the person out. |
| `SCAN_UNDO_FORBIDDEN` |  | Ask a manager, or the operator who made the scan, to undo it. |
| `SCREEN_ONLY` |  | Use a scanner device for scanning. |
| `SCREEN_REQUIRED` |  | Choose a screen view for the device in Scanning. |
| `SESSION_OPEN_FORBIDDEN` |  | Sign in with a manager PIN, then open it. |
| `STAFF_NAME_REQUIRED` |  | Send staffId with the PIN. |
| `STAFF_NAME_TAKEN` |  | Choose a different name. |
| `STAFF_REQUIRED` |  | Sign in with a staff PIN, then retry. |
| `STAFF_SIGN_IN_DISABLED` |  | Turn on staff sign-in in the scanner's settings. |
| `STAFF_SIGN_IN_UNAVAILABLE` |  | Pair the scanner, then sign in. |
| `TAG_APPROVAL_REQUIRED` |  | Have a manager approve it with their PIN. |
| `TAG_ASSIGN_FORBIDDEN` |  | Turn on assigning in the scanner's settings, or sign in as Desk or above. |
| `TAG_CARD_AMBIGUOUS` |  | Scan the card again, or assign the tag to a pass directly. |
| `TAG_CHECK_FAILED` |  | Use a different tag. |
| `TAG_HOLDER_CHANGED` |  | Fetch the tag and send the request again. |
| `TAG_LIMIT` |  | Release unused tags, or ask the platform owner to raise the limit. |
| `TAG_NOT_FOUND` |  | Check the tag id. |
| `TAG_NO_ACCOUNT` |  | Assign the tag to the pass instead. |
| `TAG_PASS_NOT_ACCEPTED` |  | Add the pass's template or event to the scanner's session. |
| `TAG_POOL_UNSUPPORTED` |  | Assign the tag to a pass or person instead. |
| `TAG_REQUEST_EXPIRED` |  | Create a new tag request. |
| `TAG_SCANNER_ONLY` |  | Assign the tag from a paired scanner. |
| `TAG_SUN_REPLAY` |  | Tap the tag again for a fresh read. |
| `TAG_UID_RANDOM` |  | Use a tag with a fixed ID. |
| `TAG_UNDO_EXPIRED` |  | Add the tag again. |
| `TAG_UNDO_FORBIDDEN` |  | Undo on that scanner, or have an admin remove the tag. |
| `TAG_UNREADABLE` |  | Hold the tag steady, or use another tag. |
| `TEMPLATE_ARCHIVED` |  | Restore it with POST /api/v1/templates/{id}/restore, or use another template. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_NOT_RELEASED` |  | Release the template with POST /api/v1/templates/{id}/releases. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TERMINAL_NOT_FOUND` |  | Use a terminal id from the key's terminals. |
| `TERMINAL_ONLY` |  | Name one of the key's terminals in the device header. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNDO_SUPERSEDED` |  | Undo the latest scan instead. |
| `UNDO_UNCONFIRMED` |  | Check the scan's state, then retry once; if it persists, send the requestId to support. |
| `UNLOCK_REQUIRED` |  | Enter a staff PIN. |
| `USER_NOT_FOUND` |  | Check the id with GET /api/v1/users. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `ZONE_ARCHIVED` |  | Use a zone that is not archived. |
| `ZONE_CYCLE` |  | Choose a parent outside the zone. |
| `ZONE_DEPTH` |  | Move the zone higher in the tree. |
| `ZONE_EVENT_SESSION` |  | Use a zone session, or remove the zones. |
| `ZONE_KEY_TAKEN` |  | Choose a different key. |
| `ZONE_NAME_TAKEN` |  | Choose a different name. |
| `ZONE_NOT_FOUND` |  | Check the zone id. |

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

## Console only

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

- `GET /api/v1/scans/export`: Export scans as CSV (up to 92 days and 100,000 rows)
- `GET /api/v1/scans/{id}`: Get a scan
- `POST /api/v1/scans/{id}/undo`: Undo a scan (up to 30 days old)
