Skip to main content

List leads

GET 
/v1/leads

Lists the leads of the company that owns the API key, with their custom fields, ordered by updated_at ascending (ties broken by id). Deleted leads are not returned.

Polling for changes. Store the updated_at of the last lead you processed and pass it back as updated_since on the next poll; updated_since is exclusive, so that lead is not returned again. Follow meta.next_cursor until meta.has_more is false before storing it. A lead that changes while you page through appears again on a later poll with its new updated_at. Re-submitting a web form for an existing lead updates that lead, so it is returned again with the new values.

Settle delay. Leads written in the last 30 seconds are held back and returned by a later call, so a write that commits late can never land behind a timestamp you have already passed.

Not every change moves updated_at. Adding or removing a tag, and assigning or unassigning a user, move updated_at, so a lead you tag after a poll is returned by the next one. A lead deleted after you synced it simply stops appearing. A message sent to the lead does not move updated_at. A message the lead sends usually does, but do not use updated_since to track conversation activity. tags, assigned_to and total_messages are current as of the call, for the leads a call returns.

File fields. The value of a file custom field is an object with attachment_id and download_url (GET /v1/attachments/{id}/download, same API key), not the stored path.

Cursor. next_cursor carries every filter of the first page, so a call with cursor needs no other parameters.

Rate limited per company (default 300 requests per 10 minutes).

Request​

Responses​

OK