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) 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 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"