quotes

associate_agentcy_to_quote

Code
Bind a full quote with all the necessary information.

Two tenant advanced settings, enforced at the shared new-business bind
choke point (``QuoteService.bind_quote``), can additionally gate this bind.
They govern every new-business bind path identically (this API and the
agent UI new-business submit); mid-term change/endorsement binds
(``submit_change``) are out of scope and unaffected. Both DEFAULT OFF, so
behavior is unchanged until a tenant opts in:

* ``integrations`` / ``contact-screening-require-completion-before-bind``:
  refuse the bind unless every in-scope contact has a currently complete
  screening result (``complete_pass`` or ``complete_overridden``).
  IMPORTANT for programmatic binders: the pre-existing implicit OFAC
  hit-block (``_agent_submission_locked`` in ``lib/agent/utils.py``, which
  evaluates screening and refuses on ``review_required`` hits) DOES run on
  this path - ``bind_full_quote`` -> ``submit_full_quote`` ->
  ``bind_quote`` reaches it via ``agent_submission('application')``. But it
  is only EFFECTIVE on the agent-UI submit, which surfaces the returned
  failure dict; on the programmatic path only the gate's
  ``restrictionReason`` refusals (suspension / limit) become an error, and
  the hit-block sets none, so it is a no-op here and a ``flagged`` contact
  will bind. That makes this setting
  the ONLY effective bind-time OFAC enforcement on the programmatic API: a
  binder that leaves it OFF gets no bind-time OFAC protection, and one that
  wants it MUST enable it. On the agent-UI path the setting is additive and
  stricter than the hit-block (it also refuses ``never_screened`` /
  ``expired`` / ``data_mismatch``, not just hits).
* ``policies`` / ``enforce-business-rules-at-bind``: gate the bind by the
  KNOCKOUT business rules (disallowed category options, required /
  List-``Disallow`` supplemental-question knockouts, and revision-level
  underwriting prevent-continue blocks). It intentionally does NOT enforce
  the completeness/boundary checks (item mandatoriness, multiplicity,
  deductible/limit boundaries): those are build-time input guards that
  false-positive on a fully rated quote, so enforcing them at bind would
  reject the existing book. When either gate trips, the bind is refused
  with a ``BCGlobalValidationError``.

Parameters
----------
id : str, optional
    Revision id.
external_system_reference : str, optional
    Caller-side reference, alternative to ``id``.
submit_bound : bool, optional
    Whether the policy should be submitted as bound (legacy behavior).

copy_quote

create_and_rate_endorsement_quote

Create and rate a full quote without committing to the database.

Code
Both modes can run through the unified engine, each behind its own
advanced setting (default off; flipping back is the rollback): the
STATELESS mode (rate_quote=true too) on the rate-only pipeline, the
STATEFUL mode on the persist branch with the response read back by
the legacy retrieve -- the flag alone routes (the per-feature
capability gate is gone; underlying-policy copy and template risks
resolve in input space). rate_quote=false always stays legacy (an
unrated create is persistence-only).

Code
Create an endorsement quote with all the necessary information.

Code
Create a full quote with all the necessary information.

Validate a full-quote payload synchronously, then offload heavy creation to Celery.

Code
Returns immediately with a ``reference_id`` the caller polls via
:func:`get_full_quote_async_status`.

Code
Create a renewal quote using the latest committed or pending revision.

Request:
    - Quote ID or Quote Exref or Policy Number.
Response:
    - Full Quote response.
Validations:
    - Renewal can only be created on the latest committed or pending revision.

Code
Delete a full quote with all the necessary information.

delete_quote

Code
Evaluate contact screening for a quote or revision.

Parameters
----------
id : str
    ID of the quote or revision to evaluate contact screening for
skip_integrations : bool, optional
    If True, skip external integration calls and only use existing screening results.
    Defaults to False.

Returns
-------
dict
    Screening results
    {
        "screening_contacts": [...],
        "all_results": [...],
        "review_required_results": [...]
    }

Generate a quote through the unified engine (plan.md 1A.14).

Code
NOTE: decorated with ``log_payload_params=False`` -- the quote payload
(multi-KB, insured PII) and the full rated response would otherwise be
JSON-serialized into the INFO logs twice per request (file + stdout
handlers). Both are recoverable from ``stateless_quotes`` (``input_data``
encrypted, ``output_data``) when ``save_stateless_quote`` is on, so the
logs only need the received/completed markers, path, and timing.

Authorization -- ``create_quote_extended`` parity: gateway authentication
only (any valid api key or session), NO endpoint-level permission check.
The graduated ``britecore/policies/newPolicy`` gate was enforced briefly
and removed (plan.md 1A.14): api-key
principals carry no permissions tree for the path engine to evaluate, so
on restrictive-engine sites the check denied EVERY integration -- the
endpoint's primary callers. Re-gating waits on an api-key story in the
permission engine.

Takes ONE of:
  - ``quote_info``: a ``create_quote_extended``-shaped payload (names) --
    translated by ``RequestSource``;
  - ``quote``: the canonical ``CreateFullQuoteRequestModel`` JSON (ids) --
    deserialized directly by ``CanonicalSource``.

Rate-only through the FULL unified pipeline (Source -> canonical
CreateFullQuoteRequest -> vendor enrichment -> ItemBuilderCore mutating
the working Quote -> UWR core-routing loop -> rating projection ->
rate_line_items_in_memory). Enrichment (geocoding + per-insured credit
reports via ``VendorIntegrationService``, all enabled vendor calls in ONE
PARALLEL batch) is fail-open: vendor degradation lands in the response's
``warnings`` list (and in ``stateless_quotes.messages`` when saving),
never as a failed quote (FR-13/AS-29).

Two INDEPENDENT persistence flags; the pipeline itself stays rate-only:
  - ``save_stateless_quote`` -- the STATELESS terminal: one row in
    ``stateless_quotes`` (raw payload as encrypted input_data, rating
    result + '_unified' UWR sidecar as output_data, origin='canonical');
    the response carries ``stateless_quote_id``. Defaults ON -- an absent
    key saves; the dry run (rate-only, no row written) is opt-in via an
    explicit ``save_stateless_quote=false``. A non-boolean value is
    rejected (``ensure_boolean``) so a stringy ``"false"`` cannot
    silently persist a caller's intended dry run.
  - ``save_full_quote=true`` -- the STATEFUL terminal (1A quote+bind
    branch): ``QuoteService.quote_and_persist`` runs the same pipeline
    with stateful seeding semantics (DEFAULT items included, BL-2) and
    ``QuotePersister`` writes the real graph -- Policy + PolicyTerm +
    Revision + properties + the quote's items/sub-lines -- then numbering
    and billing. The response carries ``revision_id`` / ``policy_id`` /
    ``policy_number``. With both flags on, the saved row is linked to the
    created revision via ``revision_id``.

The response also carries the rating result (same shape as the stateless
output, for side-by-side comparison), the surfaced UWR outcome, and the
quote's serialized items/sub-lines (what ``save_full_quote`` writes).

Code
Return the read-only set of forms applicable to a quote's revision.

Each row carries the ``form_id`` (``File.id``) and a ``has_preview``
hint; the wizard frontend (``applicable-forms.vue``) builds the
download URL with the standard ``core.uploads.getAttachment`` gateway
shape used everywhere else for File downloads, so frontend routing
stays out of the backend response.

The list itself is the server-side applicability gate: the wizard can
only ever open previews for ``form_id`` values it receives here, so we
don't need a separate per-form re-validation endpoint.

Eligibility mirrors commit-time generation; this endpoint does not
commit, render PDFs, or otherwise mutate the quote.

Parameters
----------
quote_id : str
    Revision id of the in-progress quote.

Returns
-------
dict
    ``forms`` is the list of applicable forms; ``revision_updated_at``
    is the staleness signal the frontend captures on load and compares
    against the next ``rate_quote`` to decide whether the list needs
    a refresh.
    {
        "forms": [
            {
                "form_id": str,
                "form_number": str,
                "form_title": str,
                "form_type": str,
                "applicability": str,
                "edition_number": str,
                "description": str,
                "has_preview": bool,
                "mime_type": str,
            },
            ...
        ],
        "revision_updated_at": str | None,
    }

Code
Report the current contact-screening completeness for a revision, without
making any vendor calls.

Distinct from :func:`evaluate_contact_screening`, which calls the
vendor for any contact missing a valid result (side effects +
integration cost). This endpoint is pure read against persisted
state, so callers can pre-check before bind and decide whether to
invoke ``evaluate_contact_screening``, prompt for an override, fix
contact data, or proceed.

The per-contact ``status`` is one of the ``SCREENING_VERIFICATION_STATUS_*``
values; ``complete_pass`` and ``complete_overridden`` are the only
statuses that count as complete. ``vendor_message`` is surfaced verbatim
on ``flagged`` rows so callers can distinguish a confirmed sanctions hit
from an ambiguous / insufficient-data response.

Parameters
----------
id : str
    Revision id.

Returns
-------
dict
    {
        "revision_id": str,
        "all_complete": bool,
        "screening_enabled": bool,
        "integration_configured": bool,
        "tenant_reason": str|null,
        "contacts": [
            {
                "contact_id": str,
                "contact_name": str,
                "status": str,
                "is_complete": bool,
                "reason": str,
                "vendor_message": str|null,
                "screened_at": iso8601|null,
                "screening_check_result_id": str|null,
                "has_valid_override": bool
            }
        ]
    }

Return estimated quote for the given quote.

Poll for the status of an async quote creation job.

Code
Get the last execution date of data prefill for a given policy.

get_quote

get_quote_properties_summary

FR-14 (spec 009 P2): the JSON Schema (draft-07) describing the canonical create_full_quote payload for ONE policy type -- derived from the same PolicyTypeConfigProvider the unified engine rates from. Integrator/UI-facing; Marshmallow remains the in-process validator of record.

Code
POST /api/v2/quotes/get_quote_schema  {"policy_type_id": "<uuid>"}

get_quote_wizard_plugin

The active "Suspend Quoting" message for a revision being quoted, or None (BC-24714).

Code
The read-only companion to the enforcement points. Rating refuses, the location save refuses
and submission refuses, each by raising; the wizard needs the same answer without provoking a
raise, so that it can keep an agent out of the steps that work an unquotable quote. It returns
the message rather than a bare boolean so the copy stays in one place: what the wizard shows is
what the refusals say.

Deliberately answers about the quote as SAVED, and offers no way to ask about an address the
agent has merely typed. A refused address was never written, so it is not a risk the quote
holds, and the AC blocks the wizard when a suspension matches a risk. An earlier revision of
this endpoint did take a candidate location; it over-blocked a quote that was still perfectly
quotable, and it latched, because nothing could clear a verdict about an attempt the agent then
abandoned. Asking one question also means this and the rating gate cannot disagree.

Revisions that are no longer being quoted are not suspended by this action and answer None -
that exemption belongs to SuspensionService and is shared with the rating gate.

Code
Get all risks (Properties, Vehicles, Watercrafts) for a quote.
Returns a summary of each risk with type and name.

Code
Issue a full quote with all the necessary information.

list_available_offers

Code
Modify a full quote with all the necessary information.

prefill_loss_history

Code
Pull property loss history (CLUE / ISOLoss) for one or more properties on
a revision and persist the results.

NOTE: decorated with ``log_payload_params=False`` because the response
carries vendor-shaped ``loss_history`` and report numbers (CLUE/ISOLoss
claim detail); the default ``@api_request`` would write that into the API
request/response logs.

This is the supported v2 surface for property loss history; it wraps the
legacy ``policies.views.retrieveLossHistory`` gateway function. Use this
in place of hitting that gateway path directly. The auto equivalent is
:func:`prefill_loss_history` (this endpoint is property-only).

Reading already-pulled history does not require this endpoint;
/api/v2/policies/retrieve_risk_details surfaces stored loss history
alongside the rest of the property data.

Parameters
----------
revision_id : str, required
    Revision whose property/properties should have loss history pulled.
property_ids : list[str], optional
    Restrict the pull to specific properties on this revision. Ids that
    don't belong to the revision are silently skipped (they will not
    appear in the response). When omitted (``None``), all properties on
    the revision are pulled; an explicit empty list pulls none.
force_run : bool, optional, default False
    When False, CLUE's property-level 30-day check applies: a property
    whose most recent successful report is within 30 days is reused
    instead of burning another vendor call. When True, that property-level
    check is bypassed. NOTE: CLUE's separate <=30-day ``VendorCache``
    (keyed on the named insureds) may still serve a cached result even
    with ``force_run=True``, so a fresh vendor order is NOT guaranteed -
    inspect each property's ``pull_performed`` flag to know whether an
    order actually ran. ISOLoss has no equivalent cache; this kwarg is a
    no-op there.

Returns
-------
dict
    ::
        {
            "vendor": "iso_loss" | "clue_property" | null,
            "properties": [
                {
                    "property_id": str,
                    "loss_history": [...],            # vendor-shaped past claims
                    "loss_history_date_pulled": str,  # MM/DD/YYYY
                    "loss_history_report_number": str,
                    "pull_performed": bool,           # true when a fresh vendor call ran
                    "mandatories_succeeded": bool or null, # loss-free mandatory item refresh result
                    "messages": [str]                 # per-property warnings/errors
                }, ...
            ],
            "messages": [str]                          # tenant-level warnings (e.g. no vendor configured)
        }

prefill_quote

prefill_violations

The Quote Wizard Rate action as ONE call: hydrate the persisted revision, run UWR server-side, rate fully in memory, persist the rate delta, and answer with the retrieve_revision_details payload -- replacing the wizard's 8-request reset/rate_risk/rate_revision/details cascade.

Code
The response also carries a ``risk_rates`` sibling: per property of the
revision, the legacy ``rate_risk`` response shape (rated items and
sub-lines plus the four premium columns). Every property, not a
requested subset -- the engine rates them as a set, because they can
reference each other, so all of their premiums move and every property
model in the wizard needs the new figures.

``generate_quote``'s sibling in the unified-engine namespace:
``quotes/generate_quote`` creates, ``quotes/rate`` rates existing
content. ``quote_id`` IS the revision id -- the quotes v2 API
convention (the repository layer resolves ``Revision.get(quote_id)``,
lib/repository/legacy_utils.py:217).

This endpoint rates through the unified engine, period -- it does NOT
fall back to the legacy ``rate_quote_revision`` in-process. WHICH Rate
action a revision gets is the service's decision (``rate_capability``:
the ``britequote/toggle-feature-enable-rate-revision-unified-engine``
advanced setting ON, default OFF, AND a rating-v2 Property
new-business/renewal revision), and the wizard consumes it from the
revision-details payload BEFORE its first call: a supported revision
POSTs ``run_pre_rate_integrations`` then this; an unsupported one runs
the legacy cascade untouched. The adapter re-asserts the predicate, so a
call that lands here with it False (a stale wizard whose details predate
a setting flip, or a direct caller) is refused in the flat error.

Authz continuity: the EXPLICIT page-permission decorator
(``_RATE_PAGE_PERMISSIONS``) keeps an agent authorized for the
Rating/Risks wizard pages under the legacy rate authorized here -- a
bare ``api/v2/quotes/rate`` module-path check would key on a new
namespace no existing grant covers.

Layering: orchestration lives in the adapter
(``service/quote_services/adapters/rate_revision.py``) with every read
behind a repository, and the service projects its own result
(``RateRevisionResult``, plain values); this layer parses, translates
errors and serializes -- it assembles nothing. Engine and guard failures
re-raise as marshmallow ``ValidationError`` so the shape is the legacy
cascade's flat ``messages`` list (``standard_error`` parity) rather
than the ``_base_`` / ``_rules_`` dict a ``BCValidationError`` would
envelope them in, so every failure of this endpoint answers in one
shape.

Parameters
----------
quote_id : str
    UUID of the revision to rate (the quotes v2 convention: ``quote_id``
    IS the revision id). Required by the request schema.

Returns
-------
success : bool
messages : list of str
    On a refusal or failure (success False), the flat legacy list --
    ALWAYS a list of strings, never the ``_base_`` dict shape: every
    exception this endpoint does not translate is caught, logged with the
    revision id, and re-raised as a sanitized ``RATE_UNEXPECTED_FAILURE_
    MESSAGE``.
error_code : str, optional
    Present only for the one machine-readable failure: the rate delta
    committed but its response could not be built
    (``'rate_saved_response_unavailable'``). Absent from every other
    response, success or failure.
data : dict
    ::

        {
            # ...the retrieve_revision_details payload of the rated
            # revision (items, sub_lines, premiums, rate_capability)...
            'delta_summary': {},  # per-table counts of the rate delta
            'uwr_outcome': {},    # the server-side UWR run's outcome
            'risk_rates': {}      # property id -> rate_risk-shaped figures
        }

Code
Rate a full quote with all the necessary information.

If external_system_reference is provided, it will be used to retrieve the latest non archived quote.

rate_quote

Code
Retrieve a full quote with all the necessary information.

The Rate click's vendor integrations, split out of the rate itself: HazardHub-on-rate and the property lookups configured with runWhenQWUserClicksCalculateRate, for EVERY live risk of the revision in one call.

Code
The legacy ``rate_risk`` ran these inline before rating; the unified
``rate`` is deliberately integration-free, so the wizard POSTs this
first and only rates when it succeeds -- the same abort-the-rate
semantics the legacy cascade had, made explicit. Sites with nothing
configured for the rate click answer immediately (two config reads).

Orchestration is ``QuoteService.run_pre_rate_integrations``; this layer
owns the wire shape only. Failures ride the legacy flat ``messages``
list, always -- but only the ONE reviewed vendor failure (HazardHub's own
real-rating-error raise) keeps ``rate_risk``'s verbatim
``standard_error(str(e))`` text; anything unreviewed is logged and
answered with a stable, sanitized message instead.

Parameters
----------
quote_id : str
    UUID of the revision to run the integrations for (the quotes v2
    convention: ``quote_id`` IS the revision id).

Returns
-------
success : bool
messages : list of str
data : dict
    ::

        {
            'ran': bool,          # False = nothing ran; see reason
            'alert_messages': [], # lookup alerts + selection conflicts
            'reason': str         # '' | 'unsupported' | 'nothing-configured'
        }

Bind (submit) a new-business quote from the agent UI wizard.

Code
Routes through the shared new-business bind choke point
``QuoteService.bind_quote``, so the same two tenant advanced settings that
govern ``bind_full_quote`` also govern this path. (Mid-term
change/endorsement binds go through ``submit_change`` instead and are NOT
gated by these settings.) Both DEFAULT OFF (unchanged behavior until
opt-in):

* ``integrations`` / ``contact-screening-require-completion-before-bind``:
  refuse the bind unless every in-scope contact has a complete screening
  result.
* ``policies`` / ``enforce-business-rules-at-bind``: gate the bind by the
  KNOCKOUT business rules (disallowed category options, required /
  List-``Disallow`` supplemental-question knockouts, and revision-level
  underwriting prevent-continue blocks). It intentionally does NOT enforce
  the completeness/boundary checks (item mandatoriness, multiplicity,
  deductible/limit boundaries): those are build-time input guards that
  false-positive on a fully rated quote, so enforcing them at bind would
  reject the existing book.

Bind (submit) a mid-term change/endorsement.

Code
NOTE: the two new-business bind-posture settings
(``contact-screening-require-completion-before-bind`` and
``enforce-business-rules-at-bind``) do NOT apply here. They are scoped to
new-business binds (``bind_full_quote`` / ``submit_application``) for
BC-22935; change/endorsement binds keep their existing behavior.

summary

turn_quote_into_application

update_e_delivery_enabled