Start KYC verification
Starts hosted verification and returns a link for the person or business to complete. The link expires after one hour. Call again with a new Idempotency-Key for a fresh link. The same key returns the old link.
A customer who is already verified gets review_status: completed and no link. For a business, every associated person must complete verification first. Tenants with automatic document verification get a 400 and must use the upload route instead.
Gravv sends the result in the customer.kyc.status.* webhooks. Each first start charges one KYC fee.
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 individual, business or UBO customer to verify. Other fields are ignored.
Request Examples
{
"customer_id": "d2581d3c-7c55-4607-9717-546694194636"
}
Responses
| Status | Description |
|---|---|
200 |
Link issued, or the customer is already verified |
400 |
Invalid request or unmet precondition |
404 |
Customer or KYC record not found |
409 |
A request with the same Idempotency-Key is still running. Retry after the Retry-After header. |
422 |
The Idempotency-Key was used before with a different body. |
500 |
Verification could not start. Retry with a new Idempotency-Key. |
503 |
The service is not configured or not reachable. Retry later. |
200 response
Always success.
Possible values: success
pending when a link was issued. completed when the customer is already verified.
Possible values: pending, completed
Hosted verification link. It expires after one hour. Omitted when review_status is completed.
{
"data": {
"status": "success",
"review_status": "pending",
"web_url": "https://verify.gravv.xyz/websdk/p/example_token"
},
"error": null
}
{
"data": {
"status": "success",
"review_status": "completed"
},
"error": null
}
400 response
Always null for error responses
Error message. Most messages start with an upper-case code and a colon, such as INVALID_REQUEST: ....
{
"data": null,
"error": "INVALID_REQUEST: The customer ID provided is not valid. Please verify the customer ID format."
}
{
"data": null,
"error": "INVALID_REQUEST: associated person \"Ada Obi\" must complete basic KYC before business verification can proceed"
}
{
"data": null,
"error": "INVALID_REQUEST: this tenant uses document-based auto verification; upload required documents instead"
}
404 response
Always null for error responses
Error message. Most messages start with an upper-case code and a colon, such as INVALID_REQUEST: ....
{
"data": null,
"error": "CUSTOMER_NOT_FOUND: Customer not found. Please verify the customer exists in our system."
}
{
"data": null,
"error": "KYC_NOT_FOUND: KYC record not found for the specified level."
}
409 response
Possible values: idempotency_in_flight, idempotency_key_reused
{
"data": null,
"error": {
"code": "idempotency_in_flight",
"message": "A request with the same Idempotency-Key is currently being processed"
}
}
422 response
Possible values: idempotency_in_flight, idempotency_key_reused
{
"data": null,
"error": {
"code": "idempotency_key_reused",
"message": "Idempotency-Key was previously used with a different request payload"
}
}
500 response
Always null for error responses
Error message. Most messages start with an upper-case code and a colon, such as INVALID_REQUEST: ....
{
"data": null,
"error": "KYC_PROCESSING_ERROR: failed to generate verification link"
}
503 response
Always null for error responses
Error message. Most messages start with an upper-case code and a colon, such as INVALID_REQUEST: ....
{
"data": null,
"error": "verification provider not configured"
}
Authorization
- ApiKeyAuth