Upserts (creates or updates) a Talkdesk contact by matching on the combination of integration_id and external_id. If a contact with the given integration mapping already exists, it is updated; otherwise a new contact is created.

Brand Sentinel Mechanism

The custom_fields array is the mechanism for identifying which store/brand a contact belongs to. The brand sentinel is a custom field entry with key = external_id and value = the brand/store identifier. When the brand sentinel is present in the request body:

1. When multiple contacts match the same integration_id + external_id, the brand
   sentinel is used to disambiguate — the service selects the contact whose
   custom_fields contain the matching brand sentinel for update.

2. If a single match exists but its brand sentinel differs from the one in the
   request body, the contact is treated as a non-match and the system falls through
   to the no-match logic (see existing_contact_id below).

3. An empty brand sentinel value is treated as "no brand" (same as omitting it).

Contact Resolution Logic

The service resolves which contact to create or update based on the following decision tree:

• Multiple matches (matched > 1):

  • If brand sentinel present in request body → select the contact matching the brand; update it.
  • If no brand match found → fall through to no-match logic.
  • If brand sentinel not present → return matches as-is (no update performed).

• Single match (matched == 1):

  • If brand sentinel not present → update the matched contact.
  • If brand sentinel present and contact has no brand sentinel → adopt the brand and update.
  • If brand sentinel present and sentinel matches → update.
  • If brand sentinel present and sentinel differs → treat as no-match (fall through).

• No match (matched == 0, or delegated from above):

  • If existing_contact_id provided → attempt to reuse that contact (merge), unless
    it already has a conflicting integration for the same integration_id (in which
    case a new contact is created instead).
  • If existing_contact_id not provided → create a new contact.

Merge Strategy (when updating)

• custom_fields: key-based merge — matching keys are overwritten, new keys are appended,
  absent keys are preserved.

• integrations: matched by integration_id + external_id pair; existing entries are
  updated, new entries are appended.

• Scalar fields (name, address): overwritten if provided, preserved if omitted (null).

• Array fields (tags, emails, phones): replaced entirely if provided.

Request Body Validation

• contact.id must be empty (omit it or set to null).
• contact.integrations must contain at least one entry with integration_id and
  external_id matching the path parameters — otherwise 400 is returned.