---
title: "Start KYC verification"
description: "Initiates KYC verification for a customer. For business customers, complete KYC verification for every associated person before starting the business's verification."
protocol: rest
method: POST
endpoint: "/v1/customers/kyc/start"
baseUrl: "https://api.gravv.xyz"
group: "KYC"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Start KYC verification

<Endpoint method="POST" path="/v1/customers/kyc/start" />

Initiates KYC verification for a customer. For business customers, complete KYC verification for every associated person before starting the business's verification.

## Headers

<ParamField name="Idempotency-Key" header="Idempotency-Key" type="string" required>
  Required for POST requests. Reuse only for an identical retry.
</ParamField>

## Request Body

<ParamField name="customer_id" body="customer_id" type="string" required>
  Customer ID to start KYC for
</ParamField>

### Request Examples

<RequestExample>

```json title="KYCRequest"
{
  "customer_id": "d2581d3c-7c55-4607-9717-546694194636"
}
```

</RequestExample>

## Responses

| Status | Description |
| --- | --- |
| `200` | KYC process started successfully |
| `400` | Invalid request |
| `404` | Customer or KYC record not found |
| `409` | KYC already completed for this customer |
| `412` | A required precondition was not met |
| `500` | Internal processing error during KYC initiation |

### 200 response

<ResponseField name="data" type="object" required>

  <Expandable title="properties">
    <ResponseField name="review_status" type="string">
      Applicant review status from the verification process.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Request status
    </ResponseField>

    <ResponseField name="web_url" type="string" required>
      URL to complete the KYC process
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="error" type="any" required>
  Error information if the request failed
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": {
    "status": "success",
    "web_url": "https://verify.gravv.xyz/websdk/p/example_token"
  },
  "error": null
}
```

</ResponseExample>

### 400 response

<ResponseField name="data" type="any" required>
  Always null for error responses
</ResponseField>

<ResponseField name="error" type="string" required>
  Human-readable error message
</ResponseField>

<ResponseField name="error" type="any">

  <Expandable title="properties">
    <ResponseField name="code" type="any">
    </ResponseField>

    <ResponseField name="message" type="any">
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The customer ID provided is not valid. Please verify the customer ID format."
  }
}
```

</ResponseExample>

### 404 response

<ResponseField name="data" type="any" required>
  Always null for error responses
</ResponseField>

<ResponseField name="error" type="string" required>
  Human-readable error message
</ResponseField>

<ResponseField name="error" type="any">

  <Expandable title="properties">
    <ResponseField name="code" type="any">
    </ResponseField>

    <ResponseField name="message" type="any">
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseExample>

```json title="CustomerNotFound"
{
  "data": null,
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer not found. Please verify the customer exists in our system."
  }
}
```

```json title="KycNotFound"
{
  "data": null,
  "error": {
    "code": "KYC_NOT_FOUND",
    "message": "KYC record not found for the specified level."
  }
}
```

</ResponseExample>

### 409 response

<ResponseField name="data" type="any" required>
  Always null for error responses
</ResponseField>

<ResponseField name="error" type="string" required>
  Human-readable error message
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": {
    "code": "KYC_ALREADY_COMPLETED",
    "message": "KYC verification has already been completed for this customer."
  }
}
```

</ResponseExample>

### 412 response

<ResponseField name="data" type="any" required>
  Always null for error responses
</ResponseField>

<ResponseField name="error" type="string" required>
  Human-readable error message
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "missing required business documents"
  }
}
```

</ResponseExample>

### 500 response

<ResponseField name="data" type="any" required>
  Always null for error responses
</ResponseField>

<ResponseField name="error" type="string" required>
  Human-readable error message
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": {
    "code": "KYC_PROCESSING_ERROR",
    "message": "failed to generate verification link"
  }
}
```

</ResponseExample>

## Authorization

- **ApiKeyAuth**