Contacts API

Contacts represent people in your Pathbound CRM. Each contact can be enriched with profile data, linked to events, and targeted by agents.

Create a Contact

POST /v1/contacts

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) 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

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.
search	string	—	Free-text search across contact fields.
sort_by	string	—	Field to sort by.
sort_dir	string	—	Sort direction (asc or desc).

Response — 200 OK

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

---

Get a Contact

GET /v1/contacts/:contact_id

Returns the contact along with its unified profile, recent actions, and 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

Request Body

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

---

Delete a Contact

DELETE /v1/contacts/:contact_id

Permanently removes the contact.

---

Get Contact Events

GET /v1/contacts/events/:contact_id

Returns all events associated with a contact.

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 */ ]
}