# Connectors

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

## List connector types {#list}

`GET /api/v1/connectors`

Scopes: `connections:read`. SDK name: `pb.connectors.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string · max 512 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection 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. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `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. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Get a connector type {#retrieve}

`GET /api/v1/connectors/{type}`

Scopes: `connections:read`. SDK name: `pb.connectors.retrieve`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | path | string | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection 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. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `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. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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