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

# Sync customers

> Keep your system linked to CurbWaste customers — create, store the UUID join key, update, find with searchTerm, and optionally ingest webhook events.

Push customer changes from your system into CurbWaste and keep a stable link using the CurbWaste UUID. This guide is **outbound** sync; use webhooks when you also need **inbound** updates from CurbWaste.

## Prerequisites

* An API key from the [Developer Platform](https://platform.curbwaste.com) with `customers:read` and `customers:write` — see [Authentication](/authentication)
* A place in your system to store the CurbWaste customer UUID after create

<Warning>
  The API does **not** accept partner-supplied `customerId` on create/update. After create, store `data.id` (UUID) as your join key. CRM `customerId` (e.g. `C001`) is system-assigned and searchable — see [Customers](/concepts/customers).
</Warning>

## Step 1 — Create and store the UUID

`displayName` is required. Optional: `email`, `phone`, `companyName`.

```bash theme={null}
export CURBWASTE_API_KEY="cw_live_…"

curl -sS -X POST "https://api.curbwaste.com/v1/customers" \
  -H "Authorization: Bearer $CURBWASTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Acme Corp","email":"billing@acme.com"}'
```

Save `data.id` from the response into your system (shown as `$CUSTOMER_ID` below).

## Step 2 — Update when contact fields change

```bash theme={null}
curl -sS -X PATCH "https://api.curbwaste.com/v1/customers/$CUSTOMER_ID" \
  -H "Authorization: Bearer $CURBWASTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"ap@acme.com"}'
```

Send at least one of `displayName`, `email`, `phone`, or `companyName`.

## Step 3 — Find candidates before linking

Use list + `searchTerm` when you need to discover an existing CurbWaste record (matches displayName, CRM customerId, email, or phone), then fetch or store that `id`.

```bash theme={null}
curl -sS "https://api.curbwaste.com/v1/customers?searchTerm=acme" \
  -H "Authorization: Bearer $CURBWASTE_API_KEY"
```

## Stay current without polling

Register webhooks for `customer.created` / `customer.updated` and upsert locally on envelope `data.id`. See [Webhook setup](/guides/webhooks-setup).

## Related

<CardGroup cols={3}>
  <Card title="Webhook setup" icon="webhook" href="/guides/webhooks-setup">
    Ingest create/update events instead of polling.
  </Card>

  <Card title="Customers" icon="users" href="/concepts/customers">
    Identifiers, profile fields, and how customers connect to other domains.
  </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.