Get Started
View as Markdown Open in ChatGPT Open in Claude

Download KYC documents

List a customer's KYC documents and download one side of one document as a data URI, for a compliance review.

You can download an identity or company document a customer gave for KYC, for example to attach a passport to a compliance review file.

A money example. Before approving a contractor's first 3,000.00 USD monthly payout, your compliance team re-checks the passport on file. You list the contractor's documents, download the passport's front, and save it to the review file. No money moves.

Before you start

1. List the documents

Call GET /v1/customers/{customer_id}/kyc/documents first. For documents captured on the hosted page, this call also fetches the images. You can download such a document only after you make this call.

curl --request GET \
     --url https://api.gravv.xyz/v1/customers/3f6b2a1e-8c4d-4e7f-9a2b-5c1d0e9f8a71/kyc/documents \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "customer_id": "3f6b2a1e-8c4d-4e7f-9a2b-5c1d0e9f8a71",
    "documents": [
      {
        "id": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d",
        "IDType": "PASSPORT",
        "IDSubType": "FRONT_SIDE",
        "IDNumber": "B04512398",
        "IssuingCountry": "NGA",
        "IssuedDate": "2020-02-11",
        "ExpiryDate": "2030-02-10",
        "has_front_image": true,
        "has_back_image": false,
        "OriginalFilename": "passport.jpg"
      }
    ],
    "count": 1
  },
  "error": null
}

Pick the document id and a side that has an image (has_front_image or has_back_image).

IDNumber is the full document number, in plain text. Do not log it, and show it only to people allowed to see identity data.

2. Download one side

Call GET /v1/customers/{customer_id}/kyc/documents/{document_id}/download with side front or back.

curl --request GET \
     --url 'https://api.gravv.xyz/v1/customers/3f6b2a1e-8c4d-4e7f-9a2b-5c1d0e9f8a71/kyc/documents/a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d/download?side=front' \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD...",
    "content_type": "image/jpeg",
    "document_id": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d",
    "filename": "passport_front-side_60287353-bc08-482b-871c-98305b9a42dd.jpg",
    "side": "front",
    "size_bytes": 57134
  },
  "error": null
}
  • The response is JSON, not the file. content is a data URI. Strip the data:<type>;base64, prefix, then decode the base64 to get the file. Uploads take raw base64 without the prefix.
  • filename is a storage name. Use OriginalFilename from the list for the customer's own name.
  • A response can be up to about 13 MB.
  • A two-sided ID is two documents, one FRONT_SIDE and one BACK_SIDE. To read the back image, send side=back with the id of the BACK_SIDE document.
  • This endpoint cannot download documents uploaded through the card KYC flow (/v1/risk/upload-document) yet. Keep one upload flow per customer.

What can go wrong

Response Why Fix
400 side is required (front or back) or side must be "front" or "back" side missing or wrong Add ?side=front or ?side=back
400 invalid document_id format Not a UUID Use documents[].id from the list
404 document not found The id belongs to another customer, or does not exist List again for this customer
404 no back image available for this document This document has no image for that side Use the BACK_SIDE document, or the other side
404 no KYC document data found for customer (on the list) The customer has no documents yet. The API returns 404, not an empty list Treat it as "no documents"
404 CUSTOMER_NOT_FOUND: … Wrong customer id or environment Check the id and the key's environment
403 {"reason": "forbidden", "required_any": ["customer:update"]} The key lacks customer:update Use a key with that permission
500 failed to download document image, or 503 storage service not configured A storage problem Retry later. Contact support if it persists

Gravv sends no webhook for document downloads.

Testing in sandbox

Downloads work in sandbox. Upload a small JPEG for a test customer, list the documents, then download it. The decoded content is the file you uploaded.

Was this page helpful?