Skip to main content
Contacts hold a person’s names, summary, stable identities, facts, and conversation history inside one organization. The verified credential supplies the organization; requests never accept an orgId that can switch tenants.

​
Search and browse

Use listContacts for both browsing and free-text search. Pass query to match names, summary text, phone numbers, email addresses, or document identities. Matching is case- and accent-insensitive.
Continue with nextCursor using the same query, sort, and filters. See Pagination.

​
Read a contact and its timeline

getContact returns the contact, its identities and facts, and the first page of its conversation timeline. Set timelineLimit to control that embedded page and use timelineCursor to request the next one. This keeps the contact and its recent activity in one read. There is no separate public timeline operation.

​
Import a remote CSV

importContacts accepts two inputs:
  • csvUrl: a direct HTTPS URL to a CSV file;
  • fieldMapper: the exact CSV headers that map to Contact fields.
At least one stable identity column—phone, email, or document—is required. Each source column can map to only one field. Keys inside facts are active Contact Definition identifiers; their values are CSV headers.
The API returns 202 Accepted with an importId and status: "queued". A durable Workflow downloads and validates the file, then imports at most 500 rows and 2 MB. Existing contacts are matched within the organization by normalized phone, email, or document identity; ambiguous matches are not guessed.
The source URL must return the CSV directly without redirects and remain available while the Workflow starts. Keep the importId for support and request correlation.

​
Merge duplicates

Use mergeContacts only after choosing one primary and one secondary Contact. The operation moves compatible identities and facts to the primary Contact, redirects owned relationships, and retires the secondary Contact. An identity conflict returns 409 instead of choosing an owner implicitly.