ReferenceConnections

Connections

15 operations. Send Authorization: Bearer $PASSBOOK_KEY. Markdown

GET/api/v1/connections
connections:readSDK pb.connections.list

Query

health"unknown" | "healthy" | "degraded" | "failing" | "paused" | "disabled"
qstring · max 200
cursorstring
limitinteger · ≥ 1 · ≤ 200

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
POST/api/v1/connections
connections: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

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
GET/api/v1/connections/summary
connections:readSDK pb.connections.retrieveSummary

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
GET/api/v1/connections/{id}
connections:readSDK pb.connections.retrieve

Path

idstring · max 64Required

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry 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

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
DEL/api/v1/connections/{id}
connections:writeSDK pb.connections.delete

Path

idstring · max 64Required

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
POST/api/v1/connections/test-config
connections:writeSDK pb.connections.testConfig

Body

orgIdstring · max 64Required
connectorTypestring · max 64Required
configobjectRequired
secretsobject

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
POST/api/v1/connections/{id}/test
connections:writeSDK pb.connections.test

Path

idstring · max 64Required

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
POST/api/v1/connections/{id}/sync
connections:writeSDK pb.connections.sync

Path

idstring · max 64Required

Returns

202

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
POST/api/v1/connections/{id}/webhook-secret
connections:writeSDK pb.connections.rotateWebhookSecret

Path

idstring · max 64Required

Query

overlapSecondsnumber | null

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
DEL/api/v1/connections/{id}/webhook-secret/previous
connections:writeSDK pb.connections.revokePreviousWebhookSecret

Path

idstring · max 64Required

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.

Runs

GET/api/v1/connections/{id}/runs
connections:readSDK pb.connections.runs.list

Path

idstring · max 64Required

Query

cursorstring · max 512
limitinteger · ≥ 1 · ≤ 200

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.

Webhook Failures

GET/api/v1/connections/{id}/webhook-failures
connections:readSDK pb.connections.webhookFailures.list

Path

idstring · max 64Required

Query

cursorstring · max 512

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
POST/api/v1/connections/{id}/webhook-failures/{retentionId}/replay
connections:writeSDK pb.connections.webhookFailures.replay

Path

idstring · max 64Required
retentionIdstring · max 64Required

Returns

202

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.
POST/api/v1/connections/{id}/webhook-failures/{retentionId}/resolve
connections:writeSDK pb.connections.webhookFailures.resolve

Path

idstring · max 64Required
retentionIdstring · max 64Required

Returns

200

Errors

CodeStatusFix
CONNECTION_CONFLICTFetch it with GET /api/v1/connections/{id} and send the change again.
CONNECTION_DISABLEDEnable it with PATCH /api/v1/connections/{id}, then send the request again.
CONNECTION_NOT_FOUNDCheck the id with GET /api/v1/connections.
CONNECTOR_NOT_FOUNDList valid types with GET /api/v1/connectors.
CONNECTOR_UNKNOWNSet type to a value from GET /api/v1/connectors.
CREDENTIAL_REF_KEYSET_UNAVAILABLERetry with backoff; if it persists, send the requestId to support.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
HOLDER_EMAIL_INVALIDCorrect the email in the source system, then sync the connection again.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
MODE_UNSUPPORTEDCreate the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_INACTIVEReactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
PASS_CONFLICTFetch the pass with GET /api/v1/passes/{id} and send the request again.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
TEMPLATE_NOT_FOUNDCheck the id with GET /api/v1/templates and the key's mode.
TEMPLATE_RELEASE_CONFLICTSend the request again to use the current release.
TEMPLATE_RELEASE_REQUIREDApprove a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
UNSAFE_URLUse a public https URL.
VALIDATIONFix each field in issues and resend.
WEBHOOK_ALREADY_FINISHEDDo nothing; check its status with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_CONTEXT_CONFLICTResend the event from the source system.
WEBHOOK_DISPATCH_INCOMPLETERetry with backoff.
WEBHOOK_EFFECT_UNCERTAINResolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass.
WEBHOOK_ENQUEUE_FAILEDRetry with backoff.
WEBHOOK_ITEM_BUSYRetry with backoff.
WEBHOOK_ITEM_PENDINGRetry with backoff.
WEBHOOK_NOTHING_TO_RESOLVEDo nothing; list failures with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_NOT_FOUNDCheck the retentionId with GET /api/v1/connections/{id}/webhook-failures.
WEBHOOK_PAYLOADSend the body in the format the connector documents.
WEBHOOK_PAYLOAD_MISSINGRetry with backoff; if it persists, resend the event from the source.
WEBHOOK_REFERENCE_MODERetry with backoff.
WEBHOOK_REFERENCE_MODE_CHANGEDResend the event from the source system.
WEBHOOK_RESOLVE_CONFLICTList failures again and resolve once more.
WEBHOOK_RETENTION_FAILEDRetry with backoff.
WEBHOOK_RETENTION_UNAVAILABLERetry with backoff.
WEBHOOK_SIGNATURESign the body with the connection's current webhook secret.
WEBHOOK_SNAPSHOT_UNAVAILABLEResend the event from the source system instead of replaying.
WEBHOOK_STALE_CONTEXTResend the event from the source system.
WEBHOOK_STILL_PENDINGWait for it to run before resolving it.
WEBHOOK_UNAVAILABLERetry the webhook.
WEBHOOK_WORK_CHANGEDRetry with backoff.