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 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://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 and Initiate server-to-server verification endpoints.

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: You can get a response indicating that 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.