API Reference

Customers

Customers are the people and businesses you invoice. A customer carries its contact details, billing and shipping addresses, contacts, and tax settings.

The Customers API lets your integration create, read, update, and remove the customers in a workspace. A customer is the party you bill — it holds the display name, optional contact details, billing and shipping addresses, a list of contact people, and tax configuration used when invoicing.

Every customer is identified by a UUID. In API responses that UUID is returned as the `id` field, and the same value is what you pass in the path to retrieve, update, or delete a customer. Internal numeric identifiers and workspace foreign keys (such as `teamId`) are never exposed.

Key concepts

Identification

A customer is referenced by its UUID, returned as `id`. Pass that value in the path to retrieve, update, or delete. Bulk update rows use the same value under `uuid`. Optional `salesRepId` on create is a numeric workspace person id, not a UUID.

Required fields

Only `customer` (the name) is required to create a customer. Everything else — including email — is optional, and email does not have to be unique.

Contacts

Contacts are managed inline through the `contacts` array on create and update. The first contact populates the derived `contactName`.

Addresses

Billing and shipping addresses are embedded objects. Provide them inline; either may be null.

Tax handling

Set `taxAutoCalculate` to true to derive tax from the address, or pass a `taxes` array of tax ids for manual rates. `taxExcluded` controls tax-exclusive treatment.

Status & lifecycle

Customers are active by default. Deleting a customer is a soft delete: its status becomes inactive and it stops appearing in active lists.

The customer object

Fields returned on a customer. Related objects (billing/shipping address, contacts, taxes, sales rep) are embedded when present.

Attributes

iduuid

Unique identifier (UUID). Use this value in the path for retrieve, update, and delete.

customerstring

Customer or business name. This is the only field required when creating a customer.

emailstring

Primary contact email. Optional and not required to be unique.

mainPhonestring

Primary phone number.

websitestring

Website URL. If you omit the protocol, the API stores it with an https:// prefix.

statusenum

Customer status. Defaults to active. Deleting a customer sets this to inactive.

One of: active, inactive

notesstring

Free-text notes. HTML is sanitized on save.

paymentTermstring

Default payment term applied to invoices for this customer (for example net30).

taxNumberstring

Tax registration number.

taxAutoCalculateboolean

When true, tax is auto-calculated from the address instead of from the manual taxes list.

taxExcludedboolean

Whether amounts for this customer are treated as tax-exclusive.

contactNamestring

Derived from the first contact; maintained automatically.

billingAddressobject

Billing address, or null.

streetstring

Street address.

citystring

City or locality.

statestring

State, province, or region.

zipCodestring

Postal or ZIP code.

countrystring

Country name or ISO code.

shippingAddressobject

Shipping address, same shape as billingAddress, or null.

contactsarray

Contact people for this customer.

iduuid

Contact identifier (UUID).

firstNamestring

Contact's first name.

lastNamestring

Contact's last name.

emailstring

Contact's email address.

phonestring

Contact's phone number.

isPrimaryboolean

Marks the primary contact.

taxesarray

Tax rates linked to the customer (used when taxAutoCalculate is false).

salesRepobject

The assigned sales representative (a workspace person), or null.

createdAtdatetime

ISO 8601 timestamp when the customer was created.

updatedAtdatetime

ISO 8601 timestamp of the last update.

Example

{
  "id": "dfa3219e-6af8-4c53-997a-037534f63a35",
  "customer": "Acme Corporation",
  "email": "contact@acme.com",
  "mainPhone": "+1234567890",
  "website": "https://acme.com",
  "status": "active",
  "notes": "Preferred customer. Net-30 terms.",
  "paymentTerm": "net30",
  "taxNumber": null,
  "taxAutoCalculate": false,
  "taxExcluded": false,
  "contactName": "John Doe",
  "billingAddress": {
    "id": "0b2c1f5e-7a9d-4f2b-9c1e-2a4b6d8e0f12",
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102",
    "country": "USA"
  },
  "shippingAddress": null,
  "contacts": [
    {
      "id": "a5da3577-bf85-4e3a-aa73-df85ca69bc67",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@acme.com",
      "phone": "+1234567890",
      "isPrimary": true
    }
  ],
  "taxes": [],
  "salesRep": null,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-28T14:22:30.000Z"
}

Identifiers are UUIDs returned as id

Partner responses replace internal numeric ids with the record UUID under the `id` key and remove internal foreign keys such as teamId. Use the `id` value from a response wherever the path expects a customer identifier.

How search works

The `search` query parameter on list matches the customer name, the derived contact name, and contact phone numbers (case-insensitive, partial). It does not search by email.

Deletion is restricted

A customer that has been assigned to an invoice, project, or transaction cannot be deleted and the request returns 400. Firm-managed (system-created) customers also cannot be deleted.

Recent changes

2026-06-29

Budgets API and documentation parity

Added the Budgets API reference (14 endpoints), invoice send-history, and account sub-types list. Introduced an automated parity check (`npm run check:parity`) that compares documented routes against count-dev. Normalized customer path parameters to `{uuid}` and fixed the documents chunk-upload progress path.