leads
Create, update, and query leads.
List leads
Lists leads for an organization, paginated and sortable, filterable by any combination of the fields in the querystring (free-text search, status, folder, age bucket, call-hours window, GHL tags, campaign, dial status, and due-callback state). Array-valued filters (e.g. `status`, `leadFolders`, `campaign`) are OR-ed together within the field, and every filter field supplied is AND-ed together.
Delete leads
Permanently deletes multiple leads by ID.
Create a lead
Creates a single lead for the organization.
Bulk edit leads
Applies the same partial field update (any subset of editable lead fields, e.g. `status`, `assignedTo`, `leadFolders`) to every lead in `ids` in one request. Unset fields in `update` are left untouched on each lead; this is a merge, not a replace.
Edit a lead
Updates editable fields on a single lead.
Get a lead
Fetches a single lead by its ID or by phone number.
Delete a lead
Permanently deletes a single lead.
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.
Bulk update leads
Applies the same partial field update (any subset of editable lead fields, e.g. `status`, `assignedTo`, `leadFolders`) to every lead in `ids` in one request. Unset fields in `update` are left untouched on each lead; this is a merge, not a replace.
Export leads to CSV
Streams back a CSV of the given leads, with one column per entry in `headers`. `headers` takes dotted paths rather than top-level keys so nested fields (e.g. custom data) can be exported individually.
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.
List GoHighLevel tag options
Lists the distinct GoHighLevel tags present across the organization's leads, for use in filters.
List campaign options
Lists the distinct campaigns leads originated from, each tagged with its source platform (e.g. Instantly, Smartlead, HeyReach), optionally scoped to a single workspace. Intended to populate the `campaign` filter used by `list` and `timezoneCounts`.
List dial status options
Lists the distinct LeadHero dial statuses present across the organization's leads, for use in filters.
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.
Sync a lead to HeyReach
Adds a lead to its mapped HeyReach campaign.
Schedule a callback
Sets a lead's next callback date (and an optional note), removing it from the redial queue until that date passes.
List scheduled callbacks
Lists leads with a scheduled callback. By default this is scoped to leads visible to the caller (their own, plus shared/unassigned leads); `rep` widens that to one specific rep's callbacks or every rep's callbacks, but only for owners/managers.
Cancel a scheduled callback
Clears a single lead's scheduled callback entirely (manual or automated), reverting its status to what it was before the callback was scheduled.
Cancel scheduled callbacks
Clears the scheduled callback on multiple leads entirely (manual or automated), reverting each lead's status to what it was before its callback was scheduled.
Ignore a scheduled callback
Pushes a single lead's automated no-pickup redial to its next cycle instead of canceling it outright. Only valid for automated redials (`nextCallSource: 'auto-no-pickup'`); manually scheduled callbacks must be canceled instead.
Ignore scheduled callbacks
Pushes each automated no-pickup redial in `ids` to its next cycle instead of canceling it outright. IDs that are not automated redials (e.g. manually scheduled callbacks) are silently skipped rather than erroring, so a bulk 'mute all' over a mixed selection still mutes every eligible one.
Uploads
2 items
Folder
2 items