IDEMPOTENT, keyed on the profile: the first call commissions the
walks; calling again with the same profile collects progress and
results instead of re-submitting anything — whatever the ask. A
profile that has already been walked returns those results (the
carriers are never asked twice): the envelope's
``coverage_selection`` names the ask the walk typed, and each quote
carries the carrier's other recorded coverage options as
``variants``, so a new ask reads the same run. So call once to
start, then re-call after a few minutes to collect; agents still
working report their stage.
No sign-in is required. The one hard requirement is the user's own
consent, captured in-band: BEFORE the commissioning call, you MUST
tell the user, plainly: Foresee will submit their details to the
named carriers; the carriers may obtain their credit-based insurance
score (a soft pull, with no impact on your credit score); and the
carriers may contact them by email or phone. Then get their explicit
go-ahead and pass their affirmation VERBATIM as ``user_authorization``
(e.g. "yes, go ahead"). The affirmation is stored as the durable
consent record for the dispatch; without one the call is refused with
``authorization_required``. Foresee only collects quotes; it does
not take payment or bind insurance.
Collect the ``identity`` fields in chat. They may be omitted only
when the session is signed in to Foresee and the user has saved their
profile on the Foresee site — then their consented profile-of-record
is used, refined by anything passed in ``profile``.
A ``missing_facts`` response is normal: carrier forms insist on facts
(body style, purchase date, age first licensed…) that Foresee will not
invent. Each ``needs`` entry carries the carrier (``scope``), the
facts in the walk's own words (``need``), and ``fields[]`` — per
fact, the ``ask`` beside the exact schema path to pass the answer
under (``field``, e.g. ``auto.vehicles[].purchase_date``;
``identity.…`` paths go on ``identity``). Ask the user for exactly
those facts, then call again with the answers merged in at those
paths. A fact with no ``field`` has no profile home yet — relay
that carrier's ask as unavailable rather than guessing a key. When
the dispatch was PARTIAL (some carriers walked, some skipped over
missing facts), follow the receipt's ``recover`` block: re-call
with the new facts merged AND ``carriers`` set to exactly
``recover.carriers`` — a changed profile is a new dispatch, and an
unscoped re-call would re-submit the already-walked carriers too.
Unasserted MINOR facts are not asked: a form field that is really a
claim nobody made (an anti-theft device, a defensive-driving course,
years licensed abroad) is answered with the declared no-claim value —
never a discount claim — and every one comes back in ``assumptions``
(``field`` + the ``assumed`` value submitted). Relay them with the
results; if the user corrects one, re-call with the real value at
that path.
``lines`` names WHICH line to walk, exactly one per call (a fan-out
drives one form family): ``{"auto": {...the ask...}}``,
``{"home": null}``, or ``{"renters": {"coverage_c": 30000,
"coverage_e": 100000, "coverage_f": 1000, "deductible": 500}}``. An
AUTO walk's ask is REQUIRED — the limits and deductibles the agents
ask the carriers for, as actual numbers (`bi` "100/300", `pd` 100,
`coll_deductible` 500, `comp_deductible` 500, the same four axes as
quote_insurance); without it the tool answers with the
selection-required message; ask the user, then call again. A HOME
walk takes NO ask — the carrier's own form prices its package
(dwelling amount from its replacement-cost estimate) and the agents
report what it chose. A RENTERS walk requires its four axes as
actual dollars — ``coverage_c`` (personal-property/contents),
``coverage_e`` (personal liability), ``coverage_f`` (guest medical)
and ``deductible`` — the agents type the user's numbers on the form
instead of accepting its defaults, and Foresee never invents them.
Quotes come back with evidence. ``quote.premium`` is VERBATIM as
the carrier's page printed it, and ``term_months`` says what it
covers — a 6-month figure is not a monthly one. When term_months
is known, present the monthly equivalent (premium ÷ term_months)
so carriers compare on one basis, the page's own figure beside it;
without it, relay the printed premium and say the monthly
equivalent is unknown. A carrier may
also decline the risk — a real answer to relay, not an error.
``skipped`` and ``not_dispatched`` name the carriers NOT walked,
each with the reason — relay those too; a carrier never silently
vanishes.