> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lms.bsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List customers

> Fetch a paginated list of customers.

Returns a paginated page of customers. See
[Pagination](/concepts/pagination) for the common query parameter
contract.

## Query parameters

<ParamField query="page" type="integer" default="1" />

<ParamField query="rows" type="integer" default="10">
  Page size, max 100.
</ParamField>

<ParamField query="orderBy" type="string">
  Column to sort by. Common values: `id`, `displayName`,
  `submittedDate`, `activationDate`.
</ParamField>

<ParamField query="sortOrder" type="string">
  `ASC` or `DESC`.
</ParamField>

<ParamField query="externalId" type="string">
  Point-lookup by partner-supplied externalId. Returns a single-item
  page if found, or an empty page (`items: []`, `total: 0`) if not.
  externalId uniqueness is enforced upstream, so at most one match is
  ever returned. Pagination params are still honoured for response
  shape but don't affect the result.
</ParamField>

## Examples

```bash theme={null}
# Paginated list of all customers
curl -sf "$BASE/v1/customers?page=1&rows=25" \
  -H "Authorization: Bearer $TOKEN"

# Find a customer by externalId (returns 0 or 1 item)
curl -sf "$BASE/v1/customers?externalId=ext-ada-001" \
  -H "Authorization: Bearer $TOKEN"
```

## Response

```json theme={null}
{
  "items": [
    {
      "id": "42",
      "accountNo": "000000042",
      "status": "Active",
      "active": true,
      "officeId": "1",
      "displayName": "Ada Lovelace",
      "activationDate": "2026-05-22"
    }
  ],
  "total": 1284,
  "page": 1,
  "rowsPerPage": 25
}
```

Each `items` entry has the same shape as the
[customer object](/customers/overview).