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

# List All Customers — CurbWaste API Reference Guide

> Retrieve a paginated list of customers from your CurbWaste account. Search by name, customerId, email, or phone. Requires the customers:read scope.

Use this endpoint to retrieve a paginated list of customers in your CurbWaste account. Each item returns the full customer profile. Narrow results with an optional `searchTerm` and control pagination with `page` and `limit`.

## Endpoint

```text theme={null}
GET /v1/customers
```

**Base URL:** `https://api.curbwaste.com`

## Required Scope

<Note>
  Your API key must include the **`customers:read`** scope to call this endpoint.
</Note>

## Query Parameters

<ParamField query="searchTerm" type="string">
  Case-insensitive contains match against **displayName**, **customerId**, **email**, or **phone**. Maximum 255 characters.
</ParamField>

<ParamField query="page" default="1" type="integer">
  The page number to return. Must be `1` or greater. Defaults to `1`.
</ParamField>

<ParamField query="limit" default="25" type="integer">
  The number of results to return per page. Must be between `1` and `100`. Defaults to `25`.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.curbwaste.com/v1/customers?page=1&limit=25&searchTerm=Acme" \
    -H "Authorization: Bearer cw_live_YOUR_API_KEY"
  ```
</CodeGroup>

## Example Response

```json 200 OK theme={null}
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "displayName": "Acme Corp",
      "customerId": "C001",
      "status": "active",
      "email": "billing@acmecorp.com",
      "phone": "+15550001234",
      "companyName": "Acme Corporation",
      "createdAt": "2024-01-15T08:30:00.000Z",
      "updatedAt": "2024-06-10T14:22:45.000Z"
    }
  ],
  "page": 1,
  "limit": 25,
  "total": 1
}
```

## Response Fields

<ResponseField name="data" type="array" required>
  An array of customer profiles matching your query. Returns an empty array when no results are found.

  <Expandable title="data[] — PublicCustomer">
    <ResponseField name="data[].id" type="string (uuid)" required>
      The unique identifier for the customer, formatted as a UUID.
    </ResponseField>

    <ResponseField name="data[].displayName" type="string" required>
      The human-readable name used to identify the customer in the CurbWaste dashboard and communications.
    </ResponseField>

    <ResponseField name="data[].customerId" type="string" required>
      CurbWaste CRM customer number (system-assigned, e.g. `C001`). May be an empty string. Not partner-supplied.
    </ResponseField>

    <ResponseField name="data[].status" type="string" required>
      The current status of the customer account. One of `active` or `inactive`.
    </ResponseField>

    <ResponseField name="data[].email" type="string | null">
      The customer's email address, or `null` if unset.
    </ResponseField>

    <ResponseField name="data[].phone" type="string | null">
      The customer's phone number, or `null` if unset.
    </ResponseField>

    <ResponseField name="data[].companyName" type="string | null">
      The customer's company name, or `null` if unset.
    </ResponseField>

    <ResponseField name="data[].createdAt" type="string (datetime) | null">
      ISO 8601 creation timestamp, or `null` when unavailable.
    </ResponseField>

    <ResponseField name="data[].updatedAt" type="string (datetime) | null">
      ISO 8601 last-updated timestamp, or `null` when unavailable.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="page" type="integer" required>
  The current page number returned in this response.
</ResponseField>

<ResponseField name="limit" type="integer" required>
  The maximum number of items returned per page, as requested.
</ResponseField>

<ResponseField name="total" type="integer" required>
  The total number of customers matching your query across all pages.
</ResponseField>

## Errors

| Status Code | Meaning |
| - | - |
| `401 Unauthorized` | Your API key is missing or invalid. Create or rotate a key in the [Developer Platform](https://platform.curbwaste.com). |
| `403 Forbidden` | Your API key does not have the `customers:read` scope. Create a key with that scope in the Developer Platform. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.