---
title: "KYC (deprecated)"
---
Know Your Customer (KYC) verification confirms a customer's identity before creating an account or activating certain features. Gravv requires KYC to comply with financial regulations and prevent fraud.

## Required documents

For individual customers, upload one of the following government-issued IDs:

* Passport
* National ID card
* Driver's license

For business customers, upload the business’s registration certificate.

You can submit documents for verification using two methods:

* through a dedicated interface
* through an API endpoints

## Submit through a dedicated interface

Use the [Start KYC verification](/api-reference/risk-deprecated/post-v1-risk-start-kyc) endpoint to upload identity documents (IDs) through a dedicated interface. The endpoint requires the unique identity (ID) of the customer to make the request:

```bash title="basic KYC request"
curl --request POST \
     --url https://api.gravv.xyz/v1/risk/start-kyc \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: order_789_attempt_1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "c239895a-0436-4287-a37a-c2664f68d187"
}
'
```

You’ll receive a response that includes the verification status and a `web_url` link. Share this link with the end user so they can upload their ID documents:

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

## Submit through an API endpoints

You can submit IDs for verification by Base64-encoding them and using the [Upload document](/api-reference/risk-deprecated/post-v1-risk-upload-document) and [Initiate server-to-server verification](/api-reference/risk-deprecated/post-v1-risk-start-kyc-s2s) endpoints.

### Upload documents

First, upload each required document using the [Upload document](/api-reference/risk-deprecated/post-v1-risk-upload-document) endpoint. Encode each document in Base64 and provide it as the value of the content field.

```bash title="upload passport request"
curl --request POST \
     --url https://api.gravv.xyz/v1/risk/upload-document \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: passport_upload_001' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "aabe0a33-6716-42e2-bbca-7abf1a8bd91c",
  "metadata": {
    "idDocType": "passport",
    "idDocSubType": "front_side",
    "country": "usa",
    "firstName": "John",
    "lastName": "Doe",
    "number": "P123456789",
    "issuedDate": "2020-01-15",
    "validUntil": "2030-01-15",
    "dob": "1990-05-20",
    "placeOfBirth": "New York, NY"
  },
  "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAY...",
  "filename": "passport_front.jpg",
  "return_doc_warnings": true
}
'
```

The response confirms upload and may include quality warnings:

```json title="upload passport response"
{
  "data": {
    "document_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "uploaded",
    "message": "Document uploaded successfully",
    "warnings": [
      {
        "code": "low_quality",
        "message": "Document image quality is below recommended threshold"
      }
    ]
  },
  "error": null
}
```

Each document upload requires specific metadata fields:

| Field          | Required For             | Description                                                                                      |
| :------------- | :----------------------- | :----------------------------------------------------------------------------------------------- |
| `idDocType`    | All documents            | Document type: `passport`, `id_card`, `drivers_license`, `selfie`, or `registration_certificate` |
| `idDocSubType` | All documents            | Document side: `front_side` or `back_side`                                                       |
| `country`      | All documents            | Issuing country 3-letter ISO code, such as `usa`, `gbr`, `nga`                                   |
| `firstName`    | All documents            | First name on document                                                                           |
| `lastName`     | All documents            | Last name on document                                                                            |
| `number`       | ID documents             | Document identification number                                                                   |
| `issuedDate`   | ID documents             | Issue date in YYYY-MM-DD format                                                                  |
| `validUntil`   | ID documents             | Expiration date in YYYY-MM-DD format                                                             |
| `dob`          | ID documents             | Date of birth in YYYY-MM-DD format                                                               |
| `placeOfBirth` | ID documents (optional)  | Place of birth as shown on document                                                              |
| `middleName`   | All documents (optional) | Middle name on document                                                                          |

### Initiate verification

After uploading all required documents, call the [Initiate server-to-server verification](/api-reference/risk-deprecated/post-v1-risk-start-kyc-s2s) endpoint to complete the intermediate KYC process:

```bash title="initiate verification request"
curl --request POST \
     --url https://api.gravv.xyz/v1/risk/start-kyc-s2s \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: kyc_initiate_001' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "aabe0a33-6716-42e2-bbca-7abf1a8bd91c"
}
'
```

The endpoint returns one of three possible outcomes:

* **Full success:** All documents uploaded successfully, and verification started:

```json title="full success response"
{
  "data": {
    "review_status": "pending",
    "status": "success",
    "applicant_id": "507f1f77bcf86cd799439011"
  },
  "error": null
}
```

If you get this response, then wait for the webhook notifications about verification status changes.

* **Missing documents:** You can get a response indicating that the required documents haven't been uploaded yet:

```json title="missing documents response"
{
  "data": null,
  "error": {
    "code": "missing_documents",
    "message": "Required documents have not been uploaded for this customer",
    "details": {
      "missing_documents": ["selfie"]
    }
  }
}
```

If you get this response, then upload the missing documents listed in the error response and call the Initiate KYC verification endpoint again.

* **Partial success:** Some documents failed to upload automatically:

```json title="partial success response"
{
  "data": {
    "review_status": "partial_success",
    "status": "partial_success",
    "applicant_id": "507f1f77bcf86cd799439011",
    "failed_documents": [
      {
        "doc_type": "selfie",
        "reason": "Upload failed"
      }
    ]
  },
  "error": null
}
```

If you get this response, then retry uploading the failed documents and call the Initiate KYC verification endpoint again.