KYC overview
Use the KYC API to start customer verification, upload supporting documents, and retrieve verification documents or status.
Start a KYC session or browse the operations in this category.
Review the recommended verification flow before integrating.
Verification flows
Gravv supports two verification flows:
- Hosted flow. Call
POST /v1/customers/kyc/start. The customer completes verification on a hosted page. This is the simplest integration. - Server-to-server (S2S) flow. You collect and submit the documents yourself:
- Upload each required document as a base64-encoded string with its metadata.
- Start S2S verification after you upload all required documents.
In both flows, the outcome is the customer's basic KYC status. Read kyc on GET /v1/customers/{customer_id}, or subscribe to customer KYC webhook events. While the review runs, GET /v1/customers/{customer_id}/kyc/status shows its current state. Errors are strings that start with a code, such as INVALID_REQUEST: ….
For business customers, complete KYC verification for every associated person before you start the business's own verification. Business documents use idDocType COMPANY_DOC with four sub-types. See KYC.
Endpoints
| Endpoint | Description |
|---|---|
POST /v1/customers/kyc/start |
Start hosted KYC verification for a customer |
POST /v1/customers/kyc/upload-document |
Upload a base64-encoded KYC document (S2S step 1) |
POST /v1/customers/kyc/start-s2s |
Start server-to-server verification using uploaded documents (S2S step 2) |
GET /v1/customers/{customer_id}/kyc/documents |
List a customer's uploaded documents with metadata |
GET /v1/customers/{customer_id}/kyc/documents/{document_id}/download |
Download one side of one document as a data URI, for a compliance review. A scoped key needs customer:update. See Download KYC documents |
GET /v1/customers/{customer_id}/kyc/status |
Get the current review status and result |
Reading verification status
| Field | While in review | After review |
|---|---|---|
reviewStatus |
pending |
completed |
reviewResult |
omitted | contains the decision |
Authentication
All requests use https://api.gravv.xyz/v1/ and authenticate with the Api-Key header. See Authentication for details.