ReferencePasses
Holders
8 operations. Send Authorization: Bearer $PASSBOOK_KEY. Markdown
GET
/api/v1/holderspasses:readSDK pb.holders.list
Query
emailstring · max 254
state"unassigned" | "waiting" | "owned"
cursorstring
limitinteger · ≥ 1 · ≤ 200
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BLOCK_NOT_FOUND | Check the block id and send the request again. | |
| EMAIL_INVALID | Send a valid address in the email field. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| HOLDER_CHANGED | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| HOLDER_OWNED | Use POST /api/v1/holders/reassign to move it. | |
| HOLDER_TRANSFER_PENDING | Wait for the transfer to finish, then send the request again. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| 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. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
GET
/api/v1/holders/{id}passes:readSDK pb.holders.retrieve
Path
idstring · max 64Required
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BLOCK_NOT_FOUND | Check the block id and send the request again. | |
| EMAIL_INVALID | Send a valid address in the email field. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| HOLDER_CHANGED | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| HOLDER_OWNED | Use POST /api/v1/holders/reassign to move it. | |
| HOLDER_TRANSFER_PENDING | Wait for the transfer to finish, then send the request again. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| 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. | |
| 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. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/holders/assignholders:writeSDK pb.holders.assign
Body
passIdstring · max 64Required
emailstring · max 254Required
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BLOCK_NOT_FOUND | Check the block id and send the request again. | |
| EMAIL_INVALID | Send a valid address in the email field. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| HOLDER_CHANGED | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| HOLDER_OWNED | Use POST /api/v1/holders/reassign to move it. | |
| HOLDER_TRANSFER_PENDING | Wait for the transfer to finish, then send the request again. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| 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. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/holders/assign-bulkholders:writeSDK pb.holders.bulkAssign
Body
itemsobject[]Required
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BLOCK_NOT_FOUND | Check the block id and send the request again. | |
| EMAIL_INVALID | Send a valid address in the email field. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| HOLDER_CHANGED | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| HOLDER_OWNED | Use POST /api/v1/holders/reassign to move it. | |
| HOLDER_TRANSFER_PENDING | Wait for the transfer to finish, then send the request again. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| 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. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/holders/reassignholders:writeSDK pb.holders.reassign
Body
passIdstring · max 64Required
emailstring | null · max 254Required
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BLOCK_NOT_FOUND | Check the block id and send the request again. | |
| EMAIL_INVALID | Send a valid address in the email field. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| HOLDER_CHANGED | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| HOLDER_OWNED | Use POST /api/v1/holders/reassign to move it. | |
| HOLDER_TRANSFER_PENDING | Wait for the transfer to finish, then send the request again. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| 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. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/holders/unassignholders:writeSDK pb.holders.unassign
Body
passIdstring · max 64Required
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BLOCK_NOT_FOUND | Check the block id and send the request again. | |
| EMAIL_INVALID | Send a valid address in the email field. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| HOLDER_CHANGED | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| HOLDER_OWNED | Use POST /api/v1/holders/reassign to move it. | |
| HOLDER_TRANSFER_PENDING | Wait for the transfer to finish, then send the request again. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| 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. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/holders/clear-blockholders:writeSDK pb.holders.clearBlock
Body
passIdstring · max 64Required
userIdstring · max 64Required
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BLOCK_NOT_FOUND | Check the block id and send the request again. | |
| EMAIL_INVALID | Send a valid address in the email field. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| HOLDER_CHANGED | Fetch the pass with GET /api/v1/passes/{id} and send the request again. | |
| HOLDER_OWNED | Use POST /api/v1/holders/reassign to move it. | |
| HOLDER_TRANSFER_PENDING | Wait for the transfer to finish, then send the request again. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| 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. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |
POST
/api/v1/offboardpasses:writeSDK pb.holders.offboard
Body
holderEmailstring · max 254
externalIdstring · max 200
passes"void" | "remove"
tags"spare" | "lost"
dryRunboolean
Returns
200
Errors
| Code | Status | Fix |
|---|---|---|
| BRAND_IMAGE_NOT_FOUND | Upload the image with PUT /api/v1/orgs/{id}/branding/{slot} and use the URL it returns. | |
| BRAND_MARK_NOT_ALLOWED | Remove the setting, or ask the platform owner to enable it for the organization. | |
| ENTITLEMENTS_CHANGED | Fetch them with GET /api/v1/orgs/{id}/entitlements and send your change again. | |
| FORBIDDEN | Use a key with the scope the operation lists, or ask an org admin. | |
| IDENTITY_NOT_FOUND | Check the id with GET /api/v1/identities. | |
| IMAGE_BYTES | Compress the image and upload it again. | |
| IMAGE_INVALID | Export a standard PNG and upload it again. | |
| IMAGE_NOT_FOUND | Upload one with PUT /api/v1/orgs/{id}/branding/{slot}. | |
| IMAGE_SCALE | Resize so the @2x image is two thirds of the @3x, then upload both. | |
| IMAGE_SIZE | Resize to the size named in issues and upload it again. | |
| INVALID_API_KEY | Create a new key in the console and update PASSBOOK_KEY. | |
| INVITATION_INVALID | Ask an organization admin to send a new invitation with POST /api/v1/orgs/{id}/invitations. | |
| INVITATION_PENDING | Revoke it to send a new one. | |
| LAST_ORG_ADMIN | Make someone else an org admin first. | |
| MEMBERSHIP_CONFLICT | Fetch it with GET /api/v1/orgs/{id}/memberships and send the change again. | |
| MISSING_SCOPE | Create a key with the scope the operation lists under security. | |
| ORG_CONFLICT | Fetch it with GET /api/v1/orgs/{id} and send the change again. | |
| ORG_NOT_FOUND | Check orgId with GET /api/v1/orgs. | |
| ORG_PERSONAL_SINGLE_MEMBER | Use a regular organization to work with others. | |
| ORG_SLUG_RESERVED | Choose a different slug. | |
| ORG_SLUG_TAKEN | Choose a different slug. | |
| ORG_STATUS_ALONE | Send the status change in its own request, then the other edits. | |
| RATE_LIMITED | Wait for Retry-After seconds, then retry. Back off on repeats. | |
| SETTINGS_CHANGED | Fetch them with GET /api/v1/settings and send your change again. | |
| UNAUTHENTICATED | Send Authorization: Bearer $PASSBOOK_KEY. | |
| VALIDATION | Fix each field in issues and resend. |