Suppliers

A supplier represents a company or person that provides products or services to your business.

The supplier object

Field	Type	Description
`id`	string	Unique supplier UUID.
`object`	string	Always `supplier`.
`customer_number`	integer	Account-assigned supplier number.
`name`	string	Supplier 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	Supplier 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.
`document_count`	integer	Number of documents associated with the supplier.
`archived`	boolean	Whether the supplier is archived.
`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 suppliers

GET/api/v3/suppliers

Required scope: suppliers:read

Returns suppliers 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 supplier name and office email. A numeric value also matches an exact supplier number.

Example request

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

Example response

{
  "object": "list",
  "url": "/api/v3/suppliers",
  "has_more": false,
  "data": [
    {
      "id": "91651057-1c88-4598-8cfa-6ac006a21e0a",
      "object": "supplier",
      "customer_number": 312,
      "name": "Example Supplier",
      "office_email": "orders@example.com",
      "office_phone": "604-555-0164",
      "office_fax": "",
      "url": "https://example.com",
      "billing_address_1": "300 Main Street",
      "billing_address_2": "",
      "billing_city": "Vancouver",
      "billing_region": "British Columbia",
      "billing_postal_code": "V6B 3C3",
      "billing_country": "Canada",
      "shipping_address_1": "300 Main Street",
      "shipping_address_2": "",
      "shipping_city": "Vancouver",
      "shipping_region": "British Columbia",
      "shipping_postal_code": "V6B 3C3",
      "shipping_country": "Canada",
      "document_count": 0,
      "archived": false,
      "owner_user_id": "693ab0a0-d0f1-4dd1-a462-d8f9867d3747",
      "created_at": "2026-07-18T18:42:19+00:00",
      "updated_at": "2026-07-18T18:42:19+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_records": 1
  }
}

Retrieve a supplier

GET/api/v3/suppliers/{supplier_id}

Required scope: suppliers:read

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

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/suppliers/91651057-1c88-4598-8cfa-6ac006a21e0a" \
  --header "Authorization: Bearer YOUR_API_KEY"

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

Create a supplier

POST/api/v3/suppliers

Required scope: suppliers:write

The name field is required. SalesBinder assigns the supplier 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.
`tax_rate1`	number	No	Primary default tax rate.
`tax_rate2`	number	No	Secondary default tax rate.
`customer_label_id`	string	No	Account-label UUID.

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/suppliers" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-example-supplier-001" \
  --data '{
    "name": "Example Supplier",
    "office_email": "orders@example.com",
    "office_phone": "604-555-0164",
    "billing_city": "Vancouver",
    "billing_region": "British Columbia",
    "billing_country": "Canada"
  }'

Response

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

Update a supplier

PATCH or PUT/api/v3/suppliers/{supplier_id}

Required scope: suppliers: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/suppliers/91651057-1c88-4598-8cfa-6ac006a21e0a" \
  --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "office_phone": "604-555-0118"
  }'

Returns the updated supplier object with 200 OK.

Delete a supplier

DELETE/api/v3/suppliers/{supplier_id}

Required scope: suppliers:delete

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

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/suppliers/91651057-1c88-4598-8cfa-6ac006a21e0a" \
  --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": "91651057-1c88-4598-8cfa-6ac006a21e0a",
  "object": "supplier",
  "deleted": true
}