Contacts API

Contacts represent people in your Pathbound CRM. Each contact has a unified profile, an event timeline, conversation history, and a list of notes. Contacts can be associated with a company, targeted by agents, and grouped by segments.

Create a Contact

POST /v1/contacts

Required scope: contacts:write

Request Body

Field	Type	Required	Description
email	string	yes	Contact email address (must be unique).
properties	object	no	Arbitrary key-value properties for the contact.
visitor_id	string | string[]	no	Website visitor ID(s) from the tracker to associate.

Response — 201 Created

{
  "status": "success",
  "contact": { /* contact object */ }
}

Returns 409 Conflict if a contact with the same email already exists.

---

List Contacts

GET /v1/contacts

Required scope: contacts:read

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number.
limit	number	20	Results per page (1–100).
status	string	—	Filter: enriched or not_enriched.
lifecycle_stage	string	—	Filter by lifecycle stage (lead, prospect, mql, sql, opportunity, customer, evangelist, subscriber, other).
lead_status	string	—	Filter by lead status.
country	string	—	Filter by country.
industry	string	—	Filter by industry.
city	string	—	Filter by city.
state	string	—	Filter by state/region.
job_title	string	—	Filter by job title (case-insensitive match).
has_linkedin	boolean	—	Filter contacts with/without a LinkedIn profile.
company_id	string	—	Filter by associated company ID.
created_after	string	—	Only contacts created after this ISO 8601 date.
created_before	string	—	Only contacts created before this ISO 8601 date.
search	string	—	Free-text search across name, email, company, job title.
sort_by	string	—	Field to sort by (email, firstname, lastname, company, createdate).
sort_dir	string	desc	Sort direction (asc or desc).
count_only	boolean	false	If true, return only { count } — no records.
fields	string	—	Set to summary for a compact ~200 byte/contact response.

Response — 200 OK

{
  "status": "success",
  "contacts": [ /* contact objects */ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total_pages": 5,
    "total_items": 100
  }
}

For a “how many” question, prefer count_only=true. For multi-entity lookups, use the batch API instead of paginating with filters.

---

Get a Contact

GET /v1/contacts/:contact_id

Required scope: contacts:read

Returns the contact along with its unified profile, recent actions, and recent events.

Response — 200 OK

{
  "status": "success",
  "contact": { /* contact object */ },
  "unified_profile": { /* profile data */ },
  "actions": [ /* recent actions */ ],
  "events": [ /* recent events */ ]
}

---

Update a Contact

PUT /v1/contacts/:contact_id

Required scope: contacts:write

Request Body

Field	Type	Required	Description
properties	object	no	Properties to update or add (merge).
visitor_id	string | string[]	no	Visitor ID(s) to associate.

To change a contact’s lifecycle stage, set properties.lifecyclestage to one of the allowed values. For audited stage transitions (with a reason), use the update_lifecycle_stage action — see Actions.

Lifecycle stages

lead, prospect, mql, sql, opportunity, customer, evangelist, subscriber, other.

---

Delete a Contact

DELETE /v1/contacts/:contact_id

Required scope: contacts:write

Permanently removes the contact and its notes. Events and actions remain in the audit log.

---

Get Contact Events

GET /v1/contacts/events/:contact_id

Required scope: contacts:read

Returns all events associated with a contact. For aggregate event queries (across many contacts), use the Events API directly.

Query Parameters

Parameter	Type	Default	Description
event_type	string	—	Filter by event type.
sort_dir	string	desc	Sort direction (asc or desc).

Response — 200 OK

{
  "status": "success",
  "events": [ /* event objects */ ]
}

---

Get Contact Conversations

GET /v1/contacts/:contact_id/conversations

Required scope: contacts:read

Returns the contact’s email (Gmail) and Intercom conversation history.

Query Parameters

Parameter	Type	Default	Description
include_messages	boolean	false	Include the full message bodies, not just thread metadata.
messages_per_thread	number	5	Max messages per thread when include_messages=true.
limit	number	20	Total threads to return.

---

List Contact Email Threads

GET /v1/contacts/:contact_id/email-threads

Required scope: contacts:read

Returns a compact list of Gmail threads for the contact. Use this when drafting a follow-up via the Actions API: pass the returned thread_id into email_message action params to keep the message in the existing thread.

---

Contact Notes

Each contact can have an unlimited list of free-form notes. Notes are written directly (no approval flow) and are visible to anyone with contacts:read.

List Notes

GET /v1/contacts/:contact_id/notes

Required scope: contacts:read

Create a Note

POST /v1/contacts/:contact_id/notes

Required scope: contacts:write

Field	Type	Required	Description
content	string	yes	Note body (markdown).

Update a Note

PATCH /v1/contacts/:contact_id/notes/:note_id

Required scope: contacts:write

Delete a Note

DELETE /v1/contacts/:contact_id/notes/:note_id

Required scope: contacts:write