Skip to main content
The End User Onboarding API base URL is https://api-sandbox.circle.com for sandbox and https://api.circle.com for production. All requests require a Bearer token obtained via Circle key exchange in the Authorization header. All POST requests require an X-Idempotency-Key header with a client-generated UUID v4.
Submit a completed application for compliance review and track its progress through approval. After submission, monitor status changes through webhooks or polling, and list applications by status as needed.

​
Prerequisites

Before you begin, ensure that you’ve:
  • Obtained an API key for the End User Onboarding API from the CPN Console.
  • Completed all application sections (each has complete status).
  • Uploaded all required documents. See Upload documents.

​
Steps

​
Step 1. Discover required certifications (GUI flows only)

Some applications require your end user to actively review and agree to one or more compliance certifications before you submit on their behalf. Whether you need to perform this step depends on how your integration is built:
  • API-only integrations: If you control the submission flow programmatically and your end users never see the terms directly (for example, you have a separate agreement process in your own product), you can skip this step and omit certificationIds from the submit request.
  • GUI / end-user flows: If you are building a UI where end users read and explicitly agree to Circle’s certification terms, you must fetch the active certifications for the application, present them to the user, and pass the agreed certification IDs in the submit request.
To retrieve the active certifications for an application: 
curl --request GET \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/certifications \
  --header "Authorization: Bearer ${YOUR_API_KEY}"
Example response: 
{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "content": "I certify that ..."
    }
  ]
}
Display each certification’s content (HTML) to your end user and collect their acknowledgment. Then pass every id in the certificationIds array when you submit (see step 2 below). If the set of IDs you provide does not exactly match the application’s active certifications, the API returns a 422 error with details about which IDs are missing or unknown.

​
Step 2. Submit the application

Submit an application when all sections have complete status: 
curl --request POST \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/submit \
  --header "Authorization: Bearer ${YOUR_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: ${IDEMPOTENCY_KEY}' \
  --data '{
    "endUserIpAddress": "203.0.113.42",
    "endUserAgreesToTermsOfService": true,
    "certificationIds": [
      "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
    ]
  }'
For the full request schema, see the Submit application API reference. The application moves from DRAFT to SUBMITTED. If any sections are incomplete, the server returns a 409 error. Example response: 
{
  "data": {
    "applicationId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "SUBMITTED"
  }
}

​
Step 3. Track application status

Monitor your application’s progress by polling, or use webhook notifications for real-time updates (see Webhook endpoints to subscribe): 
curl --request GET \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID} \
  --header "Authorization: Bearer ${YOUR_API_KEY}"
See Application states for a full list of statuses and transitions, and Webhook notifications for the event types and payloads delivered to your subscription.

​
Step 4. List all applications

List applications for your partner account. You can filter by status: 
curl --request GET \
  --url 'https://api-sandbox.circle.com/v1/onboarding/partner/applications?status=PENDING_CUSTOMER_INFORMATION&limit=25' \
  --header "Authorization: Bearer ${YOUR_API_KEY}"
The response supports pagination. Use starting_after with the applicationId of the last item to fetch the next page. If the application moves to PENDING_CUSTOMER_INFORMATION, the compliance team has issued one or more Requests for Information (RFIs). See Handle requests for information for the full RFI workflow.

​
See also