icp score

Invocation#

echo-cli icp score --product <id> --name <name> --app <web or mobile source> --days <n> --conversion-event <event> --retained-after-days <n> --by <name>
echo-cli icp scores --product <id>
echo-cli icp schedule --product <id> --name <name> --app <web or mobile source> --days <n> --conversion-event <event> --retained-after-days <n> --every-days <n> --by <name>
echo-cli icp schedules [--product <id>]
echo-cli icp unschedule --id <schedule-id>
echo-cli icp due
echo-cli icp contacts --product <id> --name <name>
echo-cli icp fill-list --product <id> --name <name> --list <crm-list-id>

Inputs and output#

score writes the score it stored and scores every stored score of the product, newest first: id, product_id, profile_name, profile_version, app_id, since, conversion_event, retained_after_days, firmographics, matched and unmatched (each people, converted, conversion_rate, counted_for_retention, retained and retention_rate; a rate is null when its cohort is empty), scored_by and scored_at. schedule writes the schedule it stored: id, product_id, profile_name, app_id, days, conversion_event, retained_after_days, every_days, declared_by, declared_at, attempted_at, score_id and error; schedules writes the schedules (of the product when named), oldest declared first; unschedule writes the one removed (its scores stay); due writes the schedules it attempted.

State effect#

score and scores call Echo Web's authenticated /api/analytics/icp/score, and schedule, schedules, unschedule and due /api/analytics/icp/score/schedules, with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the ICP score section of the tracking screen and of Echo Desktop's GEO screen (with its scheduled scores) call the same operations, and echo-mcp reads them as echo_icp_scores and echo_icp_score_schedules. score reads the source's stored events of the last --days days — a web source's web events or a mobile app's mobile events — and joins every identifier linked at sign-in into one person. A person matches the profile, at its latest version, when for every firmographic attribute the latest of their events carrying that attribute in its properties carries the profile's value, compared trimmed and case-blind; a person whose events never carry an attribute does not match. A person converts when they sent --conversion-event in the window, and is retained when an event of theirs comes at or after --retained-after-days from their first; only people whose first event is at least that old are counted for retention. Each score is stored in icp_scores with the profile version and the settings. A schedule keeps one profile's settings on one source (scheduling the same profile and source again replaces them); /api/cron/icp-scores runs daily at 06:13 UTC and scores every schedule never attempted or last attempted at least --every-days ago, as score does with scored_by "schedule declared by <name>", keeping on the schedule when it ran and the score it stored or the error that stopped it (a retired profile, a source with no events); due does the same now.

Refusals#

• A wrong invocation is refused before anything is sent: "icp takes <every verb's usage, separated by semicolons>; got <word>", "icp score does not take <flag>; it takes …", "<flag> needs a value" and "icp score needs <flag>".
• Echo Web answers a bad request with "product_id is required: …", "name is required: …", "app_id is required: …", "conversion_event is required: …", "days must be a positive whole number of days: how far back to read the events; got <value>" (and retained_after_days, every_days), "retained_after_days <n> does not fit in a window of <n> days: no one read could be told retained", "profile <name> was retired at <instant> by <name>; a retired hypothesis is not scored" or "profile <name> names no firmographic attribute, so no person can be matched to it; echo-cli icp edit adds one with --attribute <key>=<value>"; and not found with "product <id> has no ICP profile named <name>; echo-cli icp list --product <id> lists them", "no ICP score schedule has id <id>; echo-cli icp schedules lists them" or "no events were found for the source <app> of product <id> since <instant>; echo-cli tracking quality names the sources that report". The command prints Echo Web's sentence and exits 1.
• contacts reads every CRM contact (creator_contacts) and writes { product_id, profile_name, profile_version, firmographics, matched, unmatched, deal_statuses, contacts }: a contact matches the profile's latest version when its stored metadata carries every firmographic attribute with the profile's value (trimmed and case-blind, as score compares event properties); deal_statuses counts the matched and the unmatched by deal status; each contact (contact_id, name, deal_status, matches) names the attributes its metadata differs on (differing) and those it never recorded (unrecorded), matched contacts first. Nothing is stored; the CRM contacts the profile matches section under the ICP score of the tracking screen and of Echo Desktop's GEO screen read the same /api/analytics/icp/contacts, and echo-mcp reads it as echo_icp_contacts. Echo Web refuses it as score is refused: a missing product_id or name, a retired profile, a profile naming no firmographic attribute, or a product with no profile of that name.
• fill-list adds every CRM contact the profile matches now (as contacts matches them) to the CRM list --list, through POST /api/analytics/icp/contacts, so a campaign sent to that list reaches the profile; a contact already on the list stays as it is. It writes { list_id, profile_name, profile_version, matched, added (the contact ids it added), already (how many matched contacts were on the list) }. Echo Web refuses it as contacts is refused, and with "list_id is required: the CRM list the matched contacts join" or not found with "no CRM list has id <id>".