Contact lists and leads

A lead is a person in a contact list: one or more phone numbers, free-form custom fields, a time zone, and consent and registry-check flags. A campaign draws its leads from one list and can filter them and set the dialing order.

From source to campaign

Step	What happens
CSV import (source)	Column mapping, E.164 normalization, de-duplication, DNC flag, error report
Integration API (source)	Batch upload from your CRM, idempotent by customer ID (externalId)
Contact list	Leads, phones (mobile, home, work, other), custom fields
Lead selection (campaign)	A "field, operator, value" filter (conditions combined with AND only), sort on up to 4 fields, an "N of M leads match" preview

Contact lists

A list has a name, a default country (the two-letter code used to read a local phone number as E.164 when the lead carries no country of its own) and a default timezone (the IANA zone used for calling windows when the lead carries no timezone). It also declares its custom columns: key, label and type (text, number or date). A CSV import declares columns as it finds them; the type decides which operators the lead selection offers for that field.

A list that a campaign still dials cannot be deleted; point the campaign at another list first.

CSV import

The import wizard takes a UTF-8, comma-separated file whose first row is the header.

• Mapping. The dialer recognises common English and Hebrew headers and proposes a lead field for each column; you check each column and pick the field it fills, a custom field, or Ignore. Lead fields: customer ID (externalId), first name, last name, full name, phone, home phone, work phone, other phone, timezone, country, consent date, existing customer, and the national do-not-call registry flag. Columns the dialer does not know are kept as custom fields.
• At least one phone column must be mapped, or every row would be rejected.
• Merge rows matching an existing phone number. With this option, rows without a customer ID are matched by phone instead of creating a duplicate lead.
• Result. Rows, imported, merged, rejected, and on DNC. Download the rejected rows to see why each one failed, fix them and import that file again.

Lead selection

The campaign's lead filter decides which leads of the list the campaign enrols. Each condition is a field, an operator and a value; conditions are combined with AND. Operators: is, is not, greater than, at least, less than, at most, is one of, contains, is set. Fields are the lead fields (first name, last name, country, existing customer, on the do-not-call registry, consent date, added to the list, and so on) and the list's custom fields (custom.<key>).

The dial order sorts enrolled leads on up to 4 fields, ascending or descending. With no order set, leads are enrolled in no particular order.

Working the leads

• Phone order. A lead's numbers are dialed by type in phoneOrder: mobile, home, work, other by default. SMS and WhatsApp prefer mobile numbers.
• Sync. New leads from the list can be added to a running campaign with Sync from contact list (or through the API). A dry run first shows how many match the filter, how many are already in the campaign and how many will be enrolled. For one sync you can override the filter or cap how many leads are enrolled, without changing the campaign settings.
• Priority between campaigns. Each campaign has a priority (1 to 5) and a weight. When campaigns compete for calls per second (CPS), lines and shared agents, the highest priority is served first and campaigns of the same priority split by weight.

Lead lifecycle in a campaign

Every lead in a campaign has a status. The cycle is shared by voice and messaging; only what counts as a result differs.

Claim is an exclusive reservation: the dialer takes leads with status ready whose next attempt is due, ordered by priority and due time, and a lead is never claimed twice at once. Messages skip in_progress: a delivered message moves the lead straight from dialing to done.

owned is the status of a lead waiting for a callback that belongs to one agent; the leads table shows it as "Reserved for agent".

Attempts that do not count

The attempt counter does not move when the dialer failed to reach the customer through its own fault: the call was canceled (canceled), no agent was available before dialing (agent_unavailable), the agent left while the customer's phone was ringing (agent_abandoned), or the customer waited out the hold ceiling (hold_timeout, which also books a callback). The lead goes straight back to ready.

See Outcomes and retries for the retry rules, and Compliance and calling hours for the checks every claim goes through.