ReferenceConnections
Connections
15 operations. Send Authorization: Bearer $PASSBOOK_KEY. Markdown
GET
/api/v1/connectionsconnections:readSDK pb.connections.list
Query
health"unknown" | "healthy" | "degraded" | "failing" | "paused" | "disabled"
qstring · max 200
cursorstring
limitinteger · ≥ 1 · ≤ 200
Returns
200
Errors
| 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. |
POST
/api/v1/connectionsconnections:writeSDK pb.connections.create
Body
orgIdstring · max 64Required
connectorTypestringRequired
namestring · max 120Required
configobjectRequired
secretsobject
webhookSecretstring · max 256
mappingobject
defaultTemplateIdstring · max 64
holderEmailFieldstring · max 200
autoCreateboolean
autoEmailboolean
onMissing"keep" | "flag" | "void"
voidWhenobject[]
mode"poll" | "webhook" | "hybrid" | "manual" | "snapshot"
intervalSecondsinteger · ≥ 60
maxConcurrencyinteger · ≥ 1 · ≤ 20
requestsPerMinuteinteger · ≥ 1 · ≤ 6000
Returns
201
Errors
| 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. |
GET
/api/v1/connections/summaryconnections:readSDK pb.connections.retrieveSummary
Returns
200
Errors
| 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. |
GET
/api/v1/connections/{id}connections:readSDK pb.connections.retrieve
Path
idstring · max 64Required
Returns
200
Errors
| 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. |
PATCH
/api/v1/connections/{id}connections:writeSDK pb.connections.update
Path
idstring · max 64Required
Body
namestring · max 120
configobject
secretsobject
webhookSecretstring · max 256
mappingobject
defaultTemplateIdstring · max 64
holderEmailFieldstring · max 200
autoCreateboolean
autoEmailboolean
onMissing"keep" | "flag" | "void"
voidWhenobject[]
mode"poll" | "webhook" | "hybrid" | "manual" | "snapshot"
intervalSecondsinteger · ≥ 60
maxConcurrencyinteger | null · ≥ 1 · ≤ 20
requestsPerMinuteinteger | null · ≥ 1 · ≤ 6000
enabledboolean
overlapSeconds0 | 3600 | 86400 | 604800
Returns
200
Errors
| 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. |
DEL
/api/v1/connections/{id}connections:writeSDK pb.connections.delete
Path
idstring · max 64Required
Returns
200
Errors
| 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. |
POST
/api/v1/connections/test-configconnections:writeSDK pb.connections.testConfig
Body
orgIdstring · max 64Required
connectorTypestring · max 64Required
configobjectRequired
secretsobject
Returns
200
Errors
| 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. |
POST
/api/v1/connections/{id}/testconnections:writeSDK pb.connections.test
Path
idstring · max 64Required
Returns
200
Errors
| 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. |
POST
/api/v1/connections/{id}/syncconnections:writeSDK pb.connections.sync
Path
idstring · max 64Required
Returns
202
Errors
| 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. |
POST
/api/v1/connections/{id}/webhook-secretconnections:writeSDK pb.connections.rotateWebhookSecret
Path
idstring · max 64Required
Query
overlapSecondsnumber | null
Returns
200
Errors
| 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. |
DEL
/api/v1/connections/{id}/webhook-secret/previousconnections:writeSDK pb.connections.revokePreviousWebhookSecret
Path
idstring · max 64Required
Returns
200
Errors
| 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. |
Runs
GET
/api/v1/connections/{id}/runsconnections:readSDK pb.connections.runs.list
Path
idstring · max 64Required
Query
cursorstring · max 512
limitinteger · ≥ 1 · ≤ 200
Returns
200
Errors
| 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. |
Webhook Failures
GET
/api/v1/connections/{id}/webhook-failuresconnections:readSDK pb.connections.webhookFailures.list
Path
idstring · max 64Required
Query
cursorstring · max 512
Returns
200
Errors
| 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. |
POST
/api/v1/connections/{id}/webhook-failures/{retentionId}/replayconnections:writeSDK pb.connections.webhookFailures.replay
Path
idstring · max 64Required
retentionIdstring · max 64Required
Returns
202
Errors
| 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. |
POST
/api/v1/connections/{id}/webhook-failures/{retentionId}/resolveconnections:writeSDK pb.connections.webhookFailures.resolve
Path
idstring · max 64Required
retentionIdstring · max 64Required
Returns
200
Errors
| 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. |