Skip to main content
PATCH
Update the status of leads

Description

Marks leads of a search as qualified or disqualified. It is the status the app shows in a saved list, and the one GET /searches/{id} returns as status and rejection_reasons and filters on with ?status=. Use it to write back a verdict on each lead, for instance after checking them against your ICP. Leads are identified by the lead.id that GET /searches/{id} returns for each lead. You can update your own searches, or those of your workspace members when you authenticate with a workspace key. It costs no credits or quota.

Parameters

Path Parameters

  • id (required, string, UUID): The ID of the search

Body Parameters

  • lead_ids (required, array of strings): IDs of the leads to update, from lead.id in GET /searches/{id}. 1 to 1000
  • status (required, string): qualified or disqualified
  • reason (optional, string): Why the leads are disqualified. Defaults to Manually disqualified. Ignored when qualifying

Example

Responses

200 OK

  • updated is the number of leads whose status was set.
  • unknown_lead_ids lists the IDs that matched no lead of this search. The other IDs are still applied.

400 Bad Request

lead_ids is missing, empty, not an array of strings or longer than 1000; status is not qualified or disqualified; reason is not a string; or the body is not valid JSON.

404 Not Found

The search does not exist, or it belongs to another user outside your account (or outside your workspace, with a workspace key).

422 Unprocessable Entity

The body carries a parameter this endpoint does not take.

Notes

  • Disqualifying replaces any rejection reason the leads already carry; qualifying clears it
  • The search’s qualified and disqualified counts are refreshed after the update

Authorizations

X-API-KEY
string
header
required

Your API key

Path Parameters

id
string<uuid>
required

ID of the search

Body

application/json
lead_ids
string<uuid>[]
required

IDs of the leads to update, as GET /searches/{id} returns them in lead.id. 1 to 1000.

Required array length: 1 - 1000 elements
Example:
status
enum<string>
required

qualified keeps the leads, disqualified rejects them.

Available options:
qualified,
disqualified
reason
string

Why the leads are disqualified, returned as rejection_reasons. Ignored when qualifying. Defaults to Manually disqualified.

Example:

"Not in our ICP"

Response

Leads updated

search_id
string<uuid>

ID of the search

status
enum<string>
Available options:
qualified,
disqualified
rejection_reasons
string[]

Rejection reasons the leads now carry; empty when qualifying

Example:
updated
integer

Number of leads updated

Example:

1

unknown_lead_ids
string[]

IDs that matched no lead of the search

Example: