Change the status of many leads
change_leads_statusChange the status of many leads
Changes every lead that matches the filters to new_status. There is no undo. The
filters are listLeads' own and combine the same way, so listLeads with the same query
lists the leads this takes (those already in new_status are left alone and not
counted). status is required, so a call always names the statuses it takes leads from
(422 invalid_request_body without it); limit and cursor aren't taken
(422 invalid_request_body). Each lead that changes gets a status-change note on its
contact's timeline, as updateLead writes, and a new last_activity_at; nobody is
assigned, and the agent's status flow is not applied.
dry_run is required: send dry_run: true first, which returns how many leads would
change and changes nothing. A changed of 0 means there is nothing to change: don't send
the real call. Otherwise send the same query with dry_run: false and that number as
max_changes: if more would change by then, nothing changes (409 too_many_leads); send
a dry run again and confirm the new number. Leads change in batches of 1,000, so if a call
fails part way, the leads already changed stay changed: send a dry run again to see how
many are left, then the call with that number. Admin rank on the agent, as in the
dashboard.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"agent_id": "<agent_id>",
"status": "<status>",
"new_status": "<new_status>",
"dry_run": "<dry_run>"
},
"name": "change_leads_status"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Matches the name or phone. | |
| status | Yes | The statuses to take leads from, comma-separated, written exactly as `listLeadFields` returns them. | |
| date_to | No | Only those created on or before this date (UTC), the whole day included. Send a date such as `2026-10-11`; a date-time is read as its date. | |
| dry_run | Yes | `true` counts the leads that would change and changes nothing. Required, so leaving it out never changes leads. | |
| agent_id | Yes | The agent the resource belongs to. Another company's agent, or the nil UUID, is `404 agent_not_found`; an agent outside the key's agent list is `403 agent_not_authorized`. | |
| date_from | No | Only those created on or after this date (UTC). Send a date such as `2026-10-01`; a date-time is read as its date. | |
| new_status | Yes | The `value` of one of the agent's lead statuses as `listLeadFields` returns it; matched without regard to case. | |
| assigned_to | No | Only the leads assigned to this teammate (a `user_id` from `listAgentMembers`), or `unassigned` for the leads assigned to no one. `me` isn't taken, because a key isn't a person; it and any other value are `422 invalid_request_body`. | |
| max_changes | No | The most leads this call may change: send the dry run's `changed` (a dry run of 0 has nothing to change, so don't send the call). If more would change, nothing changes (`409 too_many_leads`). | |
| custom_fields | No | Only the leads whose custom fields match: a URL-encoded JSON object that maps a field's key (from `listLeadFields`) to a clause, such as `{"city": {"op": "eq", "values": ["Cairo"]}, "budget": {"op": "is_null"}}`. `op` is `eq` (one value), `in` (one or more), `ilike` (one value the field contains, ignoring case, where `%` and `_` are wildcards), `between` (two values: from the first, included, to the second, excluded) or `is_null` (no `values`). Values are JSON strings, numbers or booleans, compared with the stored value as text: write dates `YYYY-MM-DD` for `between`, and don't expect numbers to compare by size. Clauses combine with AND. A lead without the key reads as null there: it matches `is_null` and no other op. At most 10 keys and 100 values in all; anything else is `422 invalid_request_body`. | |
| last_activity_since | No | Only the leads last worked (`last_activity_at`: a status change or a new note) later than this instant: ISO 8601 with an offset, such as `Z`. Must be earlier than `last_activity_before`, or it is `422 invalid_request_body`. | |
| last_activity_before | No | Only the leads last worked at or before this instant: ISO 8601 with an offset, such as `Z`. Leads nobody has touched since then. |