To let an assistant use these tools, grant Customer CRM on the consent screen, or just
Outcomes & conversion goals under its Fine-tune. The scope is outcomes.
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
What happens commercially to leads, as your organisation defines it: measures (premium, commission, costs), outcome types (quote made, policy sold, clawback...) and conversion goals, plus the record of outcomes. Call get_outcome_model first: the keys are different in every organisation. Recording or reversing an outcome changes reported conversions and revenue, so confirm with the user; to correct one, reverse it and record a new one, never edit. Products (list_crm_products) say what a sale was for and what it earns. Changing the model needs an owner or manager.
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.
get_outcome_model
Read Get the outcome model
The org's outcome model: measures (the numbers it tracks, e.g. premium, commission, lead cost), outcome types (what can happen to a lead, e.g. quote made, policy sold, clawback; which measures each carries, required or calculated as a rate of another; which engagement-ladder rung it counts as) and conversion goals (which type counts as a conversion and which measure is its value; one is the default). Read this before recording or configuring outcomes: keys are per org.
Arguments
| Field | Type | Description |
|---|---|---|
| include_archived | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_outcome_events
Read List outcomes
The outcomes ledger, newest first, for one lead (contact_id), one deal (deal_ref) or one type, including reversals.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id | string | |
| deal_ref | string | |
| outcome_type | string | |
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
record_outcome_event
Write Record an outcome
Record that something commercial happened to a lead (get_outcome_model lists the types and their measures). measures are in natural units: money in pounds, percent as a percentage. deal_ref ties a sale to its later commission or clawback (a lead can buy more than once). product is the product it was for (list_crm_products: its key or an alias), where the type takes one; its commission rule fills commission when you don't give it. A cancelled sale is cancel_outcome_event. This changes the org's reported conversions and revenue: confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| contact_id required | string | |
| outcome_type required | string | |
| occurred_at | string | ISO 8601; now when omitted |
| measures | object | |
| deal_ref | string | |
| product | string | |
| note | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
reverse_outcome_event
Write Reverse an outcome
Reverse an outcome recorded in error (the ledger keeps both). To correct values, reverse and record again. A sale that was really cancelled is cancel_outcome_event instead, so it still counts in its own month. Changes reported conversions and revenue: confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| id | string | Our outcome id |
| event_id | string | Or the sender's own reference for it |
| note | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
cancel_outcome_event
Write Record a cancelled sale
Record that a sale (an outcome id from list_outcome_events) was cancelled: occurred_at is when it was cancelled (ISO 8601; now when omitted), reason one of cooling_off, not_taken_up, stopped_paying, customer_cancelled, replaced, other, clawback the commission paid back in pounds (omit it and the sale's product rule works it out). The sale keeps counting in the month it was made; the cancellation counts in its own month. Not reverse_outcome_event, which is for outcomes recorded in error. Confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| occurred_at | string | |
| reason | string |
One of: "cooling_off", "not_taken_up", "stopped_paying", "customer_cancelled", "replaced", "other"
|
| clawback | number | |
| note | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
complete_outcome_event
Write Complete an outcome's missing values
Add values an outcome was recorded without (e.g. the premium of a sale recorded by a stage move), and the product it was for when it has none (list_crm_products: key or alias; its commission rule fills commission). Only missing values are set; recorded ones never change.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| measures | object | |
| product | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
save_outcome_measure
Write Save an outcome measure
Create or update a measure the org tracks on outcomes. unit (money, count or percent) is fixed at creation; direction says whether it is revenue, a cost or neither. archived: true hides it from forms, keeping its history. Owner or manager.
Arguments
| Field | Type | Description |
|---|---|---|
| key required | string | lowercase_with_underscores, fixed once created |
| label | string | |
| unit | string |
One of: "money", "count", "percent"
|
| direction | string |
One of: "revenue", "cost", "neutral"
|
| archived | boolean | |
| formula | string | Makes it derived: arithmetic over recorded measure keys, e.g. "commission - lead_cost" or "commission / annual_premium * 100" (in pounds, percent, counts). Worked out in reports, never recorded. Blank clears it. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
save_outcome_type
Write Save an outcome type
Create or update something that can commercially happen to a lead. ladder_stage makes it count as an engagement-ladder rung (engaged, conversing, lead, booked, quoted, sold). repeatable lets a lead have it more than once (otherwise once per lead, or per deal_ref). measures replaces the set it carries: [{key, required, rate_percent, rate_of}]; a rate makes the value calculated from another measure when not given (commission = 22 percent of annual_premium). System types (the rungs) keep their key and rung. product_mode (none, optional, required) is whether recording one asks which product it was for (list_crm_products). Owner or manager.
Arguments
| Field | Type | Description |
|---|---|---|
| key required | string | |
| label | string | |
| description | string | |
| ladder_stage | string |
One of: "engaged", "conversing", "lead", "booked", "quoted", "sold", ""
|
| repeatable | boolean | |
| archived | boolean | |
| product_mode | string |
One of: "none", "optional", "required"
|
| measures | array of object | |
| measures[].key required | string | |
| measures[].required | boolean | |
| measures[].rate_percent | number | |
| measures[].rate_of | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
save_outcome_goal
Write Save a conversion goal
Create or update a conversion goal: which outcome type counts as the conversion and which measure is its value (used for return on ad spend). default: true makes it the org's default goal on the Sources report. Owner or manager.
Arguments
| Field | Type | Description |
|---|---|---|
| key required | string | |
| label | string | |
| outcome_type | string | |
| value_measure | string | A measure key, or empty for no value |
| default | boolean | |
| archived | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_crm_products
Read List products
The products the org sells (not the insurance engine's products): the key and aliases to record an outcome against (record_outcome_event product), what a sale earns (commission: a fixed amount in pounds, or a percentage of a measure) and the clawback if a sale is cancelled.
Arguments
| Field | Type | Description |
|---|---|---|
| include_archived | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
save_crm_product
Write Save a product
Create or update a product the org sells, found by key (set once, used by the API and uploads). aliases: other codes a CRM sends for it. insurance_product: an insurance engine product id it is (with the engine only; blank unlinks). commission_kind: none, fixed (commission_amount in pounds per sale) or percent (commission_rate_percent of the measure commission_rate_of, e.g. annual_premium); it fills a sale's commission when none is given. clawback_months and clawback_mode (full or pro_rata): how much commission comes back if a sale is cancelled. Omitted fields are left as they are. Owner or manager.
Arguments
| Field | Type | Description |
|---|---|---|
| key required | string | |
| name | string | |
| description | string | |
| aliases | array of string | |
| insurance_product | string | |
| commission_kind | string |
One of: "none", "fixed", "percent"
|
| commission_amount | number | |
| commission_rate_percent | number | |
| commission_rate_of | string | |
| clawback_months | integer | |
| clawback_mode | string |
One of: "full", "pro_rata"
|
| archived | boolean | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
submit_outcomes
Write Submit outcomes in bulk
Record many outcomes at once, e.g. from a CRM export the user pasted. Each item: {event_id (their reference, makes it safe to retry), type (an outcome type key), occurred_at (ISO 8601), lead: {id (our contact_id) | external_id (their system's id) | email/phone with match_on_details: true}, values {measure_key: number, money in pounds}, deal_ref, note}. Items with no single matching lead are held for review (list_outcome_submissions). Up to 500. Changes reported conversions: confirm first.
Arguments
| Field | Type | Description |
|---|---|---|
| outcomes required | array of object | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_outcome_submissions
Read List held outcomes
Outcomes that arrived (API, upload, bulk submit) without a single matching lead, waiting to be matched or dismissed: what was sent, why it didn't match, and any candidate leads.
Arguments
| Field | Type | Description |
|---|---|---|
| status | string |
One of: "pending", "matched", "dismissed"
|
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
match_outcome_submission
Write Match a held outcome to a lead
Record a held outcome against the lead it is about (contact_id), exactly as it was submitted. Changes reported conversions: confirm the lead with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| contact_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
dismiss_outcome_submission
Write Dismiss a held outcome
Drop a held outcome that isn't about any lead the org has.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_outcome_uploads
Read List outcome uploads
Spreadsheets of outcomes uploaded on the dashboard, newest first: each file's row counts by status (recorded, duplicate, held, conflict, invalid) and the rows that weren't recorded, with why.
Arguments
| Field | Type | Description |
|---|---|---|
| limit | integer | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_campaign_performance
Read Get campaign performance
Each lead campaign's P&L for a window: leads, its goal's conversions (gross) and value, cancelled (how many of those were cancelled since) and still_on_book_rate, income (revenue measures such as commission), costs (price per lead, clawbacks on cancelled sales, costs entered by hand, linked Google/Meta spend), profit, ROI, cost per lead and per conversion, and the org's derived measures (formulas). Money in pounds. period: today, week, month (so far), last7, last30, last90, last_month (last30 by default), or custom with from/to (YYYY-MM-DD); campaign_id narrows to one.
Arguments
| Field | Type | Description |
|---|---|---|
| period | string |
One of: "today", "week", "month", "last7", "last30", "last90", "last_month", "custom"
|
| from | string | |
| to | string | |
| campaign_id | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_product_performance
Read Get product performance
Each product's figures for a window, as on Insights > Growth > Products: the goal's conversions (gross) and value, cancelled (of those, cancelled since; null when the goal can't be cancelled) and still_on_book_rate, income (revenue measures such as commission), clawbacks on cancelled sales, and net income. Outcomes without a product are their own row. Money in pounds. goal: a goal key (the org's default when omitted). period: today, week, month (so far), last7, last30 (default), last90, last_month, or custom with from/to (YYYY-MM-DD).
Arguments
| Field | Type | Description |
|---|---|---|
| period | string |
One of: "today", "week", "month", "last7", "last30", "last90", "last_month", "custom"
|
| from | string | |
| to | string | |
| goal | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
record_campaign_cost
Write Record a campaign cost
Enter a cost against a lead campaign for its P&L (a monthly fee, a print run): amount in pounds, dated (today when omitted). Per-lead prices and linked ad spend count by themselves; don't enter them here. Owner or manager only.
Arguments
| Field | Type | Description |
|---|---|---|
| campaign_id required | string | |
| amount required | number | |
| incurred_on | string | ISO date |
| note | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
delete_campaign_cost
Write Delete a campaign cost
Remove a cost entered by hand against a lead campaign (get_campaign_performance shows the totals; the campaign's page lists each cost). Owner or manager only.
Arguments
| Field | Type | Description |
|---|---|---|
| cost_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |