Contacts API

Contacts are the core CRM record. All endpoints are org-scoped via X-Org-Id and respect the caller’s data-scoping (a member restricted to “only assigned data” sees only their assigned contacts).

Endpoints

All paths are prefixed with /api/v1.

Method	Path	Description
GET	/contacts	List contacts (paginated; supports today’s q / tag projection).
POST	/contacts	Create a contact (201).
POST	/contacts/import	Bulk import contacts; returns an import result summary.
POST	/contacts/search	Server-side advanced filter (the smart-list query model).
GET	/contacts/views	List saved smart-list views (org-shared).
PUT	/contacts/views	Save / replace smart-list views.
GET	/contacts/{contact_id}	Get one contact (detail).
PATCH	/contacts/{contact_id}	Update a contact.
DELETE	/contacts/{contact_id}	Delete a contact.
GET	/contacts/{contact_id}/opportunities	Opportunities linked to a contact.

Advanced search

POST /contacts/search compiles an OR-of-AND filter model into a single SQL query — OR across groups, AND within a group:

{
  "query": {
    "groups": [
      { "conditions": [{ "field": "tags", "op": "contains", "value": "replied-interested" }] }
    ]
  },
  "q": "optional free-text",
  "limit": 50,
  "offset": 0
}

Fields include contact columns (name, email, phone, company, source, notes, tags, dnc, created_at) and custom.<key> JSONB paths. An invalid filter returns 422.

Tags and custom fields

Tags, custom-field folders, custom fields, and per-contact custom values live in the customization router (also under /api/v1):

Method	Path	Description
GET	/tags	List tags.
POST	/tags	Create a tag (201).
DELETE	/tags/{tag_id}	Delete a tag.
POST	/contacts/{contact_id}/tags	Add tag(s) to a contact.
DELETE	/contacts/{contact_id}/tags/{name}	Remove a tag from a contact.
GET	/custom-fields	List custom-field definitions.
POST	/custom-fields	Create a custom field (201).
PATCH	/custom-fields/{field_id}	Update a custom field.
DELETE	/custom-fields/{field_id}	Delete a custom field.
PUT	/contacts/{contact_id}/custom/{key}	Set a contact’s custom field value.

Custom values (the {{custom_values.x}} token store used by the setter and cold-SMS copy) are managed via GET /custom-values, PUT /custom-values/{key}, and DELETE /custom-values/{key}.