SamurAI can now ask the CRM exactly how each conversion rate is defined: what it counts, and what counts as "converted". It can also turn on "Show Converted Leads" when it creates or updates a Leads report. Conversion reports built by SamurAI therefore follow the same definitions as the conversion rates in the CRM's Reports wizard.
Contents
1. Before You Start
2. How Conversion Rates Are Defined
3. Read the Definitions
4. Create a Conversion Report
5. Show Converted Leads
6. Two Things to Know Before Relying on the Numbers
7. Frequently Asked Questions
1. Before You Start
You will need: a session for the SamurAI service account (the sessionName from the login call), as today.
Access requirements: any valid API session can read the definitions. No configuration is needed in the CRM.
The new read call becomes available when its database update has run on the instance during deployment. Until then, the instance answers {"status": false, "message": "You are on the wrong path"} . Treat that answer as "not available on this instance yet", not as a failure. The "Show Converted Leads" option works as soon as the new code is deployed.
2. How Conversion Rates Are Defined
There is no per-customer configuration screen for conversion definitions. The CRM ships nine fixed metrics, the same on every instance; only their labels follow each customer's naming. For example, the stage stored as Closed Won is shown as "Admitted". Customers choose per report which metrics to show, whether to ignore the report's filters, and, on a Leads report, whether to include converted Leads.
Key | Counts | Converted when |
M1 | Leads | The Lead has been converted |
M2 | Intake Opportunities | Sales Stage is Admitted |
M3 | Leads | The Lead's Account has an Intake Opportunity at Admitted |
M4 | Leads | The Lead's Account has at least one Intake Opportunity |
M5 | Accounts | The Account has an Intake Opportunity at Admitted |
M6 | Accounts | The Account has at least one Intake Opportunity |
M7 | Leads | Lead → Account → Intake Opportunity has at least one VOB |
M8 | VOB | VOB Stage is Verification Complete, and its Intake Opportunity is at Admitted |
M9 | Intake Opportunities | The Intake Opportunity has at least one VOB |
Conversion rates are available on a report when any of Leads, Accounts, Intake Opportunities, or VOB is its primary or a secondary module.
3. Read the Definitions
GET {instance}/crm/restapi.php/getreportconversionmetrics?sessionName=<sessionName> GET {instance}/crm/restapi.php/getreportconversionmetrics?sessionName=
<sessionName>&module=Leads&secondary=Accounts
module and secondary are optional and accept module names or labels.
Without module, the answer is the full catalog.
With module, the answer also says whether conversion rates apply to that report shape. When they don't, metrics is an empty list. That is a normal answer, not an error.
Example response (one metric shown):
{ "metrics": [
{ "key": "M2",
"alias": "opportunity_to_admitted",
"label": "Intake Opportunities → Admitted %",
"counts": { "name": "Potentials", "label": "Intake Opportunities" },
"numerator_label": "Admitted Intake Opportunities",
"denominator_label": "Total Intake Opportunities",
"path": [ { "name": "Potentials", "label": "Intake Opportunities" } ],
"converted_when": [
{ "type": "field_value",
"module": { "name": "Potentials", "label": "Intake Opportunities" },
"field": "sales_stage", "field_label": "Sales Stage",
"field_ref": "Intake Opportunities. Sales Stage",
"value": "Closed Won", "value_label": "Admitted",
"description": "Sales Stage is Admitted." } ] }
/* ... M1 to M9 ... */ ],
"availability": { "primary_module": { "name": "Leads", "label": "Leads" }, "secondary_modules": [],
"available": true, "include_converted_leads_applies": true },
"options": { "system_wide": { "payload": "conversion_rates.system_wide", "label": "Ignore Conditions", "default": false },
"include_converted_leads": { "payload": "include_converted_leads",
"label": "Show Converted Leads", "default": false } },
"defaults": { "conversion_rates": { "enabled": false, "metrics": [], "system_wide": false },
"include_converted_leads": false } }
Response key | What it tells SamurAI |
counts | The records the rate is counted over (its denominator) |
path | The modules the conversion passes through |
converted_when | What must be true for a record to count as converted. field_ref can be used directly as a report filter |
availability | Whether conversion rates apply to the requested primary and secondary modules |
options / defaults | The per-report choices and their default values |
4. Create a Conversion Report
Switch conversion rates on with the existing conversion_rates block (unchanged). On a Leads report, add include_converted_leads :
POST {instance}/crm/restapi.php/createreport?sessionName=<sessionName>
{
"name": "Lead conversion",
"primary_module": "Leads",
"columns": ["Leads.First Name", "Leads.Lead Source"],
"conversion_rates": { "enabled": true, "metrics": ["lead_to_account",
"lead_to_opportunity"], "system_wide": false },
"include_converted_leads": true,
"chart": { "type": "pieChart", "group_by_field": "Leads.Lead Source", "data_fields": ["count(*)"] }
}
metrics accepts either the key ( M1 ) or the alias ( lead_to_account ).
5. Show Converted Leads
include_converted_leads is the Reports wizard's "Show Converted Leads" checkbox.
Value sent | Result |
Not sent, on create | Off, as before: converted Leads are left out of the report |
true , 1 or "true" on a Leads report | On: converted Leads are included |
false , 0 or "false" | Off |
true on a report whose primary module is not Leads | Error INVALID_INPUT : the option only applies to Leads reports |
Anything else, for example "yes" | Error INVALID_INPUT |
Not sent, on update | Kept as it was |
Important: before this release, every update report switched "Show Converted Leads" off, even on reports where a user had ticked it in the wizard. An update now keeps it on unless include_converted_leads is sent.
6. Two Things to Know Before Relying on the Numbers
Report-scoped rates need Leads, Accounts, Intake Opportunities, or VOB as the primary module. With "Ignore Conditions" off, the rates are counted over the records the report lists. That only works when the primary module is one of those four. For any other primary module, the CRM shows the instance-wide numbers instead. If a scoped rate is needed, make one of those modules the primary module; otherwise, say in the answer that the rates cover the whole instance.
A scoped Leads report needs include_converted_leads: true. A Lead can only reach an Account, an Intake Opportunity, or a VOB by being converted. With the option off, every rate counted over Leads (M1, M3, M4, M7) is 0% on a scoped report.
7. Frequently Asked Questions
Q: Can SamurAI change what counts as converted? No. The definitions are fixed in the CRM and the same everywhere. SamurAI chooses which metrics a report shows, and the options are in section 5.
Q: What if a report's modules have no conversion rates? The read call returns an empty metrics list and sets available to false. createreport rejects any conversion metric for that report, just as the wizard does not offer them there.
Q: Why do the labels differ between instances? Labels follow each customer's naming. The keys and aliases never change.
Q: Do deleted records count? The records a rate is counted over are never deleted ones. A link through a deleted record can still count, for example, a Lead whose converted Account was later deleted.
Need Help?
If you run into issues:
1. If the read call answers "You are on the wrong path", the instance does not have the release's database update yet.
2. Check availability for the report's modules before sending conversion_rates. 3. Contact Dazos support with the request, the response, and a reference to CRM-3959.