Search contacts

GET

/api/contacts

• Production

Searches contacts by name or email address. Returns all matching contacts. If no search query is provided, returns all contacts in the tenant.

Authorizations

• bearerAuth

Parameters

Query Parameters

q

string

Search query to match against contact names and email addresses. Case-insensitive partial matching.

Example

mueller

Responses

200

Contacts matching the search query. Returns an empty array if no matches are found.

List of contacts matching the search criteria.

Array<object>

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

Jan

lastName

Last name of the contact.

string | null

Example

Mueller

email

Primary email address of the contact.

string | null

Example

jan.mueller@acme-customer.de

phone

Phone number of the contact in E.164 format.

string | null

Example

+4915112345678

companyName

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

string | null

Example

Acme Customer GmbH

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