Contacts are an organization-wide address book shared across every agent. Each contact aggregates a person or company — names, emails, phones, domains, addresses — and is visible to every agent in your org by default. Narrow that visibility per agent when you need to, or keep the wildcard and let every agent see every contact.

The minimum is one non-empty name field: given_name, family_name, company_name, or preferred_name. Emails and phones are validated client-side before the request leaves the SDK.

When an email or call comes in, you usually want to know who it's from before deciding how your agent should respond. contacts.lookup runs a reverse search by exact email, email substring, email domain, exact phone, or phone substring. Exactly one filter is required per call.

Contacts created through the SDK default to the wildcard rule: every active agent in your org can see them. This matches how a shared address book usually works.

To narrow the visibility of a contact to a specific set of agents — for example, to keep customer contacts separate from vendor contacts — create the contact with an explicit access_identity_ids list, or revoke agents from an existing contact. Note that revoking an identity from a wildcard contact automatically fans the wildcard out into per-identity rows for every other active agent before dropping the revoked one, so the narrowing is atomic.

Round-trip contacts through the RFC 6350 vCard format to migrate from Apple Contacts, Google Contacts, LinkedIn exports, or any other address book. Bulk import handles up to 1000 cards per request with per-card isolation: one bad card doesn't poison the rest, and the response breaks down created_count / error_count plus per-card errors.

• Contacts API reference
• Access control reference
• vCard import/export reference