Start server-to-server KYC verification
Sends the documents you uploaded for review, with no hosted page. This is step 2 of server-to-server verification. Upload every required document first.
For a business, every associated person must complete verification first, and the business needs each COMPANY_DOC subtype. Gravv sends the result in the customer.kyc.status.* webhooks.
This flow records no liveness check. A customer verified this way must still complete a liveness step before a card can be issued.
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 |
Documents sent for review, or verification completed at once |
400 |
Invalid request or missing documents |
404 |
Customer or KYC record not found |
409 |
KYC is already completed for this customer, or a request with the same Idempotency-Key is still running. |
422 |
The Idempotency-Key was used before with a different body. |
500 |
The documents could not be sent for review |
503 |
The service is not configured or not reachable. Retry later. |
200 response
pending when the documents were sent for review. completed on tenants with automatic document verification.
Possible values: pending, completed
{
"data": {
"status": "pending",
"message": "KYC verification initiated. Status will be updated via webhook."
},
"error": null
}
{
"data": {
"status": "completed",
"message": "KYC auto-approved for this tenant."
},
"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: no documents found; please upload all required documents before initiating S2S verification"
}
{
"data": null,
"error": "INVALID_REQUEST: missing required documents: Selfie"
}
{
"data": null,
"error": "INVALID_REQUEST: missing required business documents: Tax Document (TAX_DOCUMENT)"
}
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. Please verify the customer exists in our system."
}
409 response
One of the following variants:
Always null for error responses
Error message. Most messages start with an upper-case code and a colon, such as INVALID_REQUEST: ....
Possible values: idempotency_in_flight, idempotency_key_reused
{
"data": null,
"error": "KYC_ALREADY_COMPLETED: KYC verification has already been completed for this customer."
}
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": "failed to upload documents to verification provider"
}
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