Know your customer (KYC)

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.

You can submit documents for verification using two methods.

Submit through a dedicated interface

Use the Start KYC verification endpoint to upload identity documents (IDs) through a dedicated interface. The endpoint requires the unique identity (ID) of the customer to make the 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:

{
  "data": {
    "review_status": "pending",
    "status": "success",
    "web_url": "https://in.kyc.com/websdk/p/Cz3WKRuxvlmuS2kp"
  },
  "error": "null"
}

Submit through an API endpoint

You can submit IDs for verification by Base64-encoding them and using the Upload document and Initiate server-to-server verification endpoints. For more information, see Know Your Customer (KYC).

Upload documents

First, upload each required document using the Upload document endpoint. Encode each document in Base64 and provide it as the value of the content field.

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:

{
  "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 endpoint to complete the intermediate KYC process:

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:

{
  "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: the required documents haven't been uploaded yet:

{
  "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:

{
  "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.

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.