Advice and quotes

An Insurance Broker Advice Case ties a customer to the regulatory basis of an advisory process and to its outcome: needs assessment, recommendation, and customer decision. Insurance Broker Quote records hold what a carrier offered. This page describes what the forms contain and what the system checks. It also says plainly where the Desk offers no workflow for advice commands.

Who does this

Role	What the DocType permissions allow
Insurance Broker Advisor	Read, write, and create Advice Case, Needs Assessment, Risk Needs Assessment, Product Applicability Assessment, Recommendation, Recommendation Record, Customer Decision, Quote, Quote Coverage, and Submission.
Insurance Broker Manager	Read, write, and create Advice Case and Quote.
Insurance Broker Administrator	Same as Advisor on these records.
Insurance Broker Compliance	Read most advice records; read and write Product Applicability Assessment; create Initial Disclosure and read and write Remuneration Disclosure.
Insurance Broker Operations	Create and read Remuneration Disclosure; read Initial Disclosure.
Insurance Broker Auditor, Insurance Broker Read Only	Read only.

Role names follow contracts/security/roles_baseline_v1.json. See Roles and access.

Before you start

• Company Settings has Advice Enabled switched on for the company. Saving an Advice Case checks this toggle and stops when it is off (code IBC-COMPANY-SETTING-ADVICE-001).
• The customer party, a mandate version, and a regulatory context exist (see Parties and Mandates).
• The supporting records you want to link exist first: Advice Regime Version, Advisor Eligibility Snapshot, Initial Disclosure, and Product Version. These are required links on the case.
• The regulatory rule contracts ship as unapproved; read docs/operations/en/regulatory_activation.md in the source repository before you rely on any rule result.

Open the advice case list

Choose Advice Cases in the Insurance Broker workspace or in the workspace Advice/Quotes, which also has shortcuts to Tenders, Tender Invitations, Submissions, Quote Comparisons, and the reports Disclosure Gaps and Advisor Eligibility. The list loads the fields Status, Capability Status, Customer Party, and Started At, and shows a status indicator.

The advice case form

Record names follow the series IB-ADVICE- plus a five digit counter. The form has three sections.

Section	Fields
Advice case	Company, Customer Party, Status, Started At (all required); Completed At.
Regulatory basis	Mandate Version, Regulatory Context, Advice Regime, Advisor Eligibility, Initial Disclosure, Product Version, Capability Status (all required); Product Information Receipt, Remuneration Disclosure, Conflict Assessment, Delivery Evidence (optional links).
Advice outcome	Needs Assessment, Product Applicability Assessment, Recommendation, Customer Decision (links).

The Status select offers draft, assessment, market_analysis, recommendation, decision, completed, cancelled, and assignment_required. Capability Status offers model_only, manual_only, validated, blocked, and not_applicable. The fields for advisor handoff and eligibility invalidation (Assignment Required From Status, Handoff Advisor, and the invalidation counters and timestamps) are read only.

Supporting records

Record	Series	Content
Initial Disclosure	hash	Party Identity, Country (DE, AT, CH), Broker Role, Register Reference, Complaints Body, Market Scope, Content Digest, Version, Status (draft, issued, superseded).
Delivery Evidence	hash	Source DocType and Name, Recipient Party, Channel (email, portal, postal, in_person, other), Delivered At, Content Digest, Provider Receipt Reference, Classification. Can be created, not edited, by Administrator, Compliance, and Operations.
Remuneration Disclosure	hash	Party Identity, Advice Case Reference, Agreement, Mode (commission, client_fee, mixed), Amount Description, Content Digest, Customer Confirmation, Posting Requested, Status (draft, confirmed, superseded).
Needs Assessment	IB-NEEDS-	Advice Case, Version, Customer Objectives, Identified Risks, Coverage Needs (JSON), optional Budget Constraints and Existing Cover, Data Digest, Recorded At.
Risk Needs Assessment	IB-RNA-	Advice Case, Status (draft, assessed, rejected), Needs (JSON), Assessed At, Evidence Reference.
Product Applicability Assessment	IB-APPL-	Advice Case, Product Version, Regulatory Context, Status (proposed, assessed, rejected), Decision Code, Evidence Reference, Assessed At.
Recommendation	IB-REC-	Advice Case, Quote, Product Version, Reasoning, Customer Needs Mapping, Conflicts Assessed, Product Version Changed, Revalidated, Recorded At, Digest.
Recommendation Record	IB-RREC-	Advice Case, Risk Needs Assessment, Product Applicability Assessment, Reasoning, Customer Needs Mapping, Conflicts Assessed, Recorded At, Digest.
Customer Decision	IB-DECISION-	Advice Case, Decision (accept_recommendation, choose_alternative, decline, defer), optional Selected Quote and Deviation Reason, Decided At, Decision Maker, Delivery Evidence (required), Signature Reference.

Quotes

A Quote (series IB-QUOTE-) belongs to an advice case and a carrier. Required fields: Company, Advice Case, Carrier, Product Version, Quote Reference, Quote Version (default 1), Is Current (default on), Status, Coverage Basis Digest, and Terms (JSON). Status offers requested, received, declined, withdrawn, expired, and accepted. Optional fields are Submission, Previous Quote, Revision Key, Valid Until, Annual Premium, Currency, and Document Reference. A Quote Coverage record links a quote to a Coverage with its own digest and a Status of proposed, selected, or rejected.

A quote revision is immutable. Once a quote has been saved, any further save is rejected with IBC-QUOTE-REVISION-IMMUTABLE-001; deleting or renaming is rejected with the same code. A change is a new quote:

1. The new quote has Quote Version one higher than its source and Previous Quote pointing to the source. Version 1 must have no Previous Quote (IBC-QUOTE-REVISION-LINEAGE-001) and a later version must have one (IBC-QUOTE-REVISION-LINEAGE-002).
2. The service insurance_broker_core/services/quote_revisions.py creates such a revision from a current quote and a revision key, marks the old quote as not current, and returns the existing revision when the same revision key is used again. A source quote that is no longer current is rejected with IBC-QUOTE-REVISION-STALE-001.
3. A Quote Comparison record (series IB-QCOMP-) refers to quotes by name and only accepts current quotes of the same company; otherwise it fails with IBC-QUOTE-COMPARISON-STALE-001 or IBC-QUOTE-COMPARISON-COMPANY-001.

What the system checks

Check	Code
Advice Enabled off for the company	IBC-COMPANY-SETTING-ADVICE-001
Completing a case without one of the required links (mandate version, regulatory context, advice regime, advisor eligibility, initial disclosure, product version, needs assessment, product applicability assessment, product information receipt, remuneration disclosure, conflict assessment, delivery evidence, recommendation, customer decision)	IBC-ADVICE-COMPLETION-001
Completing a case whose Capability Status is not validated	IBC-ADVICE-CAPABILITY-001
Completing a case without a matching advice capability admission for the recommended product class	IBC-CAP-NOT-ADMITTED-001, IBC-CAP-BLOCKED-001, or IBC-CAP-UNRESOLVED-001
Changing the original eligibility snapshot of a saved case	IBC-ADVISOR-ELIGIBILITY-INVALIDATED-001
Recommendation without reasoning or needs mapping	IBC-RECOMMENDATION-REASON-001
Product version changed without revalidation	IBC-RECOMMENDATION-REVALIDATE-001
Remuneration mode client_fee or mixed with Posting Requested	IBC-REMUNERATION-POSTING-001
Saving an existing quote	IBC-QUOTE-REVISION-IMMUTABLE-001

Status changes on a saved advice case or quote through an ordinary form save are rejected with IBC-STATE-MACHINE-STATUS-SAVE-001.

State machines in short

The contract advice_case_v1 defines draft, assessment, recommendation, completed, and cancelled, with the commands start_assessment, recommend, complete, and cancel for the role Insurance Broker Advisor. The contract quote_v1 defines draft, issued, accepted, withdrawn, and expired, with the commands issue, accept, withdraw, and expire. The status options on the forms are wider than these contracts, so use the contracts as the reference for allowed transitions: State machines.

Reports

Disclosure Gaps lists advice cases of one company with Customer, Status, Started At, Completed At, Mandate Version, Regulatory Context, Advice Regime, and Capability Status. It has a Status filter in the API and is restricted to Insurance Broker Administrator and Insurance Broker Compliance.

What this page does not cover / current limits

• No Desk path for advice commands is evidenced. The Desk scripts for the advice list only define the list columns and the indicator. There is no button and no API module for start_assessment, recommend, complete, or cancel in the Desk code, and the status field cannot be changed by a form save.
• Quote revisions are created by a service function. In the code it is reached from the tender API; no Desk button for it is evidenced. Tender steps are covered in Tender overview.
• The disclosure forms only store the evidence fields listed above (digests, references, delivery details); they do not generate or send documents.
• Rule results from the regulatory engine are not covered here. The engine is inert by default; see the activation page in the source repository linked below.

Capability status

contracts/w0/capability_matrix_v1.json lists the processes advice, quote_comparison, and placement. The default status is model_only for DE, AT, and CH, and the list validated_claims is empty. For the special classes Fonds and Diverse, advice and quote_comparison are blocked. Only a validated status may be claimed publicly.

Related pages

• Policies
• Tender overview
• Product catalog
• Regulatory activation
• Capability claims