Start cardholder KYC verification
Starts hosted verification for a cardholder, with a liveness check, and returns a link. The link expires after one hour.
Do not call this for a customer whose KYC is already completed. It sets the customer's KYC back to pending until the new review ends, which can block accounts and cards. To get only a liveness check, use the link that feature activation returns.
Every error on this route is 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. Other fields are ignored.
Request Examples
{
"customer_id": "d2581d3c-7c55-4607-9717-546694194636"
}
Responses
| Status | Description |
|---|---|
200 |
Link issued |
400 |
Any error, including an unknown customer and a start already in progress. |
200 response
Always success.
Possible values: success
Always pending.
Possible values: pending
Hosted verification link. It expires after one hour.
Verification applicant ID. Returned on the first start only.
Verification level, basic. An empty string when a started verification is restarted.
The customer ID. An empty string when a started verification is restarted.
{
"data": {
"status": "success",
"applicant_id": "66f0c2a1b3d4e5f6a7b8c9d0",
"kyc_level": "basic",
"review_status": "pending",
"external_user_id": "d2581d3c-7c55-4607-9717-546694194636",
"web_url": "https://verify.gravv.xyz/websdk/p/example_token"
},
"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_NOT_FOUND: Basic KYC must be completed before upgrading to higher levels."
}
{
"data": null,
"error": "KYC for customer d2581d3c-7c55-4607-9717-546694194636 is already in progress; retry shortly"
}
Authorization
- ApiKeyAuth