To let an assistant use these tools, grant Customer CRM on the consent screen, or just
CRM leads & facts under its Fine-tune. The scope is crm.
Read tools work with Read only or Read & write access; write tools only with
Read & write.
Your assistant doesn't see these tools straight away. It finds them with search_tools or
describe_tools, and runs one with use_tool, passing its name and
arguments. Most assistants do this for you: just ask for what you want.
What your assistant is told about this group
The customer record: leads, what you know about each of them, and the timeline of what happened. Each fact records where it came from and how sure it is: a value an agent wrote is not the same as one a person entered, and the results say which is which. ALWAYS read list_crm_fields before writing: reusing an existing key keeps data findable, while inventing a near-duplicate quietly breaks search. record_lead_fact does NOT overwrite what a person entered: if they disagree, the fact is marked as contested and goes to the review queue instead. revert_crm_source undoes everything from one conversation, import or extraction run, and affects many records. search_leads answers a plain-language question and says WHY each lead matched; always read its `interpretation` and `unsupported` before treating the answer as complete. Leads can be created, edited, disqualified or reopened, snoozed, archived or restored; you can log calls and meetings and record call consent, and the bulk_* tools do the same for many leads at once. The feed tools say what has been happening across all leads. message_lead, bulk_message_leads and enrol_leads_in_outreach or add_outreach_leads_by_filter (on a stream that sends automatically) MESSAGE REAL CUSTOMERS: draft first (draft_lead_message, draft_bulk_message), show the user the exact text and get their go-ahead. erase_lead, merge_lead and delete_lead_document are PERMANENT: always confirm with the user before calling them.
The descriptions below are the ones your assistant reads, so they're written for it. When a connection covers more than one
organisation, the assistant passes org (the organisation's slug, from list_orgs) to say which one.
list_leads
Read List CRM leads
The org's CRM leads, with stage, owner, score and how long since anyone contacted them. `untouched_for_days` answers the 'who has gone quiet' question directly. Stage keys are org-authored: call list_crm_stages first rather than guessing them.
Arguments
| Field | Type | Description |
|---|---|---|
| query | string | Free text over name, email, phone. |
| stage | array of string | Stage keys from list_crm_stages. |
| status | array of string | |
| owner_user_id | string | |
| unowned | boolean | Only leads with nobody on them. |
| untouched_for_days | integer | Nobody has contacted them in this many days. |
| created_within_days | integer | |
| created_from | string | Created on or after this day (YYYY-MM-DD, the org's time zone). |
| created_to | string | Created on or before this day, the whole day included (YYYY-MM-DD). |
| touched_from | string | Last in touch on or after this day (YYYY-MM-DD). Leads never contacted have no date, so either bound leaves them out. |
| touched_to | string | Last in touch on or before this day, the whole day included (YYYY-MM-DD). |
| tags | array of string | Tag keys from list_crm_tags: any of them. |
| campaign_ids | array of string | Campaign ids from list_crm_campaigns: any of them. |
| score_min | integer | 0 to 100. |
| score_max | integer | 0 to 100. |
| include_snoozed | boolean | Snoozed leads are left out unless true. |
| include_archived | boolean | Archived leads are left out unless true. |
| sort | string |
One of: "last_touched_desc", "last_touched_asc", "score_desc", "score_asc", "created_desc", "created_asc", "stage_asc", "stage_desc", "due_asc", "name_asc", "name_desc", "status_asc", "status_desc", "owner_asc", "owner_desc", "activity_desc", "activity_asc", "campaign_asc", "campaign_desc", "buying_desc", "buying_asc"
|
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
search_leads
Read Search leads in plain language
Ask a question about the org's leads in ordinary words: "who went quiet after a quote", "leads with a budget over 50k nobody owns", and get back the matching leads with the reason each one matched. Read `interpretation` before trusting the result: it says what the question was understood to mean. `unsupported` lists any part of the question that could NOT be expressed as a filter, if it is non-empty, the answer is partial and you should say so rather than presenting it as complete. `degraded` true means the question could not be planned at all and this is a plain keyword match. Each lead carries `matched`: the specific facts and events that put it in the list, with the evidence behind them. Cite those rather than asserting the result is correct. `filters` is the resolved structured query. Reuse it with list_leads to page or refine without asking again.
Arguments
| Field | Type | Description |
|---|---|---|
| query required | string | The question, in plain language. |
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_saved_views
Read List saved CRM segments
Segments the organisation has saved. Each one stores a resolved filter, so running it costs nothing and returns the same definition every time: prefer an existing segment over re-asking a question it already answers.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_lead
Read Get one CRM lead
Everything the CRM holds on one contact: pipeline state, current facts with their provenance, the recent timeline, and the names of any filed documents. Facts carry confidence and source: treat a low-confidence agent-written fact as a lead, not as truth.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_lead_facts
Read List a lead's facts
Current values the CRM holds for one contact. Set include_history to see superseded assertions too: useful for 'what did we believe in March', and for seeing where an agent disagreed with a person.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| include_history | boolean | |
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_lead_activity
Read List a lead's timeline
What has happened with one contact: conversations, quotes, policies, emails, outreach, notes. Rows point at the record they describe rather than copying it.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| kind | string | Narrow to one activity kind. |
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_crm_fields
Read List CRM fields
The vocabulary this org records against. Read it BEFORE writing a fact: using an existing key keeps the data findable, whereas inventing a near-duplicate (job_title vs occupation) splits it and breaks search. `aliases` shows the other spellings that already resolve to a field.
Arguments
| Field | Type | Description |
|---|---|---|
| status | string |
One of: "proposed", "active", "deprecated"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_crm_review_queue
Read CRM review queue
What the CRM held back for a person to decide: facts an agent asserted that contradict something more trusted, fields an agent invented that nobody has accepted yet, incoming data whose identifiers pointed at two different people, and outcomes (sales, commission...) from the CRM or an upload that matched no lead (match_outcome_submission settles those). Worth checking before assuming the record is complete.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_crm_insights
Read CRM health
How the CRM is doing: lead counts by stage, how many have gone quiet or have no owner, where facts are coming from, and how ingest is faring. `contested_rate` is the number to watch: the share of agent-written facts the organisation's own people contradicted. A rising rate means agents are confidently wrong somewhere, and volume does not make up for it.
Arguments
| Field | Type | Description |
|---|---|---|
| window_days | integer | Defaults to 30. |
| period | string |
Instead of window_days, the Insights window: today, week, month (so far), last7, last30, last90, last_month, or custom with from/to (YYYY-MM-DD).
One of: "today", "week", "month", "last7", "last30", "last90", "last_month", "custom"
|
| from | string | |
| to | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_crm_campaigns
Read List CRM campaigns
The org's lead campaigns: key, name, status, whether each is accepting leads, and its website lead forms and quote forms (get_crm_lead_form / get_crm_quote_form with a form's id for its snippet). Campaign keys appear on leads and events; this is where they resolve to something readable.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_crm_workflows
Read List CRM workflows
The org's automation: each workflow's trigger, conditions, actions and whether it is enabled. This is how to answer "which workflow did that" when a lead's timeline names an automated act.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_workflow_runs
Read List CRM workflow runs
CRM workflow runs, newest first: which workflow, which lead, whether it worked (running, succeeded, failed, skipped) and when. Filter by status or workflow to find why automation isn't doing what's expected.
Arguments
| Field | Type | Description |
|---|---|---|
| status | string |
One of: "running", "succeeded", "failed", "skipped"
|
| workflow_id | string | |
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
approve_held_lead
Write Approve a held lead
Wave a HELD submission through: it re-enters the ingest pipeline and lands with everything a normal submission gets. Held means guardrails stopped it (a validation failure a person should see): read get_crm_review_queue first, and confirm with the operator before approving anything you cannot explain.
Arguments
| Field | Type | Description |
|---|---|---|
| ingest_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
reject_held_lead
Write Reject a held lead
Refuse a HELD submission: it is discarded and never lands on anyone. Give the reason: it is kept on the record the reviewer sees. Irreversible, so confirm with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| ingest_id required | string | |
| reason | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
resolve_ambiguous_lead
Write Resolve ambiguous lead data
Decide who AMBIGUOUS data belongs to: data whose identifiers matched two different people, which the resolver refuses to guess about. verdict is one of the candidate contact ids from get_crm_review_queue, or "new" (it is neither of them: mint a fresh record), or "discard". Assigning lands the data on that person and cannot be unpicked, so confirm with the operator before anything but discard.
Arguments
| Field | Type | Description |
|---|---|---|
| ingest_id required | string | |
| verdict required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
record_lead_fact
Write Record CRM facts
Write what you have learned about a contact into the CRM. Call list_crm_fields FIRST and reuse an existing key wherever one fits. Inventing a near-duplicate (occupation when job_title exists) splits the data and quietly breaks search for everyone. Identity fields, email, phone, name, date of birth, are refused here. They live on the contact record and have their own verification rules. What you assert does not automatically become what the org believes. If a person entered something different, your value is recorded as contested and surfaces for review instead. The response says exactly what happened to each fact: read it rather than assuming success. Include `evidence`: the customer's own words that the value rests on.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| facts required | array of object | |
| facts[].key required | string | Prefer a key from list_crm_fields. |
| facts[].value required | string | Always a string; it is coerced to the field's type. |
| facts[].value_type | string |
Only when proposing a NEW field.
One of: "string", "number", "boolean", "date", "datetime", "enum", "json"
|
| facts[].label | string | Only when proposing a NEW field. |
| facts[].description | string | Only when proposing a NEW field: what it means. |
| facts[].confidence | number | 0..1. Clamped to this surface's ceiling. |
| facts[].valid_from | string | ISO time this became true in the world. |
| facts[].evidence | string | The words this rests on, verbatim. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
add_lead_note
Write Add a note to a lead
Free text on a lead's timeline. Use this for context that is not a reusable field: a summary of what happened, an explanation, a reminder. Anything a filter might later need should be a fact instead.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| body required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
tag_crm_lead
Write Tag a lead
Put tags on a lead, by name (a new name makes the tag). Each tag added runs the workflows listening for lead.tagged. Read list_crm_tags for the org's tags.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| tags required | array of string | Tag names, like "newdistribution subscriber". |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
untag_crm_lead
Write Remove tags from a lead
Take tags off a lead, by name or key. One it doesn't have is ignored.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| tags required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
add_lead_task
Write Add a task to a lead
Something a person must do for this lead: a call, an email, a meeting. It shows in the assignee's My work and on the lead. A lead can have several; the soonest becomes its next action.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| kind required | string |
One of: "call", "email", "message", "meeting", "review", "other"
|
| summary required | string | What needs doing, in a few words. |
| due_on | string | YYYY-MM-DD. Optional. |
| due_time | string | HH:MM in the org's timezone. Optional. |
| assigned_to_id | string | A member's user id; defaults to anyone. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
complete_lead_task
Write Mark a lead's task done
Tick off one of a lead's tasks, by its id (get_lead lists them). What was actually done belongs on the timeline as a note or a logged call.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| task_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
retract_lead_fact
Write Retract a CRM fact
Mark a fact as WRONG. Distinct from it being out of date: a superseded fact still answers 'what did we believe in March', a retracted one never does. Use this only when the value was never true: confirm with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| fact_id required | string | |
| reason | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
revert_crm_source
Write Revert everything one source wrote
Retract every fact that came from one conversation, ingest or extraction run, and restore whatever each of them displaced. This is the undo for a run of bad agent writes. It affects many records at once: always confirm the source reference with the operator before calling it.
Arguments
| Field | Type | Description |
|---|---|---|
| source_ref required | string | As shown on a fact's provenance, e.g. conversation:<id>. |
| reason | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_crm_feed
Read Read the CRM feed
What has been happening across every lead, newest first: conversations, bookings, sales, lead changes and automation, with who did each. Page with `before` set to the previous page's next_cursor.
Arguments
| Field | Type | Description |
|---|---|---|
| group | string |
One of: "escalations", "conversations", "bookings", "sales", "leads", "automation"
|
| from | string | YYYY-MM-DD. Optional. |
| to | string | YYYY-MM-DD. Optional. |
| mine | boolean | Only leads the signed-in user owns. |
| before | string | A next_cursor from an earlier page. |
| limit | integer | At most 50. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_crm_feed_today
Read Today's CRM pulse
Counts of what has happened today, by feed group (conversations, bookings, sales, leads, automation, escalations), and the monthly premium of policies bound today.
Arguments
| Field | Type | Description |
|---|---|---|
| mine | boolean | Only leads the signed-in user owns. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
draft_lead_message
Read Draft a message to a lead
Write a draft message to one lead from their AI briefing. Nothing is sent: show the draft to the user, and send it with message_lead only once they approve.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| channel required | string |
One of: "sms", "whatsapp", "email"
|
| instruction | string | What the message should say. Optional. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
draft_bulk_message
Read Draft one message for many leads
Write a draft that could go, word for word, to several leads at once, built around themes and/or a note. Nothing is sent: show it to the user, then send with bulk_message_leads only once they approve.
Arguments
| Field | Type | Description |
|---|---|---|
| channel required | string |
One of: "sms", "whatsapp", "email"
|
| themes | array of string | |
| note | string | What the message is about, in the user's words. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_lead
Write Add a lead
Add a lead by hand, through the same door every lead comes through: identity dedupe, campaign rules and the lead.created workflows all apply. Needs an email or a phone. Only pass consent a person actually gave; leave a channel out when nobody said. already_known true means it matched an existing contact.
Arguments
| Field | Type | Description |
|---|---|---|
| first_name | string | |
| last_name | string | |
| string | ||
| phone | string | |
| external_system_id | string | The lead's id in the organisation's other system. A lead already holding it is matched instead. |
| campaign_key | string | A campaign key from list_crm_campaigns. Optional. |
| consent | object | Channels the person agreed to be contacted on (about their enquiry and the firm's offers), e.g. {"email": true}. |
| consent.email | boolean | |
| consent.sms | boolean | |
| consent.whatsapp | boolean | |
| consent.phone | boolean | |
| consent.post | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
update_lead_details
Write Edit a lead's details
Correct a lead's name, email, phone or external system id (their id in the organisation's other system), correct declared values, or add one new declared detail. Only send the parts that change. Consent is recorded with record_consent.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| identity | object | |
| identity.first_name | string | |
| identity.last_name | string | |
| identity.name | string | |
| identity.email | string | |
| identity.phone | string | |
| identity.external_system_id | string | |
| declared | object | Corrections to existing declared facts: {field_key: new value}. |
| new_detail | object | One declared value for a field the lead has no value for yet. |
| new_detail.key | string | |
| new_detail.value | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
disqualify_lead
Write Disqualify a lead
Hand a lead a verdict (disqualified, duplicate, invalid, not_interested, ineligible). The stage stays put; the lead leaves the working list and the lead.status_changed workflows fire. reopen_lead takes it back.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| status | string |
One of: "disqualified", "duplicate", "invalid", "not_interested", "ineligible"
|
| reason | string | Why, in a sentence. Shown on the timeline. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
reopen_lead
Write Reopen a disqualified lead
Take a disqualify verdict back: the lead returns to play in the stage it is standing in, with its status matching that stage.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| reason | string | Why it is back. Optional. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
snooze_lead
Write Snooze or wake a lead
Hide a lead from the working list until a date (at most a year out), or leave `snooze_until` out to wake a snoozed lead now. A snooze only ever extends, never shortens.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| snooze_until | string | YYYY-MM-DD or an ISO 8601 time. Omit to wake. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
archive_lead
Write Archive a lead
Take a lead out of every list without destroying anything: its record and history stay, and restore_lead puts it back exactly as it was.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
restore_lead
Write Restore an archived lead
Bring an archived lead back into every list, with the same stage, status, owner and history it had.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
erase_lead
Write Erase a person (GDPR)
PERMANENT and irreversible: the UK GDPR erasure. Deletes the person's CRM record (facts, timeline, documents), scrubs their submissions and leaves a tombstone. Refused while a live policy, application or claim holds them. Owner or manager only. ALWAYS confirm with the user first; archive_lead is the reversible option. `residue` names personal data kept elsewhere under another lawful basis.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| reason required | string | Why they are being erased. Kept in the audit trail. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
merge_lead
Write Merge two leads
PERMANENT: fold a duplicate contact into the primary one. Facts, timeline, conversations and tasks move to the primary, opt-outs and flags are kept, and the duplicate is left as an empty shell. Nothing un-mixes two timelines. Owner or manager only. ALWAYS confirm which record survives with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| primary_contact_id required | string | The record that survives. |
| duplicate_contact_id required | string | The record folded in. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
log_lead_interaction
Write Log a call or meeting
Record a call or meeting that happened outside the platform, and how it went, on the lead's timeline. It counts as a touch for staleness.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| kind required | string |
One of: "call", "meeting"
|
| outcome required | string |
call: connected, no_answer, voicemail, call_back_later, wrong_number. meeting: held, no_show, rescheduled.
One of: "connected", "no_answer", "voicemail", "call_back_later", "wrong_number", "held", "no_show", "rescheduled"
|
| note | string | |
| occurred_at | string | ISO 8601. Defaults to now; never in the future. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
record_call_consent
Write Record that a lead asked to be called
Record the person's own request to be phoned (for example on a form or in a reply), which is what makes calling a TPS-registered number lawful. The note is the evidence, so say how they asked. Refused if they have opted out of calls.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| note required | string | How and when they asked to be called. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
record_consent
Write Record a lead's consent
Record what a person told the team about being contacted: a yes or a no for a purpose (service: about their enquiry or policy; first_party_marketing: the firm's own offers) on a channel. A yes needs evidence: how and when they said it. A no is always honoured. ALWAYS confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| decisions required | array of object | |
| decisions[].purpose required | string |
One of: "service", "first_party_marketing", "third_party_marketing"
|
| decisions[].channel required | string |
One of: "email", "sms", "whatsapp", "phone", "post", "in_app"
|
| decisions[].decision required | string |
One of: "granted", "withdrawn"
|
| evidence | string | How and when they said it. Needed for a yes. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
set_lead_outcome_reason
Write Say why a lead did not go ahead
Set or correct the reason on a lead that is already lost or disqualified. It feeds the loss-reason reporting. To close a lead, use record_lead_outcome.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| reason required | string |
One of: "price", "went_elsewhere", "no_response", "not_ready", "not_eligible", "changed_mind", "duplicate", "bad_details", "other"
|
| note | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
clear_lead_vulnerability
Write Clear a lead's vulnerability flag
Clear the vulnerable-customer flag after a person has reviewed it. The reason is part of the compliance record. Owner or manager only; confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| reason required | string | Why the flag no longer applies. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
check_lead_tps
Write Re-check a lead against the TPS register
Screens the lead's phone number against the Telephone Preference Service now (numbers on it mustn't get unsolicited sales calls). The result appears on the lead (get_lead) shortly.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
reanalyse_lead_conversation
Write Re-analyse a lead's conversation
Rebuilds the summary and grades for one of a lead's conversations; they update a few seconds later.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| conversation_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
refresh_lead_summary
Write Refresh a lead's AI summary
Queue a fresh AI briefing for a lead. It is written in the background, so read the lead again in a minute to see it.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
review_crm_conflict
Write Mark a contested fact reviewed
Acknowledge a contested fact from the review queue: the held-back value stays held back and leaves the queue. It does not change what the org believes. Owner or manager only.
Arguments
| Field | Type | Description |
|---|---|---|
| fact_id required | string | A contested fact id from get_crm_review_queue. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
delete_lead_document
Write Delete a lead's document
PERMANENT: remove a filed document (and its file) from a lead. Owners and managers can remove any; others only their own uploads. Document ids come from get_lead. Confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| document_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
message_lead
Write Send a message to a lead
SENDS A REAL MESSAGE TO A REAL CUSTOMER, straight away, as the signed-in user. ALWAYS show the user the exact text and channel and get their explicit go-ahead first. Refused when the lead cannot lawfully be messaged on that channel. ai_replies false means a person handles their replies.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| channel required | string |
One of: "sms", "whatsapp", "email"
|
| body required | string | The exact text to send. |
| subject | string | Email subject. Email only. |
| ai_replies | boolean | Let the agent answer replies. Default true. |
| agent_id | string | The agent to send from. Optional. |
| email_template_id | string | Email only. Optional. |
| purpose | string |
service (default): about their enquiry or policy. first_party_marketing: a promotion, refused unless they agreed to marketing on this channel.
One of: "service", "first_party_marketing"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_message_leads
Write Send one message to many leads
SENDS REAL MESSAGES TO REAL CUSTOMERS: the same text to up to 100 leads, queued at once (held until quiet hours end if it is night). ALWAYS show the user the exact text, channel and recipients and get their explicit go-ahead first. Leads who cannot lawfully be messaged are skipped and listed with the reason.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| channel required | string |
One of: "sms", "whatsapp", "email"
|
| body required | string | The exact text every recipient gets. |
| subject | string | Email subject. Email only. |
| ai_replies | boolean | Let the agent answer replies. Default true. |
| agent_id | string | |
| email_template_id | string | |
| purpose | string |
service (default) or first_party_marketing (a promotion: leads who haven't agreed to marketing on the channel are skipped).
One of: "service", "first_party_marketing"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_add_lead_note
Write Add a note to many leads
Add the same note to the timeline of up to 500 leads. Internal only; nobody is contacted.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| body required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_tag_crm_leads
Write Tag many leads
Put the same tags on up to 500 leads, by name (a new name makes the tag). A lead that already has a tag is left as it is. Each lead that gains a tag runs the workflows listening for lead.tagged, which can message or enrol people, so confirm with the user first. Read list_crm_tags for the org's tags.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| tags required | array of string | Tag names, like "renewal 2027". |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_untag_crm_leads
Write Remove tags from many leads
Take the same tags off up to 500 leads, by name or key. A lead without the tag is left as it is. Each lead that loses one raises lead.untagged for the workflows listening.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| tags required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_archive_leads
Write Archive or restore many leads
Archive up to 500 leads at once, or restore them with restore: true. Nothing is destroyed. `unchanged` counts leads already in the wanted state.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| restore | boolean | true restores instead of archiving. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_assign_lead_owner
Write Assign an owner to many leads
Give up to 500 leads the same owner, or leave owner_user_id out to unassign them. Each new owner is notified, so confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| owner_user_id | string | A member's user id. Omit to unassign. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_disqualify_leads
Write Disqualify many leads
Give up to 500 leads the same verdict. Stages stay put; bulk_reopen_leads takes it back. Confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| status required | string |
One of: "disqualified", "duplicate", "invalid", "not_interested", "ineligible"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_move_lead_stage
Write Move many leads to a stage
Move up to 500 leads to one stage (ids from list_crm_stages). A won or lost stage closes them and changes the funnel numbers, so confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| stage_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_reopen_leads
Write Reopen many leads
Take the disqualify verdict back on up to 500 leads. `not_disqualified` counts leads that had nothing to reopen.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_run_crm_workflow
Write Run a workflow on many leads
Queue an enabled workflow to run on up to 500 leads. Its actions happen for real (they may message customers or change leads), so confirm with the user first; test_crm_workflow shows what it would do. Owner or manager only.
Arguments
| Field | Type | Description |
|---|---|---|
| workflow_id required | string | |
| contact_ids required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
bulk_add_lead_task
Write Add a task to many leads
Give up to 500 leads the same task (a call, an email, a meeting). It shows in the assignee's My work.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_ids required | array of string | |
| kind required | string |
One of: "call", "email", "message", "meeting", "review", "other"
|
| summary required | string | What needs doing, in a few words. |
| due_on | string | YYYY-MM-DD. Optional. |
| assigned_to_id | string | A member's user id; defaults to anyone. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
enrol_leads_in_outreach
Write Add leads to an outreach stream
Put up to 500 leads onto an active outreach stream, one row per channel they consented to. If the stream auto-sends, REAL CUSTOMERS ARE MESSAGED without review, so confirm with the user first. Leads who cannot be added are listed with the reason.
Arguments
| Field | Type | Description |
|---|---|---|
| stream_id required | string | From list_outreach_streams. |
| contact_ids required | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
add_outreach_leads_by_filter
Write Add leads to an outreach stream by filter
Add EVERY lead matching a filter (the same filters as list_leads) to an active outreach stream, not just a page of them. Call with dry_run: true first: it says how many match, how many would join (rows per channel) and how many are left out and why (no consent for the stream's purpose, no phone or email, already in the stream, blocked, erased, possibly vulnerable, or on a reminder stream no usable date), with a few names, and writes nothing. Show the user that, then call again without dry_run to add them. Consent is what's on each lead's record; nothing is attested. At most 10000 matching leads, and no more joining than the org's add cap; over 500 matches are added in the background and the user is notified when done. Disqualified leads are left out unless include_disqualified or a status filter asks for them. If the stream auto-sends, REAL CUSTOMERS ARE MESSAGED without review, so confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| query | string | Free text over name, email, phone. |
| stage | array of string | Stage keys from list_crm_stages. |
| status | array of string | |
| owner_user_id | string | |
| unowned | boolean | Only leads with nobody on them. |
| untouched_for_days | integer | Nobody has contacted them in this many days. |
| created_within_days | integer | |
| created_from | string | Created on or after this day (YYYY-MM-DD, the org's time zone). |
| created_to | string | Created on or before this day, the whole day included (YYYY-MM-DD). |
| touched_from | string | Last in touch on or after this day (YYYY-MM-DD). Leads never contacted have no date, so either bound leaves them out. |
| touched_to | string | Last in touch on or before this day, the whole day included (YYYY-MM-DD). |
| tags | array of string | Tag keys from list_crm_tags: any of them. |
| campaign_ids | array of string | Campaign ids from list_crm_campaigns: any of them. |
| score_min | integer | 0 to 100. |
| score_max | integer | 0 to 100. |
| include_snoozed | boolean | Snoozed leads are left out unless true. |
| include_archived | boolean | Archived leads are left out unless true. |
| stream_id required | string | From list_outreach_streams. |
| dry_run | boolean | true: say what would happen and add nobody. |
| include_disqualified | boolean | Include disqualified leads (left out by default, as on the leads list). |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |