---
title: "Resolve one customer by customer_id, lead_id, phone, email or external_id, or list customers with opaque cursor pagination (leads:read)."
method: GET
path: "/v1/customers"
---

# Resolve one customer by customer_id, lead_id, phone, email or external_id, or list customers with opaque cursor pagination (leads:read).

`GET /v1/customers`

## Request

- Base URL: `https://www.kaicalls.com/api`
- URL: `https://www.kaicalls.com/api/v1/customers`
- Auth: HTTP bearer

A customer is the durable contact record a business has talked to. `customer_id` and `lead_id` are the same value today and both are accepted, so a consumer holding either identifier resolves the same record. Supplying any ONE lookup key switches the endpoint to lookup mode and returns a single customer object (404 when nothing in the calling workspace matches — a value that exists in another workspace is reported identically, so this cannot be used to probe the platform). Supplying two lookup keys is a 400 rather than a silent precedence rule. Without a lookup key the endpoint lists customers ordered by the immutable `created_at`; page with the opaque `next_cursor` and synchronize with `updated_since`. A cursor is bound to the tenant scope, filters and sort order that produced it and is rejected against any other request.

## Query parameters

- `customer_id` string
- `lead_id` string
- `phone` string
- `email` string
- `external_id` string
- `business_id` string
- `status` string
- `updated_since` string, date-time
- `cursor` string
- `order` 'asc' | 'desc'
- `limit` integer

## Response `200`

A customer object (lookup mode) or a cursor-paginated list.

## Other responses

- `400`: More than one lookup key, an invalid cursor, or a bad updated_since.
- `403`: Missing leads:read scope, or business_id outside the key.
- `404`: No customer in the calling workspace matches the lookup.

---

[API](https://skmtc.dev/kaicalls/apis/kaicalls-public-api.md) · [All operations](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/revisions/e607fc6cf36e?raw)