Skip to main content
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.