How-to: Upload documents

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

Field	Description
`fileContent`	Binary file content
`fileName`	File name with extension (for example, `passport.pdf`)
`datumName`	Schema field name this file satisfies (for example, `authorizedRepGovernmentId`)

Conditionally required fields

Field	Description
`refId`	UUID of the entity this file belongs to. Required for array sections.
`issuedCountry`	ISO 3166-1 alpha-2 country code. Required for identity documents.
`documentType`	Form of identity document being uploaded. Required when the schema field includes an `x-documentTypes` extension. Standard government ID fields accept `passport`, `usdl` (United States driver’s license), or `usid` (United States 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.

Uploads for array entities need one more step after this request completes.

Uploading a document for an array entity returns a documentId, but it does not complete the entity’s document field by itself. Save the array section again with the returned documentId in the relevant field, including the same refId so the API updates the existing entity instead of creating a duplicate. See Array sections for an example.

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.

Mint

StableFX

Digital Asset Accounts

End User Onboarding

How-to: Upload documents

Prerequisites

Steps

Step 1. Upload a document

Required fields

Conditionally required fields

Step 2. List all documents

Step 3. Download a document

Step 4. Delete a document

See also

​Prerequisites

​Steps

​Step 1. Upload a document

​Required fields

​Conditionally required fields

​Step 2. List all documents

​Step 3. Download a document

​Step 4. Delete a document

​See also

Prerequisites

Steps

Step 1. Upload a document

Required fields

Conditionally required fields

Step 2. List all documents

Step 3. Download a document

Step 4. Delete a document

See also