Kyc verification

Import a customer with a share token

Create a customer from a Sumsub share token.

POST
/api/v2/customers/kyc-share

Creates a customer from a share token generated in your Sumsub account. Verification steps the customer already completed carry over; the customer finishes the rest through the returned kycFlowLink.

Share tokens are single-use. idempotencyKey is required unless dryRun is set; reuse it on retries so they return the same customer. If a retry under a new idempotencyKey finds the customer its first request created, it gets 409 DUPLICATE_CUSTOMER with existingCustomerId. Set dryRun to check a token without using it.

Available only when share-token imports are enabled for your organization. Contact support to enable it.

Authorization

bearerAuth
AuthorizationBearer <token>

Organization API key obtained on Settings > API Keys page in Compose UI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST 'https://compose.finance/api/v2/customers/kyc-share' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Content-Type: application/json' \  -d '{    "shareToken": "SHARE_TOKEN",    "idempotencyKey": "7f3c2b1a-4d5e-4f60-8a9b-0c1d2e3f4a5b"  }'
{
  "dryRun": true,
  "reusable": true,
  "email": "[email protected]",
  "name": "JOHN SMITH",
  "proofOfAddressCountry": "DEU",
  "levelName": "customers-api-basic-ca",
  "donor": "yourcompany.example",
  "resumingCustomerId": "550e8400-e29b-41d4-a716-446655440001"
}
{
  "customerId": "550e8400-e29b-41d4-a716-446655440001",
  "email": "[email protected]",
  "name": "JOHN SMITH",
  "accountType": "individual",
  "kycVerified": false,
  "kycFlowLink": "https://www.auth.compose.finance/en/signup?c={customerId}",
  "reuse": {
    "status": "documents_requested",
    "levelName": "customers-api-basic-ca",
    "steps": {
      "emailVerification": "to_do",
      "identity": "carried",
      "selfie": "carried",
      "proofOfAddress": "carried",
      "questionnaire": "to_do"
    },
    "donor": "yourcompany.example"
  }
}

{
  "error": "idempotencyKey is required unless dryRun is true",
  "code": "VALIDATION_ERROR"
}

{
  "error": "Unauthorized - Invalid or missing API key or session"
}

{
  "error": "Importing with a share token is not available for your organization.",
  "code": "KYC_SHARE_UNAVAILABLE"
}

{
  "error": "A customer with this email already exists",
  "code": "DUPLICATE_CUSTOMER",
  "existingCustomerId": "550e8400-e29b-41d4-a716-446655440001"
}

{
  "error": "Content-Type must be application/json",
  "code": "VALIDATION_ERROR"
}
{
  "error": "Internal server error"
}

{
  "error": "This import isn't finished yet. Retry with the same idempotencyKey; do not generate a new share token.",
  "code": "TRANSIENT_ERROR"
}

Update customer developer fees PATCH

Updates the developer fee configuration for the customer. These fees are deducted from customer deposits before USDC is sent to their wallet. **Fee Types** - `developerSpreadFeeBps`: Spread fee in basis points (0-2500, max 25%). Applied to the USDC amount. **Fee Calculation** ``` spreadFee = amount × spreadFeeBps / 10000 customerReceives = amount - spreadFee ``` **Example:** 1000 USDC deposit with 1% spread (100 bps) → customer receives 990 USDC

Get customer verified address GET

Returns the address on file for a customer. For individual customers, this is extracted from KYC verification data (proof of address). For corporate customers, this is the stored business address. This address is automatically used when creating a first-party withdrawal bank without providing an address.