Skip to main content

leads

Create, update, and query leads.

📄️Generate an AI opening line for a lead

Forces a fresh AI-drafted opener for this lead's next message, based on its existing reply/message thread, unless `auto` is set. Pass `offer` to write it for that offer profile and keep it on the lead, so later replies are written for the same offer. Without it, the offer previously picked for the lead is used, then the one linked to the lead's workspace, then the organization's only offer. Fails if the lead has no conversation to write from, if no offer profile can be resolved for it, or if the daily opener limit is reached. Returns the lead with the generated opener attached.

📄️Bulk create or update leads

Imports up to 10,000 leads in one request: rows matching an existing lead's dedupe key within the same workspace are merged into it (unless the names conflict, in which case a new lead is created instead), everything else is created fresh, and malformed rows are skipped rather than failing the whole batch. The response breaks out `totalRows`/`validRows`/`totalCreated`/`totalUpdated`/`duplicates` so the caller can report partial-success detail; `leads` returns only the rows that were actually created or updated.

📄️Count leads by timezone

Counts leads matching the given filters (the same filter fields as `list`), grouped by the lead's resolved IANA timezone and UTC-offset key, so a caller can preview how a call window maps across the current lead set before dialing. `unknownCount` is leads whose timezone could not be resolved from their phone number (e.g. no primary phone, or a country not covered by our timezone data) - they never match any calling-hours window, so callers should surface this separately rather than let them silently vanish from the breakdown.

📄️Get the next leads to call by priority

Walks the caller's configured call priority tiers in order and returns the first eligible leads: callable phone, not booked/excluded, not locked by another rep, past the tier's attempt buffer and limits, inside the configured calling hours. Scoped to the given workspaces (or everything the caller can see when none are given). `exclude` drops leads already dialed in the current session. `relax` ignores the per-tier attempt buffers and limits; `coolingDown` counts the leads that only those rules hold back, computed when nothing is eligible. `ignoreCallHours` ignores the configured calling-hours windows.