---
title: "Get customers"
description: "Retrieve a paginated list of customers with optional filters."
protocol: rest
method: GET
endpoint: "/v1/customers"
baseUrl: "https://api.gravv.xyz"
group: "Customers"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Get customers

<Endpoint method="GET" path="/v1/customers" />

Retrieve a paginated list of customers with optional filters.

## Query Parameters

<ParamField name="page" query="page" type="integer">
  Page number (1-based)
</ParamField>

<ParamField name="items_per_page" query="items_per_page" type="integer">
  Number of items per page
</ParamField>

<ParamField name="email" query="email" type="string">
  Filter by exact email address
</ParamField>

<ParamField name="sort" query="sort" type="string">
  Sort order (e.g. `created_at ASC` or `created_at DESC`)
</ParamField>

<ParamField name="status" query="status" type="string">
  Filter by customer status (e.g. `active`)
</ParamField>

<ParamField name="type" query="type" type="string">
  Filter by customer type

  Possible values: `individual`, `business`
</ParamField>

<ParamField name="keyword" query="keyword" type="string">
  Full-text search across first name, last name, email, and customer ID
</ParamField>

<ParamField name="kyc_status" query="kyc_status" type="string">
  Filter by KYC status of the customer's basic KYC record
</ParamField>

<ParamField name="from" query="from" type="integer">
  Offset — number of records to skip before the current page
</ParamField>

<ParamField name="to" query="to" type="integer">
  Upper record offset bound
</ParamField>

## Responses

| Status | Description |
| --- | --- |
| `200` | Paginated list of customers |
| `400` | Bad request — invalid or missing parameters |

### 200 response

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

  <Expandable title="properties">
    <ResponseField name="items" type="object[]">

      <Expandable title="properties">
        <ResponseField name="id" type="string">
        </ResponseField>

        <ResponseField name="first_name" type="string">
        </ResponseField>

        <ResponseField name="last_name" type="string">
        </ResponseField>

        <ResponseField name="middle_name" type="string">
        </ResponseField>

        <ResponseField name="type" type="string">

          Possible values: `individual`, `business`
        </ResponseField>

        <ResponseField name="email" type="string">
        </ResponseField>

        <ResponseField name="phone" type="string">
        </ResponseField>

        <ResponseField name="address" type="object">

          <Expandable title="properties">
            <ResponseField name="address_line1" type="string" required>
            </ResponseField>

            <ResponseField name="address_line2" type="string">
            </ResponseField>

            <ResponseField name="city" type="string" required>
            </ResponseField>

            <ResponseField name="postal_code" type="string" required>
            </ResponseField>

            <ResponseField name="state" type="string" required>
            </ResponseField>

            <ResponseField name="country" type="string" required>
            </ResponseField>

          </Expandable>
        </ResponseField>

        <ResponseField name="status" type="string">
        </ResponseField>

        <ResponseField name="kyc" type="object[]">

          <Expandable title="properties">
            <ResponseField name="id" type="string">
            </ResponseField>

            <ResponseField name="type" type="string">
            </ResponseField>

            <ResponseField name="status" type="string">
            </ResponseField>

            <ResponseField name="kyc_url" type="string">
            </ResponseField>

            <ResponseField name="remark" type="string">
            </ResponseField>

            <ResponseField name="verified_at" type="string,null">
            </ResponseField>

          </Expandable>
        </ResponseField>

        <ResponseField name="associated_persons" type="object[]">

          <Expandable title="properties">
            <ResponseField name="id" type="string">
            </ResponseField>

            <ResponseField name="first_name" type="string">
            </ResponseField>

            <ResponseField name="middle_name" type="string">
            </ResponseField>

            <ResponseField name="last_name" type="string">
            </ResponseField>

            <ResponseField name="email" type="string">
            </ResponseField>

            <ResponseField name="date_of_birth" type="string">
            </ResponseField>

            <ResponseField name="gender" type="string">

              Possible values: `male`, `female`, `other`
            </ResponseField>

            <ResponseField name="phone" type="string">
            </ResponseField>

            <ResponseField name="status" type="string">
            </ResponseField>

            <ResponseField name="type" type="string">
            </ResponseField>

            <ResponseField name="address" type="object">

              <Expandable title="properties">
                <ResponseField name="address_line1" type="string" required>
                </ResponseField>

                <ResponseField name="address_line2" type="string">
                </ResponseField>

                <ResponseField name="city" type="string" required>
                </ResponseField>

                <ResponseField name="postal_code" type="string" required>
                </ResponseField>

                <ResponseField name="state" type="string" required>
                </ResponseField>

                <ResponseField name="country" type="string" required>
                </ResponseField>

              </Expandable>
            </ResponseField>

            <ResponseField name="date_added" type="string">
            </ResponseField>

            <ResponseField name="kyc" type="object[]">

              <Expandable title="properties">
                <ResponseField name="id" type="string">
                </ResponseField>

                <ResponseField name="type" type="string">
                </ResponseField>

                <ResponseField name="status" type="string">
                </ResponseField>

                <ResponseField name="kyc_url" type="string">
                </ResponseField>

                <ResponseField name="remark" type="string">
                </ResponseField>

                <ResponseField name="verified_at" type="string,null">
                </ResponseField>

              </Expandable>
            </ResponseField>

          </Expandable>
        </ResponseField>

        <ResponseField name="business_name" type="string">
        </ResponseField>

        <ResponseField name="business_description" type="string">
        </ResponseField>

        <ResponseField name="business_type" type="string">
        </ResponseField>

        <ResponseField name="business_industry" type="string">
        </ResponseField>

        <ResponseField name="registration_number" type="string">
        </ResponseField>

        <ResponseField name="date_added" type="string">
        </ResponseField>

        <ResponseField name="external_id" type="string">
        </ResponseField>

        <ResponseField name="industry_code" type="string">
        </ResponseField>

      </Expandable>
    </ResponseField>

    <ResponseField name="page" type="integer">
    </ResponseField>

    <ResponseField name="items_per_page" type="integer">
    </ResponseField>

    <ResponseField name="total_pages" type="integer">
    </ResponseField>

    <ResponseField name="total_items" type="integer">
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="error" type="null">
</ResponseField>

### 400 response

<ResponseField name="data" type="null">
</ResponseField>

<ResponseField name="error" type="string">
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": "invalid request body"
}
```

</ResponseExample>

## Authorization

- **ApiKeyAuth**