> ## 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.

# Customers

> Understand the Customer as the account hub in CurbWaste — identifiers, profile fields, and how it connects to locations, pricing, and other domains.

## What a customer is

Customers are the **account hub** in CurbWaste. Locations, catalog pricing, and related resources hang off a customer. This page covers the Customer resource itself; other domains have their own concept pages as they ship (and appear in the [API Reference](/api-reference/overview) today).

Work with customers under `/v1/customers`.

## In the platform

| Domain | Relationship to Customer |
| - | - |
| **Locations** | Service sites and addresses belong to a customer (referenced by customer UUID). |
| **Catalog & pricing** | SKUs, services, and pricelists; some pricing is scoped to a specific customer. |
| **Webhooks & MCP** | Customer writes emit events; AI agents can work with customers (and other domains) via scoped tools. |

## Identifiers

| Field | What it is | How to use it |
| - | - | - |
| `id` | Stable UUID | Join key after create. Use it in customer paths (`/v1/customers/{id}`) and when other endpoints ask for a customer UUID. |
| `customerId` | CurbWaste CRM number (e.g. `C001`) | System-assigned display number. Searchable via `searchTerm`. **Not** writable on create/update. |

<Warning>
  On the Customer resource, `customerId` is the CRM number. When Locations or catalog pricing inputs require a UUID `customerId`, pass the Customer’s `id`, not the CRM number.
</Warning>

## Customer profile

List and get return the same profile, wrapped as `{ "data": … }`.

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Stable CurbWaste id |
| `displayName` | string | Display name |
| `customerId` | string | CRM customer number (may be empty string) |
| `status` | `active` \| `inactive` | Read-only; derived from the CRM active flag |
| `email` | string \| null | Optional |
| `phone` | string \| null | Optional (max 50) |
| `companyName` | string \| null | Optional |
| `createdAt` | string \| null | ISO-8601 |
| `updatedAt` | string \| null | ISO-8601 |

## What you can change

| Operation | Body fields |
| - | - |
| `POST` create | **Required:** `displayName`. Optional: `email`, `phone`, `companyName` |
| `PATCH` update | Any of `displayName`, `email`, `phone`, `companyName` (at least one required) |

`status` and the CRM `customerId` are read-only on the profile. Successful create/update also emit `customer.created` / `customer.updated` webhook events.

## Finding customers

`GET /v1/customers` returns the full profile for each item. Optional `searchTerm` matches **displayName**, **customerId** (CRM number), **email**, or **phone** (case-insensitive contains). Pagination uses `page` and `limit`.

For the create → store UUID → update workflow, see [Sync customers](/guides/sync-customers). For request and response details, see [List customers](/api-reference/customers/list).

## Related

<CardGroup cols={3}>
  <Card title="Sync customers" icon="arrows-rotate" href="/guides/sync-customers">
    Keep your system aligned using CurbWaste `id` as the join key.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    React to create and update events with signed deliveries.
  </Card>

  <Card title="Customers API" icon="code" href="/api-reference/customers/list">
    Paths, params, and response shapes for `/v1/customers`.
  </Card>
</CardGroup>


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