Lead Identifier ​

Every telecrm workspace has a single lead identifier — a field whose value uniquely identifies a lead. The identifier drives the create-or-update behavior of the Async API and underpins lead lookups in the Sync API.

Allowed identifier types ​

The lead identifier can be set to a field of one of three types:

TypeExample value
phone"919999999999"
email"jane.doe@example.com"
text"CUST-04821"

The default for a new workspace is phone.

See Field Types for the full input rules of each type.

Configure the identifier ​

The identifier is set per workspace and applies to every lead created from any source — API, dashboard, or integration.

  1. Go to Settings → Lead Fields.
  2. Open the field you want to use as the identifier.
  3. Enable Use as lead identifier.
  4. Save.

WARNING

Changing the identifier mid-flight affects how the Async API matches incoming leads. Coordinate the change with any active integrations.

Why every payload must include it ​

The identifier is the key telecrm uses to decide whether to create a new lead or update an existing one.

  • Match found — the existing lead is updated with the supplied fields. Fields not present in the request are left unchanged.
  • No match — a new lead is created.
  • Identifier missing from the payload — the lead is silently dropped on the Async API.
json
{
  "fields": {
    "phone": "919999999999",
    "name": "Jane Doe"
  }
}

The first key (phone here) is the identifier; the rest are optional updates.

Matching rules ​

  • Matching is exact and case-insensitive.
  • For phone identifiers, the value is normalized to country code + national number before matching. +919999999999, 919999999999, and (with workspace default country code IN) 9999999999 all match the same lead.
  • For email identifiers, leading/trailing whitespace is trimmed; case is ignored.
  • For text identifiers, the comparison is character-for-character (case-insensitive).

Finding the identifier in your workspace ​

  1. Go to Settings → Lead Fields.
  2. The field marked Lead identifier is the one currently in use.
  3. Note its API name under Properties — that's the key you'll send in the payload's fields object. See Field API Names.