Skip to main content
GET
List leads

Authorizations

X-API-Key
string
header
required

API key prefixed with nl_live_ or nl_test_

Query Parameters

statuses
string

Comma-separated outreach statuses to filter by (new, contacted)

Example:

"new,contacted"

tags
string

Comma-separated list of tags to filter by

Example:

"vip,hot"

channel
string

Channel to filter by

page
integer
default:1

Page number (list / sync mode)

Required range: x >= 1
limit
integer
default:50

Page size. Campaign preview mode default 50; list / sync mode default 25.

Required range: x <= 100

Search name, phone, or email (list / sync mode)

status
enum<string>

Single outreach status filter (new or contacted) Outreach I/O state for the lead — whether Naturalead has performed contact yet. This is not journey position. Journey position lives on the conversation as currentStage / currentStageName.

Available options:
new,
contacted
sortBy
enum<string>
default:updatedAt

Sort field (list / sync mode)

Available options:
id,
name,
status,
createdAt,
updatedAt
sortOrder
enum<string>
default:desc
Available options:
asc,
desc
updatedAfter

Return only records with updatedAt strictly after this timestamp. Accepts ISO 8601 (2026-06-01T00:00:00Z) or Unix epoch (seconds or milliseconds). Use for incremental sync; lead updatedAt is also bumped when related conversations change.

Example:

"2026-06-01T00:00:00Z"

updatedBefore

Return only records with updatedAt strictly before this timestamp. Same formats as updatedAfter.

Example:

"2026-07-01T00:00:00Z"

Response

Without filters: a plain array of leads. With list/preview filters: a paginated or preview object.

id
integer
required

Sequential, account-scoped identifier

name
string
required
phone
string
required

Unique per account

email
string
default:""
required
status
enum<string>
required

Outreach I/O state for the lead — whether Naturalead has performed contact yet. This is not journey position. Journey position lives on the conversation as currentStage / currentStageName.

Available options:
new,
contacted
accountId
string
required
source
string
default:api
tags
string[]
assignedAgentId
string

ObjectId reference to AgentConfig

abTestId
string

ObjectId reference to AbTest

agentAssignedBy
enum<string>
default:auto
Available options:
manual,
ab_test,
auto
customFields
object

Key-value string map of custom fields

lastContactedAt
string<date-time>
importBatchId
string
externalId
string
currentStage
object

Present on list responses enriched with the latest conversation stage

createdAt
string<date-time>
updatedAt
string<date-time>

Last modification time. Also bumped when related conversation activity occurs, so incremental polls with updatedAfter see conversation changes.