# Customers

> Manage customer records, contacts, and bulk imports.

- **Category:** Guides
- HTML version: https://www.ondayzero.com/docs/guides/customers
- All guides: https://www.ondayzero.com/docs/guides/index.md
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

# Customers

Customers represent the people and businesses that owe you money. They are linked to invoices, credit memos, and payment records.

## Create a Customer

```bash
curl -X POST "https://api.ondayzero.com/api/v1/customers" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "phone": "+1-555-0100",
    "address": "123 Main St, San Francisco, CA 94105",
    "credit_limit_cents": 5000000
  }'
```

> `credit_limit_cents` is in cents. `5000000` = $50,000.00 credit limit.

`name` and `email` are required. Optional: `tax_id`, `website`, `notes`, `category`, `status` (`active` — the default — `inactive` or `blocked`), `default_payment_term_id` (see [Payment Terms](/docs/guides/payment-terms)) and `invoice_footer` (text printed on this customer's invoices).

## List Customers

```bash
curl "https://api.ondayzero.com/api/v1/customers?search=acme&limit=25" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

### Filter Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `search` | string | Fuzzy search by name (1-200 chars) |
| `email` | string | Filter by exact email |
| `status` | string | `active`, `inactive` or `blocked` |
| `id` | UUID | Get specific customer by ID |

Plus the standard [pagination](/docs/guides/pagination) parameters.

## Get a Customer

```bash
curl "https://api.ondayzero.com/api/v1/customers/{customer_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

## Update a Customer

```bash
curl -X PUT "https://api.ondayzero.com/api/v1/customers/{customer_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "website": "https://acme.com"
  }'
```

## Contacts

Each customer can have multiple contacts (billing, technical, etc.):

```bash
curl -X POST "https://api.ondayzero.com/api/v1/customers/{customer_id}/contacts" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@acme.com",
    "role": "Accounts Payable",
    "is_primary": true
  }'
```

List contacts: `GET /api/v1/customers/{customer_id}/contacts`. Update or remove one with `PUT` / `DELETE /api/v1/customers/{customer_id}/contacts/{contact_id}`.

## Bulk Upload

Download the CSV template with `GET /api/v1/customers/bulk-upload/template`, then import:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/customers/bulk-upload" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -F "file=@customers.csv"
```

CSV columns: `name`, `email`, `phone`, `address`, `tax_id`, `website`, `notes`, `category`, `status`, `credit_limit` (in dollars, not cents).

Duplicate emails are automatically skipped. The response includes counts and any row-level errors.

## Duplicate Detection

Before creating a customer, check for potential duplicates:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/customers/check-duplicates?name=Acme%20Corp&email=billing@acme.com" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

Returns a list of similar existing customers with similarity scores and match types. `name` is required; `email`, `tax_id` and `exclude_id` (ignore one customer, e.g. the one you're editing) are optional.

## AI Helpers

- `POST /api/v1/customers/categorize?name=…` suggests a `category` for a customer from its name, email, website and address; `POST /api/v1/customers/auto-categorize` fills in every uncategorized customer.
- `POST /api/v1/customers/analyze-payment-behavior` summarises how promptly customers pay, from their invoice history.

## Delete a Customer

```bash
curl -X DELETE "https://api.ondayzero.com/api/v1/customers/{customer_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```