Leads

Search leads

Find leads by free text and filters. With a query, best matches come first (name, then email starting with it); without one, newest first. Every word in query must appear in the name, email, company, title, or a handle. Filter on built-in fields or on custom properties as properties.<key>; GET /lead-properties lists the keys, their types, and common values. An operator that does not fit the field type returns 400 naming the operators that do. Pass nextCursor as cursor, with the same query and filters, for the next page.

POST

/api/v1/leads/search

Request bodyrequired

queryoptional

string

Free text. Every word must appear in the name, email, company, company domain, job title, or a profile handle. Combined with filters.

filtersoptional

object[]

Every filter must match.

cursoroptional

string

limitoptional

integer

Response

200A page of matching leads.

leads

object[]

nextCursor

string | null

requestId

string · uuid

Id of this request, for support and troubleshooting

Errors

  • 400: Bad request
  • 401: Unauthorized: missing or invalid API key
  • 403: Forbidden
  • 404: Not found
  • 422: Invalid request payload

Search docs

Search documentation, API reference, and MCP tools

We use cookies to enhance your experience on Needle and keep your data secure. Privacy Policy