---
title: "KYC overview"
description: "Verify customers and retrieve verification status."
---

# KYC overview

Use the KYC API to start customer verification, upload supporting documents, and retrieve verification documents or status.

<CardGroup cols={2}>
  <Card title="Browse KYC endpoints" icon="code" href="/api-reference/kyc/post-v1-customers-kyc-start">
    Start a KYC session or browse the operations in this category.
  </Card>
  <Card title="KYC integration guide" icon="book" href="/getting-started/kyc-new">
    Review the recommended verification flow before integrating.
  </Card>
</CardGroup>

## Verification flows

Gravv supports two verification flows:

1. **Hosted flow** — call [`POST /v1/customers/kyc/start`](/api-reference/kyc/post-v1-customers-kyc-start). The customer completes verification through the provider's hosted experience. This is the simplest integration.
2. **Server-to-server (S2S) flow** — you collect and submit documents yourself:
   1. [Upload each required document](/api-reference/kyc/post-v1-customers-kyc-upload-document) as a base64-encoded string with its metadata.
   2. [Start S2S verification](/api-reference/kyc/post-v1-customers-kyc-start-s2s) once all required documents are uploaded.

In both flows, poll [`GET /v1/customers/{customer_id}/kyc/status`](/api-reference/kyc/get-v1-customers-customer-id-kyc-status) for the outcome, or subscribe to [customer KYC webhook events](/platform/webhooks/customer-kyc-events).

<Note>
For **business customers**, complete KYC verification for every associated person before starting the business's own verification.
</Note>

## Endpoints

| Endpoint | Description |
|---|---|
| [`POST /v1/customers/kyc/start`](/api-reference/kyc/post-v1-customers-kyc-start) | Start hosted KYC verification for a customer |
| [`POST /v1/customers/kyc/upload-document`](/api-reference/kyc/post-v1-customers-kyc-upload-document) | Upload a base64-encoded KYC document (S2S step 1) |
| [`POST /v1/customers/kyc/start-s2s`](/api-reference/kyc/post-v1-customers-kyc-start-s2s) | Start server-to-server verification using uploaded documents (S2S step 2) |
| [`GET /v1/customers/{customer_id}/kyc/documents`](/api-reference/kyc/get-v1-customers-customer-id-kyc-documents) | List a customer's uploaded documents with metadata |
| [`GET /v1/customers/{customer_id}/kyc/status`](/api-reference/kyc/get-v1-customers-customer-id-kyc-status) | Current verification status and review 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](/getting-started/authentication) for details.