Start server-to-server cardholder KYC verification
Sends the documents you uploaded for a cardholder for review. This is step 2 of server-to-server card KYC.
Three outcomes return HTTP 200, so check data.status and data.code: pending (sent for review), partial_success (the customer finishes on web_url), or a code of MISSING_DOCUMENTS or KYC_ALREADY_COMPLETED.
This flow records no liveness check, so card activation will ask for one. Other errors are HTTP 400.
Headers
Required for POST requests. 1 to 255 printable ASCII characters. A retry with the same key and body within 24 hours returns the first response.
Request Body
ID of the customer to verify. Upload the required documents for this customer first.
Request Examples
{
"customer_id": "aabe0a33-6716-42e2-bbca-7abf1a8bd91c"
}
{
"customer_id": "b84d9a52-2978-43e5-9b86-eac9839e1146"
}
Responses
| Status | Description |
|---|---|
200 |
Sent for review, partly sent, or a coded result |
400 |
Any other error |
200 response
One of the following variants:
pending when every document was sent for review. partial_success when some documents failed. The customer then finishes on web_url.
Possible values: pending, partial_success
Verification applicant ID
Hosted link to finish the failed documents. Only on partial_success.
Documents that could not be sent. Only on partial_success.
Stored type, such as ID_CARD
Missing documents, or KYC already completed. Returned with HTTP 200.
Possible values: MISSING_DOCUMENTS, KYC_ALREADY_COMPLETED
{
"data": {
"status": "pending",
"applicant_id": "66f0c2a1b3d4e5f6a7b8c9d0",
"message": "KYC verification initiated. Status will be updated via webhook."
},
"error": null
}
{
"data": {
"status": "partial_success",
"applicant_id": "66f0c2a1b3d4e5f6a7b8c9d0",
"web_url": "https://verify.gravv.xyz/websdk/p/example_token",
"failed_documents": [
{
"doc_type": "SELFIE",
"reason": "Upload failed"
}
],
"message": "Upload failed"
},
"error": null
}
{
"data": {
"code": "MISSING_DOCUMENTS",
"message": "Required documents have not been uploaded for this customer",
"details": {
"missing_documents": [
"government_id (PASSPORT, ID_CARD, or DRIVERS)",
"SELFIE"
]
}
},
"error": null
}
{
"data": {
"code": "KYC_ALREADY_COMPLETED",
"message": "KYC verification has already been completed for this customer."
},
"error": null
}
400 response
Always null for error responses
Error message. Most messages start with an upper-case code and a colon, such as CUSTOMER_NOT_FOUND: ....
{
"data": null,
"error": "CUSTOMER_NOT_FOUND: Customer not found. Please verify the customer exists in our system."
}
{
"data": null,
"error": "KYC_PROCESSING_ERROR: KYC processing failed. Please try again later or contact support."
}
Authorization
- ApiKeyAuth