Initiate server-to-server KYC verification
Initiates server-to-server (S2S) KYC verification for a customer who has already uploaded the required documents using the /v1/customers/kyc/upload-document endpoint.
This is step 2 of the S2S verification process. Before calling this endpoint, upload all required documents.
For business customers, complete KYC verification for every associated person before starting the business's verification.
On success, verification is initiated and the review outcome is delivered later by webhook. Business customers must upload a registration certificate first, or the request fails with a 400.
Headers
Required for POST requests. Reuse only for an identical retry.
Request Body
Customer ID to initiate KYC verification for. Documents must be uploaded for this customer before calling this endpoint.
Request Examples
{
"customer_id": "aabe0a33-6716-42e2-bbca-7abf1a8bd91c"
}
{
"customer_id": "b84d9a52-2978-43e5-9b86-eac9839e1146"
}
Responses
| Status | Description |
|---|---|
200 |
KYC verification initiated |
400 |
Invalid request |
404 |
Customer or KYC record not found |
409 |
KYC already completed for this customer |
412 |
Required documents have not been uploaded |
500 |
Internal processing error during S2S initiation |
200 response
Possible values: pending
Error information if the request failed
{
"data": {
"status": "pending",
"message": "KYC verification initiated. Status will be updated via webhook."
},
"error": null
}
400 response
Always null for error responses
Human-readable error message
{
"data": null,
"error": {
"code": "INVALID_REQUEST",
"message": "The customer ID provided is not valid"
}
}
404 response
Always null for error responses
Human-readable error message
{
"data": null,
"error": {
"code": "CUSTOMER_NOT_FOUND",
"message": "Customer not found. Please verify the customer exists in our system."
}
}
{
"data": null,
"error": {
"code": "KYC_NOT_FOUND",
"message": "KYC record not found for the specified level."
}
}
409 response
Always null for error responses
Human-readable error message
{
"data": null,
"error": {
"code": "KYC_ALREADY_COMPLETED",
"message": "KYC verification has already been completed for this customer."
}
}
412 response
Always null for error responses
Human-readable error message
{
"data": null,
"error": {
"code": "INVALID_REQUEST",
"message": "no documents found for customer; please upload required documents before initiating S2S verification"
}
}
{
"data": null,
"error": {
"code": "INVALID_REQUEST",
"message": "missing required ID document"
}
}
{
"data": null,
"error": {
"code": "INVALID_REQUEST",
"message": "missing required selfie document"
}
}
500 response
Always null for error responses
Human-readable error message
{
"data": null,
"error": {
"code": "KYC_PROCESSING_ERROR",
"message": "failed to upload documents to verification provider"
}
}
Authorization
- ApiKeyAuth