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.
Attach supporting files to an onboarding application (such as identity documents, certificates, or proof of address), then list, download, or delete them while the application is still in a mutable state.

​
Prerequisites

Before you begin, ensure that you’ve:
  • Obtained an API key for the End User Onboarding API from the Circle Mint Console.
  • Confirmed your application is in DRAFT or PENDING_CUSTOMER_INFORMATION status.
  • Identified which datumName fields need files (from the schema).

​
Steps

​
Step 1. Upload a document

Upload a file and link it to a field in the application: 
curl --request POST \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/documents \
  --header "Authorization: Bearer ${YOUR_API_KEY}" \
  --header 'X-Idempotency-Key: ${IDEMPOTENCY_KEY}' \
  --form 'fileContent=@passport.pdf' \
  --form 'fileName=passport.pdf' \
  --form 'datumName=authorizedRepGovernmentId' \
  --form 'issuedCountry=US' \
  --form 'documentType=passport'

​
Required fields

FieldDescription
fileContentBinary file content
fileNameFile name with extension (for example, passport.pdf)
datumNameSchema field name this file satisfies (for example, authorizedRepGovernmentId)

​
Conditionally required fields

FieldDescription
refIdUUID of the entity this file belongs to. Required for array sections.
issuedCountryISO 3166-1 alpha-2 country code. Required for identity documents.
documentTypeForm of identity document being uploaded. Required when the schema field includes an x-documentTypes extension. Standard government ID fields accept passport, usdl (US driver’s license), or usid (US state ID). Notarized government ID fields accept idNotarization.
To find which documentType values are accepted for a given field, retrieve the application schema (GET /v1/onboarding/partner/applications/{applicationId}/schema) and inspect the x-documentTypes array on the target field. Fields without x-documentTypes do not require this parameter.
Example response: 
{
  "data": {
    "documentId": "550e8400-e29b-41d4-a716-446655440002"
  }
}
Uploading to a submitted application returns a 409 error. The application must be in DRAFT or PENDING_CUSTOMER_INFORMATION.

​
Step 2. List all documents

List all files for an application: 
curl --request GET \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/documents \
  --header "Authorization: Bearer ${YOUR_API_KEY}"
Example response: 
{
  "data": {
    "documents": [
      {
        "documentId": "550e8400-e29b-41d4-a716-446655440002",
        "fileName": "passport.pdf",
        "datumName": "passport_document",
        "uploadedAt": "2026-03-25T14:30:00Z"
      }
    ]
  }
}

​
Step 3. Download a document

Download a file you uploaded: 
curl --request GET \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/documents/${DOCUMENT_ID} \
  --header "Authorization: Bearer ${YOUR_API_KEY}" \
  --output document.pdf
The response body is binary data with a Content-Type: application/octet-stream header.

​
Step 4. Delete a document

Delete a document that is no longer needed: 
curl --request DELETE \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/documents/${DOCUMENT_ID} \
  --header "Authorization: Bearer ${YOUR_API_KEY}"
A successful deletion returns 204 No Content.
You can only delete documents while the application is in DRAFT or PENDING_CUSTOMER_INFORMATION status. Deleting a document from a submitted application returns a 409 error.

​
See also