Leads

List, create, read, update and move leads through your pipeline.

2 min read

List leads

http

GET /api/v1/leads

Parameter	Description
`filter[status]`	Status public id
`filter[owner]`	Membership public id
`filter[source]`	Source public id
`filter[created_at]`	A date range, or a keyword such as `last_30_days`
`filter[score_band]`	`hot`, `warm` or `cold`
`sort`	`-created_at`, `score`, `-last_activity_at`
`page[size]`	Up to 200; defaults to 50
`page[after]`	Cursor taken from `links.next`

Note

Filter values are public ids, not names or slugs. An unrecognised filter key returns 200 with an empty list rather than an error — so when you add a filter, verify it returns the rows you expect, not merely that it returned 200.

Results are always scoped to what your token's membership may see. A manager's token returns their team; an agent's token returns their own leads. There is no parameter that widens this.

Create a lead

http

POST /api/v1/leads

json

{
  "first_name": "Aarav",
  "last_name": "Patel",
  "phone": "9812300045",
  "email": "aarav@example.com",
  "source": "01H8XGJWBWBAQ4S1PT7C2N3M4K",
  "estimated_value": 140000,
  "custom_fields": { "product_interest": "Annual plan" }
}

Distribution rules apply, so a lead created through the API is routed exactly like one from a web form.

Duplicate detection runs on phone and email. A match returns 200 with the existing lead and "duplicate": true rather than creating a second record — which means a retried request is safe.

Read a lead

http

GET /api/v1/leads/{public_id}

Returns the lead with its contact, source, status, owner and custom fields. Add ?include=activities,notes for the timeline.

Update a lead

http

PATCH /api/v1/leads/{public_id}

Send only the fields you are changing. Every change is written to the audit trail with your token recorded as the actor, so an API-driven edit is as traceable as one made in the interface.

Move a lead's stage

http

POST /api/v1/leads/{public_id}/status

json

{ "status": "01H8XGK2M4P5Q6R7S8T9V0W1X2", "note": "Customer confirmed budget" }

Important

Use this rather than PATCHing a status field. It records a proper stage transition, and transitions are what funnel, velocity and conversion reporting read. A directly-written status changes the lead but leaves the reports blind to when it moved.

Stuck on a response you did not expect? Send us the request_id from the error body and we can trace the exact call — contact support.