GET /leads

Required. /leads returns your leads. It is incremental and syncs after /pipelines, so each lead’s won/lost can be resolved from its stage.

Purpose

A lead is one sales opportunity in your CRM. HunterAI reads /leads to compute revenue, win-rate, conversion, and goal progress (from the lead’s value, its stage, and its timestamps), traffic and source analytics (from source and the utm fields), loss analysis (from loss_reason), and per-manager and per-contact attribution. This is the highest-value endpoint: if it is empty, almost every metric is empty.

Request

GET /api/hunterai/v1/leads?limit=100&page=1&updated_since=2025-07-01T00:00:00+05:00 HTTP/1.1
Host: crm.example.uz
Authorization: Bearer <token>
Accept: application/json

Query param	Value	Notes
`limit`	`100`	Always sent. Return up to this many leads per page.
`page`	`1`, `2`, …	1-based. Page until `has_more` is `false`.
`updated_since`	timestamp	Return leads with `updated_at >= updated_since` (inclusive).

You must return the leads ordered by updated_at ascending. HunterAI advances its watermark page by page and relies on that order; an out-of-order page can cause older leads on a later page to be skipped.

Response envelope

200 OK

{
  "data": [
    {
      "id": "L-9001",
      "name": "Toshkent ofis — 20 litsenziya",
      "price": 48000000,
      "pipeline_id": "pipe-sales",
      "stage_id": "stg-won",
      "responsible_user_id": "u-1001",
      "contact_ids": ["c-5001", "c-5002"],
      "loss_reason": null,
      "source": "instagram",
      "utm": {
        "source": "instagram",
        "medium": "cpc",
        "campaign": "summer-2025",
        "content": "banner-a",
        "term": null
      },
      "custom_fields": { "employees": "20", "sector": "retail" },
      "created_at": "2025-06-28T10:00:00+05:00",
      "updated_at": "2025-07-02T16:45:00+05:00",
      "closed_at": "2025-07-02T16:45:00+05:00",
      "is_deleted": false
    },
    {
      "id": "L-9002",
      "name": "Samarqand filiali",
      "price": 12500000,
      "pipeline_id": "pipe-sales",
      "stage_id": "stg-lost",
      "responsible_user_id": "u-1002",
      "contact_ids": ["c-5003"],
      "loss_reason": "Byudjet yetarli emas",
      "source": "referral",
      "utm": {
        "source": "referral",
        "medium": "partner",
        "campaign": "q3-partners",
        "content": null,
        "term": null
      },
      "custom_fields": { "sector": "manufacturing" },
      "created_at": "2025-06-25T09:00:00+05:00",
      "updated_at": "2025-07-03T11:20:00+05:00",
      "closed_at": "2025-07-03T11:20:00+05:00",
      "is_deleted": false
    }
  ],
  "has_more": false,
  "page": 1,
  "limit": 100
}

The envelope (data, has_more, page, limit) is the same on every endpoint — see How sync works → The envelope. Only data and has_more are read.

Fields

Field	Type	Required	Nullable	Format / Constraint	Example	Notes
`id`	string	Yes	No	max 255 chars; stable and unique per connection; never changes for the same lead	`"L-9001"`	The upsert key together with the connection. An absent or over-length `id` fails its page.
`name`	string	No	Yes	max 255 chars	`"Toshkent ofis — 20 litsenziya"`	Silently truncated to 255 chars.
`price`	number	No	No	numeric; may be sent as a numeric string (`"48000000"`); must be numeric if present	`48000000`	Stored as a whole number — any fractional part is dropped. Currency is not stored. A non-numeric value is rejected.
`pipeline_id`	string	No	Yes	must match an `id` from `/pipelines`	`"pipe-sales"`	The lead’s pipeline.
`stage_id`	string	No	Yes	must match a stage `id` returned by `/pipelines`	`"stg-won"`	Sets won/lost via the stage’s `kind`.
`responsible_user_id`	string	No	Yes	must match an `id` from `/users`	`"u-1001"`	The owning manager; drives per-manager attribution.
`contact_ids`	array<string>	No	Yes	each element a contact `id` from `/contacts`	`["c-5001", "c-5002"]`	Only the first element is kept; the rest are ignored.
`loss_reason`	string	No	Yes	max 500 chars	`"Byudjet yetarli emas"`	Free text. HunterAI derives a de-duplicated loss-reason record from it; identical text maps to the same record. Truncated to 500.
`source`	string	No	Yes	max 255 chars	`"instagram"`	Free-text lead source. Truncated to 255.
`utm`	object	No	Yes	container for the five UTM sub-fields below	`{ "source": "instagram", "medium": "cpc", "campaign": "summer-2025", "content": null, "term": null }`	Attribution container.
`utm.source`	string	No	Yes	max 255 chars	`"instagram"`	Truncated to 255.
`utm.medium`	string	No	Yes	max 255 chars	`"cpc"`	Truncated to 255.
`utm.campaign`	string	No	Yes	max 500 chars	`"summer-2025"`	Truncated to 500.
`utm.content`	string	No	Yes	max 500 chars	`"banner-a"`	Truncated to 500.
`utm.term`	string	No	Yes	max 500 chars	`"crm software"`	Truncated to 500.
`custom_fields`	object	No	Yes	flat key→value map with string keys	`{ "employees": "20", "sector": "retail" }`	Stored as name/value pairs.
`created_at`	string	No	Yes	timestamp (see Timestamp format)	`"2025-06-28T10:00:00+05:00"`	Lead creation time. An unparseable value becomes `null`.
`updated_at`	string	Yes	No	timestamp (see Timestamp format)	`"2025-07-02T16:45:00+05:00"`	Drives `updated_since` and the watermark. Must be present, parseable, and must advance on every modification.
`closed_at`	string	No	Yes	timestamp (see Timestamp format)	`"2025-07-02T16:45:00+05:00"`	When the lead reached a won/lost stage. An unparseable value becomes `null`.
`is_deleted`	boolean	No	No	`true` or `false`	`false`	Tombstone. `true` soft-deletes the lead. Defaults to `false` if omitted.

loss_reason needs no separate endpoint. Send the reason as free text on the lead; HunterAI synthesizes a stable loss-reason record from the text and links the lead to it. Identical text across leads maps to the same record.

Timestamp format

created_at, updated_at, and closed_at accept a calendar date and time in these concrete forms:

With an explicit offset — 2025-07-02T16:45:00+05:00.
With a trailing Z for UTC — 2025-07-02T16:45:00Z.
With no zone at all — 2025-07-02T16:45:00, which is read as UTC.
The date and time may be separated by a T or by a single space (2025-07-02 16:45:00).
A bare date — 2025-07-02 — is accepted; the time becomes 00:00 UTC.

Prefer the explicit-offset form. An unparseable value becomes null for that field, and no error is raised — the lead is still ingested.

Consequence when this hits updated_at: a null updated_at carries no modification time, so the lead cannot advance the watermark and is not selected by any later updated_since filter. In effect the lead — and every future change to it — drops out of incremental sync. Keep updated_at a valid timestamp that advances on every change.

Fields the adapter ignores

Sending any of these has no effect — do not spend effort populating them:

currency — dropped. price is stored as a plain number with no currency attached, so a connection is effectively single-currency. See Limitations → Currency.
contact_ids beyond the first element — only contact_ids[0] is kept; the rest are ignored.
is_won / is_lost — there is no such field on a lead. Won/lost is derived from the lead’s stage kind, never from the lead itself.
Any other key not listed in the Fields table — ignored.

Identity & cross-references

Identity: id is the stable primary key. HunterAI upserts by (connection, id), so id must never change for the same lead — a changed id is ingested as a brand-new lead.
pipeline_id → resolves against /pipelines.
stage_id → resolves against the stages nested in /pipelines. The stage’s kind is what makes a lead won or lost — a kind outside open, won, or lost is an error at /pipelines, not something the lead can override.
responsible_user_id → resolves against /users.
contact_ids[0] → resolves against /contacts.

Incremental sync

/leads is incremental. HunterAI sends updated_since; return only leads whose updated_at is greater than or equal to it (inclusive — re-returning the boundary lead is harmless, since the upsert is idempotent).

updated_at drives the per-entity watermark — the largest updated_at HunterAI has committed. The next run resumes from there.
You must return leads ordered by updated_at ascending, so the watermark can advance page by page without skipping an older lead on a later page.
updated_at must change on every modification of a lead — a stage move, an owner change, a field edit, or a soft-delete. A change that does not advance updated_at falls at or below the watermark and is never pulled again.

See How sync works for the shared model.

Deletion behaviour

Leads are the only entity that supports a tombstone. Set is_deleted: true to soft-delete a lead; it defaults to false. A lead that simply stops appearing in your responses is not deleted — the upsert only inserts and updates, never removes a row. See Limitations → Tombstones.

Failure modes

A page of leads (up to 100 records) is validated and written as one transaction. The consequences of that:

A single malformed lead fails the whole page. If any lead on a page cannot be processed — a missing id, a non-numeric price — none of the ~100 leads on that page are saved. This is page-level, not per-record.
A failed page fails the sync. Because /leads is required, a page that fails takes the leads entity down with it, and the overall sync is reported failed. Pages that already committed stay committed, and the next run resumes from the watermark.
A lead whose stage was not synced cannot be classified. It lands with is_won = is_lost = false; this is counted and surfaced in the run summary, not silent. Always return every stage a lead can reference on /pipelines.
An unparseable timestamp does not fail anything — the field becomes null and the lead is still ingested. See the consequence for updated_at above.
429 responses are retried with backoff up to 5 times, then the entity fails. HunterAI applies its request rate limit per connection, so two connections to the same base URL are throttled independently.
5xx responses and request timeouts are retried with exponential backoff up to 5 times; a request that times out is retried the same way as a 5xx. Persistent failure fails the entity.
A repeated or unbounded page — a page whose IDs match the previous page, or a run past the page ceiling — fails the entity. See How sync works → Paging.

If this endpoint is missing

/leads is required. A 404 fails the leads entity and the sync is reported failed. This is the core entity, so revenue, win-rate, conversion, loss analysis, and per-manager and per-contact attribution would all be empty.

Required endpoints

Optional endpoints

Purpose

Request

Response envelope

Fields

Timestamp format

Fields the adapter ignores

Identity & cross-references

Incremental sync

Deletion behaviour

Failure modes

If this endpoint is missing

​Purpose

​Request

​Response envelope

​Fields

​Timestamp format

​Fields the adapter ignores

​Identity & cross-references

​Incremental sync

​Deletion behaviour

​Failure modes

​If this endpoint is missing

Purpose

Request

Response envelope

Fields

Timestamp format

Fields the adapter ignores

Identity & cross-references

Incremental sync

Deletion behaviour

Failure modes

If this endpoint is missing