Contacts

Contacts store individual people and can be linked to one or more customers, prospects, or suppliers in the same SalesBinder account.

The contact object

Field	Type	Description
`id`	string	Contact UUID.
`object`	string	Always `contact`.
`first_name`	string	First name.
`last_name`	string or null	Last name.
`job_title`	string or null	Job title.
`phone`	string or null	Primary telephone number.
`cell`	string or null	Mobile telephone number.
`fax`	string or null	Fax number.
`email_1`	string or null	Primary email address.
`email_2`	string or null	Secondary email address.
`auto_add_email`	boolean	Whether SalesBinder automatically includes the contact when emailing a linked account record.
`account_records`	array	Visible customers, prospects, and suppliers linked to the contact.
`created_at`	string or null	ISO 8601 creation timestamp.
`updated_at`	string or null	ISO 8601 update timestamp.

Each account_records entry contains id, object, and name. Its object is customer, prospect, or supplier.

{
  "id": "7e72a682-eed9-4d32-aa8a-5ec624e49952",
  "object": "contact",
  "first_name": "Jordan",
  "last_name": "Lee",
  "job_title": "Purchasing Manager",
  "phone": "604-555-0142",
  "cell": null,
  "fax": null,
  "email_1": "jordan.lee@example.com",
  "email_2": null,
  "auto_add_email": true,
  "account_records": [
    {
      "id": "1e16bbed-38df-44d1-acf0-a840cb364f01",
      "object": "customer",
      "name": "Example Company"
    }
  ],
  "created_at": "2026-07-20T09:15:00-07:00",
  "updated_at": "2026-07-20T09:15:00-07:00"
}

List contacts

GET/api/v3/contacts

Required scope: contacts:read

Returns contacts using the standard page-based list response.

Query parameter	Type	Description
`page`	integer	Page number, starting at `1`.
`limit`	integer	Records per page from `1` to `100`. Defaults to `20`.
`q`	string	Searches names, email addresses, and phone numbers.
`account_record_id`	string	Limits results to contacts linked to the visible customer, prospect, or supplier UUID.

curl "https://yourbusiness.salesbinder.com/api/v3/contacts?q=jordan&limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

This endpoint requires contacts:read and the user's current account-management permission.

Retrieve a contact

GET/api/v3/contacts/{contact_id}

Required scope: contacts:read

Returns one visible contact.

curl "https://yourbusiness.salesbinder.com/api/v3/contacts/7e72a682-eed9-4d32-aa8a-5ec624e49952" \
  --header "Authorization: Bearer YOUR_API_KEY"

This endpoint requires contacts:read.

Create a contact

POST/api/v3/contacts

Required scope: contacts:write

Creates a contact. first_name is required. account_record_ids optionally supplies the complete set of linked customer, prospect, and supplier UUIDs.

Field	Required	Description
`first_name`	Yes	Non-empty first name, up to 255 characters.
`last_name`	No	Last name, up to 255 characters.
`job_title`	No	Job title, up to 255 characters.
`phone`	No	Primary telephone number.
`cell`	No	Mobile telephone number.
`fax`	No	Fax number.
`email_1`	No	Valid primary email address.
`email_2`	No	Valid secondary email address.
`auto_add_email`	No	Defaults to `false`.
`account_record_ids`	No	Unique visible customer, prospect, or supplier UUIDs.

curl "https://yourbusiness.salesbinder.com/api/v3/contacts" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-contact-20260720-001" \
  --data '{
    "first_name": "Jordan",
    "last_name": "Lee",
    "email_1": "jordan.lee@example.com",
    "auto_add_email": true,
    "account_record_ids": ["1e16bbed-38df-44d1-acf0-a840cb364f01"]
  }'

The response is 201 Created. This endpoint requires contacts:write and supports an optional short-lived Idempotency-Key.

All linked records must belong to the current account and be visible to the API user. SalesBinder manages relationship metadata and timestamps.

Update a contact

PATCH/api/v3/contacts/{contact_id}

Required scope: contacts:write

Updates supported fields on a contact. Omit account_record_ids to preserve existing links. Include it to replace the complete collection; an empty array removes every link.

curl "https://yourbusiness.salesbinder.com/api/v3/contacts/7e72a682-eed9-4d32-aa8a-5ec624e49952" \
  --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "job_title": "Operations Manager",
    "account_record_ids": ["1e16bbed-38df-44d1-acf0-a840cb364f01"]
  }'

This endpoint requires contacts:write.

Visibility

Contacts always remain inside the authenticated SalesBinder account. Users with permission to view all account records can access contacts linked to any customer, prospect, or supplier in that account. Other users can access only contacts linked to account records assigned to them; contacts with no visible relationship are not exposed.

API v3 does not support archiving or unarchiving contacts.