Contacts REST API

Contacts represent people in your Pathbound workspace. Each contact has a unified profile, an event timeline, conversation history, and a list of notes. Contacts are associated with a company and have a chronological event timeline.

Related endpoints on other pages: tags on a contact, sending a contact an email, enriching contacts, and identifying a logged-in user from your server.

POST /v1/contacts

Required scope: contacts:write

Without external_id, this creates a contact and an email that already exists is a 409. With external_id, your own id for the person, it is an upsert on that id, so the same request sent twice leaves one contact, unchanged by the second:

1. A contact that has this external_id is updated.
2. Else a contact that has no external id yet and holds the email takes your id and is updated. If that contact is already keyed to another id, the answer is 409 with code: "EXTERNAL_ID_CONFLICT" and its contact_id, and nothing changes.
3. Else the contact is created.

An update merges what you send: a property you send replaces the stored value, and one you leave out keeps it. An email that another contact already holds is not written, and skipped_traits says so ("email": "email_belongs_to_contact:<contact_id>"); the other fields are.

A visitor is tied to a contact only through visitor_id: a sb_visitor_ids key in properties is ignored, here and on Update a Contact.

With external_id, a company you name replaces the contact’s company, and the company it had is removed from associations.companies: a user who moves to another account is no longer listed under the old one. Without a company, a contact on a corporate email domain is linked to the company that holds that domain, if there is one and the contact has no company yet.

201 when the contact was created. A contact updated through its external_id is answered 200 OK in the same shape, with "created": false.

{
  "status": "success",
  "message": "Contact created successfully",
  "contact_id": "665f1c2ab3d4e5f601234567",
  "created": true,
  "contact": {
    "contact_id": "665f1c2ab3d4e5f601234567",
    "_id": "665f1c2ab3d4e5f601234567",
    "properties": {
      "email": "[email protected]",
      "firstname": "Ada",
      "lastname": "Lovelace"
    },
    "associations": { "companies": ["665f1c2ab3d4e5f6012345aa"] },
    "first_seen_at": "2026-10-12T10:00:00.000Z",
    "segment_ids": [],
    "creation_source": "manual",
    "created_at": "2026-10-12T10:00:00.000Z",
    "updated_at": "2026-10-12T10:00:00.000Z",
    "notes": [],
    "tags": []
  },
  "timestamp": "2026-10-12T10:00:00.000Z"
}

_id is a transitional alias for contact_id and will be removed in a future release. Prefer contact_id in new integrations.

Without external_id, returns 409 Conflict if a contact with the same email already exists. The response carries that contact’s id as contact_id, so you can update it instead.

POST /v1/contacts/bulk

Required scope: contacts:write

Creates up to 1,000 contacts in one request. It is safe to send the same list twice: a contact whose email already exists is reported as existing and is not changed. An item with an external_id is an upsert on it, as on Create a Contact, and comes back created or updated. One bad item never fails the others.

curl -X POST https://api.pathbound.ai/v1/contacts/bulk \
  -H "Authorization: Bearer $PATHBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "email": "[email protected]", "properties": { "firstname": "Ada" }, "tags": ["webinar-oct"] },
      { "email": "[email protected]", "properties": { "firstname": "Grace", "lifecyclestage": "lead" } },
      { "email": "not-an-email" }
    ]
  }'

{
  "status": "success",
  "requested": 3,
  "created": 1,
  "updated": 0,
  "existing": 1,
  "errors": 1,
  "results": [
    { "index": 0, "email": "[email protected]", "status": "existing", "id": "665f1c2ab3d4e5f601234567" },
    { "index": 1, "email": "[email protected]", "status": "created", "id": "665f1c2ab3d4e5f601234568" },
    { "index": 2, "email": "not-an-email", "status": "error", "error": "Valid email is required" }
  ],
  "timestamp": "2026-10-12T10:00:00.000Z"
}

results has one entry per item you sent, in the same order, and index is the item’s position in your array. An entry’s status is created, updated (an item with an external_id that found its contact), existing (an item without one whose email exists) or error, with the code of Create a Contact when it has one, and skipped_traits when a field was not written. The request is a 200 even when some items failed, so read errors and the entries with "status": "error". A 429 with code: "QUOTA_EXCEEDED" means the new contacts in the batch would take the workspace past its limit; an item that updates a contact through its external_id does not count toward it.

Visitor ids are not bound by this endpoint. To tie a visitor to a contact, use Create a Contact, Update a Contact or POST /v1/identify.

GET /v1/contacts

Required scope: contacts:read

The has_event_* filters return the contacts who performed a matching tracked event. For example ?has_event_type=button_click&has_event_text=Go! lists the known people who clicked the Go! button. They compose with every other filter (&lifecycle_stage=lead), with count_only, and with pagination/sorting. Notes:

• Identified contacts only. Events are matched by their linked contact, so anonymous visitors never appear. To count distinct visitors (identified + anonymous), use POST /v1/aggregate with group_by=visitor_id.
• Scope: using any has_event_* filter requires events:read in addition to contacts:read.
• If an event filter matches an unusually large number of contacts, the request returns 400. Narrow it with has_event_after / has_event_before.

Every listed contact carries email_verification_state, the deliverability verdict on file (deliverable, undeliverable, risky, unknown, or null when nobody has verified the address). It is the verdict whoever reached it: Emailable, or a data provider such as Hunter that verified the address it found. emailable: { state, score } | null adds Emailable’s own detail and is null for an address Emailable did not check. The email_verification_state query parameter filters on the verdict server-side, so ?email_verification_state=deliverable&count_only=true answers “how many contacts are safe to email” without paging any records. The finer verdict fields (score, reason, role, free, disposable, accept_all, smtp_provider) are available through filters as emailable.<field> once Emailable is connected.

{
  "status": "success",
  "contacts": [
    {
      "contact_id": "665f1c2ab3d4e5f601234567",
      "_id": "665f1c2ab3d4e5f601234567",
      "properties": { "email": "[email protected]", "firstname": "Ada", "lastname": "Lovelace" },
      "associations": { "companies": ["665f1c2ab3d4e5f6012345aa"] },
      "first_seen_at": "2026-09-15T10:00:00.000Z",
      "created_at": "2026-09-15T10:00:00.000Z",
      "updated_at": "2026-10-12T10:00:00.000Z",
      "tags": ["webinar-oct"],
      "emailable": { "state": "deliverable", "score": 97 }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total_pages": 10,
    "total_items": 100
  },
  "timestamp": "2026-10-12T10:00:00.000Z"
}

_id is a transitional alias for contact_id and will be removed in a future release.

With fields=summary each row is flat:

{
  "contact_id": "665f1c2ab3d4e5f601234567",
  "_id": "665f1c2ab3d4e5f601234567",
  "email": "[email protected]",
  "firstname": "Ada",
  "lastname": "Lovelace",
  "company": "Analytical Engines",
  "lifecyclestage": "customer",
  "last_activity_at": "2026-10-12T10:00:00.000Z",
  "emailable": { "state": "deliverable", "score": 97 },
  "email_verification_state": "deliverable",
  "tags": ["webinar-oct"]
}

With fields=ids each row is { "contact_id", "_id" } and the page does not count against your plan. A page in any other shape counts every contact on it as read. To walk a large list cheaply, filter with fields=ids and read what you need through the batch API.

For a “how many” question, prefer count_only=true.

Pass emails, a comma-separated list of up to 50 addresses, to learn which of them are already contacts. This is the cheap way to avoid creating duplicates before an import. It is free, and it matches the whole address exactly after normalizing it, unlike search.

curl -G https://api.pathbound.ai/v1/contacts \
  -H "Authorization: Bearer $PATHBOUND_API_KEY" \
  --data-urlencode "[email protected],[email protected]"

{
  "status": "success",
  "mode": "exists",
  "requested": 2,
  "found": 1,
  "results": [
    { "email": "[email protected]", "exists": true, "id": "665f1c2ab3d4e5f601234567" },
    { "email": "[email protected]", "exists": false, "id": null }
  ],
  "timestamp": "2026-10-12T10:00:00.000Z"
}

Addresses past the 50th are not checked, and the response then carries "truncated": true.

GET /v1/contacts/:contact_id

Required scope: contacts:read

Returns the contact along with its unified profile and (optionally) recent events.

{
  "status": "success",
  "contact": {
    "contact_id": "665f1c2ab3d4e5f601234567",
    "_id": "665f1c2ab3d4e5f601234567",
    "properties": { "email": "[email protected]", "firstname": "Ada", "lastname": "Lovelace" },
    "associations": { "companies": ["665f1c2ab3d4e5f6012345aa"] },
    "_summary": "Ada Lovelace | CTO | at Analytical Engines | London | Stage: customer",
    "created_at": "2026-09-15T10:00:00.000Z",
    "updated_at": "2026-10-12T12:00:00.000Z"
  },
  "unified_profile": {
    "_id": "665f1c2ab3d4e5f601234567",
    "source_count": 3,
    "sources": {
      "internal": { "id": "665f1c2ab3d4e5f601234567", "updated_at": "...", "first_seen_at": "..." },
      "hubspot": { "id": "12345", "synced_at": "...", "first_seen_at": "..." },
      "apollo": { "id": "ap_678", "enriched_at": "..." }
    },
    "profile": {
      "email": {
        "unique_values": [
          { "value": "[email protected]", "sources": [{ "source": "hubspot", "updated_at": "..." }, { "source": "apollo", "updated_at": "..." }] }
        ],
        "all_sources": ["hubspot", "apollo"],
        "has_conflict": false
      },
      "jobtitle": {
        "unique_values": [
          { "value": "CTO", "sources": [{ "source": "hubspot", "updated_at": "..." }] },
          { "value": "Chief Technology Officer", "sources": [{ "source": "apollo", "updated_at": "..." }] }
        ],
        "all_sources": ["hubspot", "apollo"],
        "has_conflict": true
      }
    },
    "created_at": "...",
    "updated_at": "...",
    "enriched_at": "..."
  },
  "events": [
    { "event_id": "665f1c2ab3d4e5f6012345e1", "_id": "665f1c2ab3d4e5f6012345e1", "event": "page_view", "timestamp": "...", "url": "...", "title": "..." }
  ],
  "total_events": 42,
  "timestamp": "2026-10-12T12:00:00.000Z"
}

_summary is a human-readable one-liner the backend stitches together from the contact’s name, title, company, industry, location, and lifecycle stage. Parts are joined with | and prefixed where applicable (at <company>, Stage: <stage>). Convenient for list views, but not a stable contract, so don’t parse it.

unified_profile is the full deduplicated cross-source profile. Each profile field is a multi-source object: unique_values holds every distinct value found across sources (deduplicated), each annotated with the sources that supplied it; all_sources lists every source that had any value for the field; and has_conflict is true when sources disagree (more than one distinct value). sources is a per-source map (presence, external IDs, and sync/enrichment timestamps), and source_count is how many sources contributed. Pass ?include=raw to additionally get raw_data, the verbatim, un-deduplicated per-source field dumps. events is a compact projection of the contact’s most recent events and is omitted (along with total_events) when the request is made with ?include_events=false.

When PII redaction is enabled for an AI-agent (MCP) caller, the personal values inside unified_profile.profile are masked (the field and its source attribution remain visible) and raw_data is never returned, even with ?include=raw. An API key is never redacted.

PUT /v1/contacts/:contact_id

Required scope: contacts:write

To change a contact’s lifecycle stage, set properties.lifecyclestage to one of the allowed values.

The response is the updated contact, in the shape of Create a Contact.

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

DELETE /v1/contacts/:contact_id

Required scope: contacts:write

Permanently removes the contact and its notes. The contact’s events are kept. This cannot be undone.

An AI agent connected through the MCP server cannot call this endpoint: it is answered 403 with the code AGENT_DELETE_FORBIDDEN. An API key can.

GET /v1/contacts/events/:contact_id

Required scope: events:read

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

{
  "status": "success",
  "events": [
    {
      "event_id": "665f1c2ab3d4e5f6012345e1",
      "_id": "665f1c2ab3d4e5f6012345e1",
      "event": "page_view",
      "timestamp": "2026-10-12T11:23:45.000Z",
      "url": "https://example.com/pricing",
      "domain": "example.com",
      "data": { "title": "Pricing — Example", "path": "/pricing" }
    }
  ],
  "contact_id": "665f1c2ab3d4e5f601234567",
  "total_items": 212,
  "returned": 50,
  "timestamp": "2026-10-12T12:00:00.000Z"
}

total_items is how many events match in all, and returned how many are in this response. Ask for the next page with offset raised by limit until you have total_items.

GET /v1/contacts/:contact_id/conversations

Required scope: contacts:read

Returns the contact’s conversation history, one block per channel: email (Gmail/SMTP), intercom, hubspot (logged 1:1 emails), instantly (cold-email messages), and meetings (tl;dv recordings and Calendly bookings). Each block has its own conversations[] and pagination. Blocks for integrations that aren’t connected come back empty.

The same history across everyone at a company is GET /v1/companies/:company_id/conversations.

With include_messages=true, an Intercom conversation’s parts start with its opening message (part_type: "source", dated with the conversation’s created_at), followed by the conversation parts in order.

A tl;dv meeting in the meetings block reports has_transcript, transcript_segment_count, and has_notes. Read the transcript itself with Get Meeting Transcript. To read notes from many meetings at once, use POST /v1/meetings/query.

GET /v1/contacts/:contact_id/meetings/:meeting_id/transcript

Required scope: contacts:read

Returns one page of a tl;dv recording’s transcript. meeting_id is the _id of a meeting in the meetings block of the conversations endpoint, and contact_id must be a contact who was on the call. Any other combination returns 404. Calendly bookings have no transcript.

Pages are cut by size, not by segment count. To read the whole transcript, pass each response’s next_offset back as offset until next_offset is null.

{
  "status": "success",
  "contact_id": "665f1c2ab3d4e5f601234567",
  "meeting": {
    "_id": "6650f1c2e4b0a1b2c3d4e5f6",
    "name": "QBR — Acme",
    "happened_at": "2026-09-22T15:00:00.000Z",
    "duration_seconds": 2280
  },
  "transcript": {
    "segments": [
      { "speaker": "Dana Lee", "start_time": 0, "text": "Thanks for making time today." },
      { "speaker": "Sam Ortiz", "start_time": 4, "text": "Happy to. Let's start with the security review." }
    ],
    "offset": 0,
    "returned": 2,
    "total_segments": 412,
    "next_offset": 2
  }
}

start_time is seconds from the start of the recording. A meeting with no transcript returns an empty page with unavailable_reason: not_available (tl;dv hasn’t produced one yet) or access_denied (tl;dv refused this connection access to the recording).

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

Required scope: contacts:read

Returns a compact list of the contact’s Gmail threads, in threads. count is the number of threads in this response, at most limit: it is not the contact’s total, and no total is returned. Each entry names the thread and its last message, which is what you need to reply inside a thread.

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

GET /v1/contacts/:contact_id/notes

Required scope: contacts:read

POST /v1/contacts/:contact_id/notes

Required scope: contacts:write

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

Required scope: contacts:write

Takes the same body as Create a Note and replaces the note’s text.

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

Required scope: contacts:write