Kyc verification

Submit customer KYC

Manually submit KYC documents for verification review.

POST
/api/v2/customers/{customerId}/kyc/submit

Manually submit a customer's KYC documents for review. This endpoint is typically not needed as verification is automatically triggered when all required steps are completed via the KYC flow link or API document uploads. Use this endpoint only if auto-submission fails. Cannot be called if review is already in progress or the customer is already verified. A rejected review can be resubmitted. Maximum 4 attempts allowed.

Authorization

bearerAuth
AuthorizationBearer <token>

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

In: header

Path Parameters

customerId*string

Unique identifier of the customer

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/{customerId}/kyc/submit' \  -H 'Authorization: Bearer YOUR_API_KEY'
{
  "success": true,
  "message": "KYC verification submitted for review successfully."
}

{
  "error": "Customer must initiate KYC verification first. Call POST /customers/{customerId}/kyc to start."
}

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

{
  "error": "Customers feature is not enabled for your organization"
}

{
  "error": "Customer not found"
}

{
  "error": "Verification review is already in progress. Please wait for the current review to complete."
}

{
  "error": "Rate limit exceeded. Please try again later."
}

{
  "error": "Internal server error"
}

{
  "error": "Failed to submit for review. Please try again."
}

Initiate customer KYC POST

Generates a KYC flow link for a customer. The link is stable and can be reused to resume verification until the customer is approved. Organizations using Sumsub-hosted verification links instead receive a Sumsub-hosted link that expires after 7 days; call this endpoint again to get a fresh link for the same verification. For these organizations, a verified customer receives a link to their completed verification, and the endpoint returns `400` when that is unavailable or when the customer's identity matches an already verified identity. Some AUD-only customers receive a new link on every call; call this endpoint again whenever you send them a link.

Upload customer KYC document POST

Uploads a KYC document (identity or proof of address) for a customer to our verification provider. The customer must have initiated KYC verification first by calling `POST /customers/{customerId}/kyc`. **Identity Documents** (`idDocType`): - `PASSPORT` - Passport (any country) - `ID_CARD` - National ID card (front and back required) - `DRIVERS` - Driver's license (front and back required) - `RESIDENCE_PERMIT` - Residence permit **Proof of Address** (`idDocType: PROOF_OF_ADDRESS`): Documents must be dated within the **last 3 months**. Accepted documents: - Utility bills (gas, electricity, water) - Telecom bills (internet, cable, mobile phone) - Bank statements or bank letters (neobanks not accepted) - Government documents (tax bills, voter registration) - Lease or rental agreements **File Requirements:** - Formats: JPEG, PNG, PDF - Maximum size: 10MB