Customers

A customer represents a company or person that purchases from your business.

The customer object

Field	Type	Description
`id`	string	Unique customer UUID.
`object`	string	Always `customer`.
`customer_number`	integer	Account-assigned customer number.
`name`	string	Customer name.
`office_email`	string or null	Primary office email address.
`office_phone`	string or null	Primary office telephone number.
`office_fax`	string or null	Primary fax number.
`url`	string or null	Customer website URL.
`billing_address_1`	string or null	First billing-address line.
`billing_address_2`	string or null	Second billing-address line.
`billing_city`	string or null	Billing city.
`billing_region`	string or null	Billing state, province, or region.
`billing_postal_code`	string or null	Billing postal or ZIP code.
`billing_country`	string or null	Billing country.
`shipping_address_1`	string or null	First shipping-address line.
`shipping_address_2`	string or null	Second shipping-address line.
`shipping_city`	string or null	Shipping city.
`shipping_region`	string or null	Shipping state, province, or region.
`shipping_postal_code`	string or null	Shipping postal or ZIP code.
`shipping_country`	string or null	Shipping country.
`vat_number`	string or null	VAT or tax registration number.
`document_count`	integer	Number of documents associated with the customer.
`archived`	boolean	Whether the customer is archived.
`pricing_tier_id`	string or null	Assigned pricing-tier UUID.
`owner_user_id`	string or null	UUID of the assigned SalesBinder user.
`created_at`	string	ISO 8601 creation timestamp.
`updated_at`	string	ISO 8601 modification timestamp.

List customers

GET/api/v3/customers

Required scope: customers:read

Returns customers ordered by name and limited by the current user's record visibility.

Query parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number. Defaults to `1`.
`limit`	integer	No	Records per page. Defaults to `20`; maximum `100`.
`q`	string	No	Searches customer name and office email. A numeric value also matches an exact customer number.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/customers?q=example&page=1&limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "object": "list",
  "url": "/api/v3/customers",
  "has_more": false,
  "data": [
    {
      "id": "709d2a43-12a9-4d85-a9d9-cb16e66cef53",
      "object": "customer",
      "customer_number": 527,
      "name": "Example Customer",
      "office_email": "accounts@example.com",
      "office_phone": "604-555-0199",
      "office_fax": "",
      "url": "https://example.com",
      "billing_address_1": "100 Main Street",
      "billing_address_2": "",
      "billing_city": "Vancouver",
      "billing_region": "British Columbia",
      "billing_postal_code": "V6B 1A1",
      "billing_country": "Canada",
      "shipping_address_1": "100 Main Street",
      "shipping_address_2": "",
      "shipping_city": "Vancouver",
      "shipping_region": "British Columbia",
      "shipping_postal_code": "V6B 1A1",
      "shipping_country": "Canada",
      "vat_number": "",
      "document_count": 0,
      "archived": false,
      "pricing_tier_id": null,
      "owner_user_id": "55259a96-c660-4eae-b0d8-3fb16882ca98",
      "created_at": "2026-07-17T22:42:19+00:00",
      "updated_at": "2026-07-17T22:42:19+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_records": 1
  }
}

Retrieve a customer

GET/api/v3/customers/{customer_id}

Required scope: customers:read

Returns one customer within the current user's account and record-visibility boundary.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/customers/709d2a43-12a9-4d85-a9d9-cb16e66cef53" \
  --header "Authorization: Bearer YOUR_API_KEY"

The response is a customer object. If the customer is unavailable to the current user, the API returns 404 resource_missing.

Create a customer

POST/api/v3/customers

Required scope: customers:write

The name field is required. SalesBinder assigns the customer number and current API user.

Writable fields

Field	Type	Required	Notes
`name`	string	Yes	Maximum 255 characters.
`office_email`	string	No	Maximum 255 characters.
`office_phone`	string	No	Maximum 255 characters.
`office_fax`	string	No	Maximum 255 characters.
`url`	string	No	Valid URL, maximum 255 characters.
`billing_address_1`	string	No	Maximum 255 characters.
`billing_address_2`	string	No	Maximum 255 characters.
`billing_city`	string	No	Maximum 255 characters.
`billing_region_id`	integer	No	SalesBinder region identifier.
`billing_region`	string	No	Maximum 255 characters.
`billing_postal_code`	string	No	Maximum 255 characters.
`billing_country_id`	integer	No	SalesBinder country identifier.
`billing_country`	string	No	Maximum 255 characters.
`shipping_address_1`	string	No	Maximum 255 characters.
`shipping_address_2`	string	No	Maximum 255 characters.
`shipping_city`	string	No	Maximum 255 characters.
`shipping_region_id`	integer	No	SalesBinder region identifier.
`shipping_region`	string	No	Maximum 255 characters.
`shipping_postal_code`	string	No	Maximum 255 characters.
`shipping_country_id`	integer	No	SalesBinder country identifier.
`shipping_country`	string	No	Maximum 255 characters.
`vat_number`	string	No	Maximum 24 characters.
`tax_rate1`	number	No	Primary default tax rate.
`tax_rate2`	number	No	Secondary default tax rate.
`customer_label_id`	string	No	Customer-label UUID belonging to the account.
`pricing_tier_id`	string	No	Pricing-tier UUID belonging to the account.

Account-owned references are validated when assigned or changed. A missing UUID or a UUID belonging to another account returns 422 validation_failed without exposing the other account's data.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/customers" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-example-customer-001" \
  --data '{
    "name": "Example Customer",
    "office_email": "accounts@example.com",
    "office_phone": "604-555-0199",
    "billing_city": "Vancouver",
    "billing_region": "British Columbia",
    "billing_country": "Canada"
  }'

Response

Returns the created customer object with 201 Created. See idempotent requests before automatically retrying creates.

Update a customer

PATCH or PUT/api/v3/customers/{customer_id}

Required scope: customers:write

Send only the writable fields that should change. Both PATCH and PUT preserve omitted writable fields.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/customers/709d2a43-12a9-4d85-a9d9-cb16e66cef53" \
  --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "office_phone": "604-555-0142"
  }'

Returns the updated customer object with 200 OK.

Delete a customer

DELETE/api/v3/customers/{customer_id}

Required scope: customers:delete

A customer can be deleted only when it has no associated documents. Deleting a customer with documents returns 422 validation_failed with document_count validation details.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/customers/709d2a43-12a9-4d85-a9d9-cb16e66cef53" \
  --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": "709d2a43-12a9-4d85-a9d9-cb16e66cef53",
  "object": "customer",
  "deleted": true
}