How-to: Handle requests for information

Resolve compliance team requests so your application can proceed to approval. List RFI bundles to see what’s needed, update the requested fields or documents, respond with comments, and resubmit the application.

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.

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 PENDING_CUSTOMER_INFORMATION status. See Application types and states for the full lifecycle.

In the sandbox, Know Your Business (KYB) applications auto-approve on submission. To get an application into review so an RFI can be issued, submit it with a reserved business name. See Magic numbers for testing.

Steps

Step 1. List RFI bundles

When an application moves to PENDING_CUSTOMER_INFORMATION, the pendingRfis array on the application response contains the bundle IDs. List all bundles:

curl --request GET \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/rfis \
  --header "Authorization: Bearer ${YOUR_API_KEY}"

Example response:

{
  "data": {
    "bundles": [
      {
        "bundleId": "660e8400-e29b-41d4-a716-446655440010",
        "status": "PUBLISHED",
        "createdAt": "2026-03-26T10:00:00Z",
        "rfis": [
          {
            "rfiId": "770e8400-e29b-41d4-a716-446655440011",
            "section": "beneficialOwnerPersons",
            "field": "passport_document",
            "type": "COLLECT_DOCUMENT",
            "status": "PENDING",
            "systemComment": "Document is illegible. Please upload a clearer copy.",
            "refId": "3de289ef-7947-457d-bbcd-a4fc8dc3b1aa",
            "createdAt": "2026-03-26T10:00:00Z"
          },
          {
            "rfiId": "880e8400-e29b-41d4-a716-446655440012",
            "section": "businessRegistrationDetails",
            "field": "businessWebsite",
            "type": "UPDATE_FIELD",
            "status": "PENDING",
            "systemComment": "Please provide your company website.",
            "refId": null,
            "createdAt": "2026-03-26T10:01:00Z"
          }
        ]
      }
    ]
  }
}

Each RFI identifies the section and field that needs attention. The systemComment explains what the compliance team requires.

Array sections and refId: Some sections, such as beneficialOwnerPersons, beneficialOwnerEntity, or trustRelatedPersons, can contain multiple entries (for example, multiple beneficial owners). When an RFI targets a field in one of these sections, the response includes a refId identifying which specific entity the RFI is for. refId is null for RFIs on single-instance sections (such as businessRegistrationDetails) and for note-type RFIs. Use refId when responding. See Step 3.

Step 2. View RFI detail and comments

Retrieve the full detail for a specific RFI, including any prior comments:

curl --request GET \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/rfis/${RFI_ID} \
  --header "Authorization: Bearer ${YOUR_API_KEY}"

Step 3. Update the requested data

For RFIs with type UPDATE_FIELD or NEW_FIELD, submit the corrected field data directly to the RFI. The request body shape depends on whether the RFI targets a single-instance section or an array section. Single-instance section (refId is null): submit a flat JSON object with the field name as the key:

curl --request PATCH \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/rfis/${RFI_ID} \
  --header "Authorization: Bearer ${YOUR_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "businessWebsite": "https://example.com"
  }'

Array section (refId is present): submit a single-element JSON array containing the refId from the RFI response alongside the updated field. This tells the API exactly which entity to update:

curl --request PATCH \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/rfis/${RFI_ID} \
  --header "Authorization: Bearer ${YOUR_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '[{
    "refId": "3de289ef-7947-457d-bbcd-a4fc8dc3b1aa",
    "trustRelatedPersonLastName": "Smith"
  }]'

The refId in the body must match the refId on the RFI. The API rejects mismatches. Replace the field name with the field value from the RFI. The API validates the submitted value against the application schema and marks the RFI as responded. For RFIs with type COLLECT_DOCUMENT, re-upload the document instead. When the RFI has a refId, include it in the document upload request to associate the file with the correct entity. See Upload documents for the upload workflow.

Step 4. Respond with a comment

Add a comment to an RFI to communicate with the compliance team:

curl --request POST \
  --url https://api-sandbox.circle.com/v1/onboarding/partner/applications/${APPLICATION_ID}/rfis/${RFI_ID}/comments \
  --header "Authorization: Bearer ${YOUR_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: ${IDEMPOTENCY_KEY}' \
  --data '{
    "content": "Updated the field as requested."
  }'

Step 5. Resubmit the application

After you address all open RFIs, resubmit the application so it moves back to SUBMITTED for another round of review:

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
  }'

This is the same endpoint used during initial submission. For details on optional fields such as certificationIds, see Submit and track applications.

Mint

StableFX

Digital Asset Accounts

End User Onboarding

How-to: Handle requests for information

Prerequisites

Steps

Step 1. List RFI bundles

Step 2. View RFI detail and comments

Step 3. Update the requested data

Step 4. Respond with a comment

Step 5. Resubmit the application

See also

​Prerequisites

​Steps

​Step 1. List RFI bundles

​Step 2. View RFI detail and comments

​Step 3. Update the requested data

​Step 4. Respond with a comment

​Step 5. Resubmit the application

​See also

Prerequisites

Steps

Step 1. List RFI bundles

Step 2. View RFI detail and comments

Step 3. Update the requested data

Step 4. Respond with a comment

Step 5. Resubmit the application

See also