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 Circle Console.
  • Completed all application sections (each has complete status).
  • Uploaded all required documents. See Upload documents.
  • For Stablecoin KYB, collected device risk signals in the browser. See Collect device risk signals.

​
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:
Example response:
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). If the set of IDs you provide doesn’t 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

For Stablecoin KYB, collect device risk signals in the browser first. See Collect device risk signals. Then submit when all sections have complete status:
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 181101 (422). If the application is in the wrong state, the server returns 181104 (409). For Stablecoin KYB device-check outcomes (181110, 181111, 181108), see Collect device risk signals. Example response:

​
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):
See Application types and 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:
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