> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Understand contacts, API resource identifiers, and external identity in the REST API.

A contact is the canonical person record within one organization, used by calls, batches, and Automation runs. Resource IDs are opaque; store the returned `id` and do not infer meaning from its format.

## Contact references

Execution requests accept either an existing `contact_id` or an inline `recipient`. An inline recipient includes an `external_id`, `name`, and `phone_number`, and may include the other supported contact fields. Brightalk resolves it to one canonical contact and returns that `contact_id` on the execution resource.

`external_id` is the caller-managed identity within its `source` namespace. Use a stable value from your own system rather than a display name or mutable phone label.

## Adoption and conflict rules

When creating or resolving an inline recipient, Brightalk applies these rules atomically:

1. A matching external identity resolves to its existing canonical contact.
2. A matching normalized phone may adopt the requested external identity only when the existing contact has no external identity.
3. If that phone already belongs to a different nonempty external identity, the request returns `409 contact_identity_conflict` and overwrites neither identity.
4. Otherwise, the supported fields create a new contact.

`POST /contacts` returns `201` for a new contact and `200` for an existing or adopted contact. Unknown fields are rejected.

## Phone format and organization isolation

`phone_number` must be strict E.164: a leading `+`, a nonzero country code, and 8–15 total digits. Syntactic validity does not guarantee that an organization is enabled to dial that destination; execution can fail safely with `unsupported_destination`.

Identity lookup, phone collisions, and resource access are isolated by organization. A request cannot merge contacts across organizations or choose an organization through a request field.