Get contact by ID

GET

/api/contacts/{id}

• Production

Retrieves a single contact by its unique identifier, including all known information such as name, email, phone, company, and resolution status.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

The unique identifier of the contact to retrieve.

Responses

200

The contact was found and returned.

A contact represents an individual person who has communicated with your organization. Contacts are automatically created when a new sender is detected, and enriched over time with additional information from conversations and account resolution.

object

id

required

Unique identifier for the contact.

string format: uuid

Example

ct1a2b3c-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this contact belongs to.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

externalRef

External CRM identifier. Set when this contact is resolved against a CRM system via an MCP server.

string | null

Example

CRM-CONTACT-78291

resolutionStatus

required

How the contact was identified. ‘unresolved’ means no CRM match was found yet. ‘crm_resolved’ means the contact was matched to a CRM record via an MCP server. ‘manually_resolved’ means a human agent linked the contact manually.

string

Example

crm_resolved

firstName

First name of the contact.

string | null

Example

Alex

lastName

Last name of the contact.

string | null

Example

Doe

email

Primary email address of the contact.

string | null

Example

alex.doe@example.com

givenEmail

The email address the visitor typed in a live chat, at its start or in the email field the chat shows. It is not verified. Present only when the visitor gave one.

string

Example

alex.doe@example.com

phone

Phone number of the contact in E.164 format.

string | null

companyName

Company name associated with this contact, derived from email domain or CRM resolution.

string | null

Example

Example Company

createdAt

required

Timestamp when the contact was first detected.

string format: date-time

Example

2026-02-10T14:30:00.000Z

updatedAt

required

Timestamp when the contact was last updated.

string format: date-time

Example

2026-03-20T09:15:00.000Z

404

No contact exists with the given ID in the authenticated tenant.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]