Skip to main content
Partner Onboarding delivers asynchronous application lifecycle events as webhook notifications so you can drive your integration with real-time updates instead of polling GET /v1/onboarding/partner/applications/{id}. Notifications are delivered as Amazon SNS messages on the v1 notification system. To register a webhook endpoint, create a subscription for partner onboarding notifications in the Circle Mint Console under Developer > Subscriptions, then see Set up a webhook endpoint.

​
When notifications fire

Webhooks are sent only for asynchronous outcomes that you cannot observe from the response to your own API call. Synchronous transitions you trigger directly—such as DRAFT → SUBMITTED from a submit request—are not delivered as webhooks because the result is already in the HTTP response.
Notification typeFires when the application transitions toFrom
onboarding_application_rfi_requestedPENDING_CUSTOMER_INFORMATIONIN_REVIEW
onboarding_application_approvedAPPROVEDIN_REVIEW
onboarding_application_deniedDENIEDIN_REVIEW
onboarding_application_cancelledCANCELLEDDRAFT
onboarding_application_rfi_requested signals that the compliance team has issued one or more Requests for Information (RFIs). See Handle requests for information for the RFI workflow, and Application states for the full lifecycle.

​
Payload

Every partner onboarding notification carries the same flat payload.
FieldTypeDescription
clientIdUUIDIdentifier of the partner the application belongs to. Used to route the notification to your endpoint.
notificationTypestringThe event type, for example onboarding_application_rfi_requested.
versionnumberNotification system version. Always 1.
applicationIdUUIDIdentifier of the affected onboarding application.
statusstringThe application’s new status.
previousStatusstringThe application’s status immediately before this transition.
status and previousStatus use the same values as Application states. Internal review sub-states are collapsed to IN_REVIEW, so a transition out of review reports previousStatus as IN_REVIEW.

​
Event types

​
onboarding_application_rfi_requested

The compliance team issued one or more RFIs and the application moved to PENDING_CUSTOMER_INFORMATION. Fetch the open RFIs with List RFIs (the application’s pendingRfis array also carries the bundle IDs), respond to each, then resubmit. 
{
  "clientId": "880e8400-e29b-41d4-a716-446655440099",
  "notificationType": "onboarding_application_rfi_requested",
  "version": 1,
  "applicationId": "6bb28d72-8a8e-4afc-9086-66f89af954eb",
  "status": "PENDING_CUSTOMER_INFORMATION",
  "previousStatus": "IN_REVIEW"
}

​
onboarding_application_approved

Compliance review completed and the application was approved. This is a terminal state. 
{
  "clientId": "880e8400-e29b-41d4-a716-446655440099",
  "notificationType": "onboarding_application_approved",
  "version": 1,
  "applicationId": "6bb28d72-8a8e-4afc-9086-66f89af954eb",
  "status": "APPROVED",
  "previousStatus": "IN_REVIEW"
}

​
onboarding_application_denied

Compliance review completed and the application was denied. This is a terminal state. 
{
  "clientId": "880e8400-e29b-41d4-a716-446655440099",
  "notificationType": "onboarding_application_denied",
  "version": 1,
  "applicationId": "6bb28d72-8a8e-4afc-9086-66f89af954eb",
  "status": "DENIED",
  "previousStatus": "IN_REVIEW"
}

​
onboarding_application_cancelled

The application was cancelled. Cancellation is only reachable from DRAFT, so previousStatus is always DRAFT. This is a terminal state. 
{
  "clientId": "880e8400-e29b-41d4-a716-446655440099",
  "notificationType": "onboarding_application_cancelled",
  "version": 1,
  "applicationId": "6bb28d72-8a8e-4afc-9086-66f89af954eb",
  "status": "CANCELLED",
  "previousStatus": "DRAFT"
}

​
See also