---
title: "Get KYC document data"
description: "Returns the list of documents a customer has uploaded, with metadata for each one."
protocol: rest
method: GET
endpoint: "/v1/customers/{customer_id}/kyc/documents"
baseUrl: "https://api.gravv.xyz"
group: "KYC"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Get KYC document data

<Endpoint method="GET" path="/v1/customers/{customer_id}/kyc/documents" />

Returns the list of documents a customer has uploaded, with metadata for each one.

## Path Parameters

<ParamField name="customer_id" path="customer_id" type="string" required>
  UUID of the customer
</ParamField>

## Responses

| Status | Description |
| --- | --- |
| `200` | Uploaded documents retrieved |
| `400` | Invalid request |
| `404` | Customer or document data not found |
| `500` | Internal processing error while retrieving documents |

### 200 response

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

  <Expandable title="properties">
    <ResponseField name="customer_id" type="string" required>
      ID of the customer the documents belong to
    </ResponseField>

    <ResponseField name="documents" type="object[]" required>
      Stored documents with their metadata

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Unique identifier for the stored document
        </ResponseField>

        <ResponseField name="IDType" type="string">
          Document type as stored by the verification provider
        </ResponseField>

        <ResponseField name="IDSubType" type="string">
          Document side
        </ResponseField>

        <ResponseField name="IDNumber" type="string">
          Document identification number
        </ResponseField>

        <ResponseField name="IssuingCountry" type="string">
          Issuing country (ISO 3166-1 alpha-3)
        </ResponseField>

        <ResponseField name="IssuedDate" type="string">
          Document issue date (YYYY-MM-DD)
        </ResponseField>

        <ResponseField name="ExpiryDate" type="string">
          Document expiration date (YYYY-MM-DD)
        </ResponseField>

        <ResponseField name="has_front_image" type="boolean">
          Whether a front-side image is stored
        </ResponseField>

        <ResponseField name="has_back_image" type="boolean">
          Whether a back-side image is stored
        </ResponseField>

        <ResponseField name="OriginalFilename" type="string">
          Original filename supplied at upload
        </ResponseField>

      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="integer" required>
      Number of stored documents
    </ResponseField>

  </Expandable>
</ResponseField>

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

<ResponseExample>

```json title="Response"
{
  "data": {
    "customer_id": "42ad0adb-e134-4345-b4be-98e5021b0da8",
    "documents": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "IDType": "PASSPORT",
        "IDSubType": "FRONT_SIDE",
        "IDNumber": "A12345678",
        "IssuingCountry": "NGA",
        "IssuedDate": "2020-01-01",
        "ExpiryDate": "2030-01-01",
        "has_front_image": true,
        "has_back_image": false,
        "OriginalFilename": "passport_front.jpg"
      }
    ],
    "count": 1
  },
  "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": "invalid 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="NoDocumentData"
{
  "data": null,
  "error": {
    "code": "KYC_NOT_FOUND",
    "message": "no KYC document data found for customer"
  }
}
```

</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 retrieve KYC document data"
  }
}
```

</ResponseExample>

## Authorization

- **ApiKeyAuth**