Quotes
Often prospective insureds wish to consider different options for coverage and price. Rather than create multiple versions of a policy, only to bind one and discard the rest, Socotra supports multiple quotes within a single policy, each of which can be considered in parallel, priced independently, and from which the insured can make a choice.
Policies contain one or more quotes. The first quote is generated automatically upon policy creation, and subsequent quotes can be generated as needed. Each quote has its own lifecycle, starting in draft
state, and one (and only one) quote may eventually be used to issue the policy.
When fetching a policy before it has been issued, its details will depend on which quote is selected
. See Selecting Quotes for more details.
After issuing a policy, the details in the accepted quote are then reflected in the policy which is accessible through the policy API. Quotes that are not used are still available for reference.
Tip
See the Quotes API topic for more information about working with Quotes through the API.
Quote Lifecycle
Quotes follow this basic lifecycle:
In addition to the basic flow of Draft → Quoted → Accepted:
A policy can be issued on the basis of an
accepted
quote. Only one quote may beaccepted
at a time, and once the policy is issued that will permanently bind that quote to the policy; it will be impossible for any other quote on that policy to be used.The Invalidate operation will move a quote back from Accepted to Quoted.
If a quote fails underwriting rules, it will become
declined
.
Quote Updates
Only quotes that are in the initial draft
state may be updated. After a quote becomes quoted
it is no longer mutable, though it can be copied and that copy is then mutable (because that copy will then be in draft
state.) See Quote Creation, below.
Quote Creation
After the policy is created it has a quote. This quote can then be copied to create a second quote which can be updated independently of the first. An optional payload can be passed which modifies the new quote before saving it. The newly created quote will be in draft
state and will therefore be mutable.
The source quote that the new quote is based on may be in any state, unless it is discarded
.
Selecting Quotes
Exactly one of a policy’s quotes may be marked as selected
. This means that that quote’s data will be used to construct the PolicyResponse object from the policy API. Also, if the policy is finalized from the policy API, the selected quote will be quoted
(if not already) and then accepted
. See Quote Lifecycle, below.
Selecting can also be used to specify that that quote is the one to be viewed in a user interface. In this case the quote being evaluated will persist from session to session. The currently selected quote is the one with the selected
flag set to true
in the PolicyQuoteResponse.
Note
The /select
endpoint is usable even by read-only users.
Pricing Quotes
Pricing for a draft
quote can be locked in by calling the /quote
endpoint. This will move the quote from draft
state to quoted
state and the quote details and its pricing will be locked from that point forward for that quote.
Important
If a quote fails underwriting rules it will not move to quoted
state. In this case it will have the state declined
and cannot be quoted or accepted. It can, however, be copied using /createNew
, and that new quote can be updated to change the data such that it will pass underwriting rules.
Accepting Quotes
Once a Quote has been chosen by the insured, the quote can then be accepted
, which means that it is the presumptive quote that will be used to issue the policy. Like quoted
quotes, no changes can be made to accepted
quotes. When accepted, an invoice that matches the quote’s pricing will be generated, and the policy’s documents will be rendered.
At most one quote per policy may be in the accepted
state, and quotes that fail underwriting will not become accepted; rather they will be marked as declined
.
Important
Accepting quotes is independent of selecting quotes. Accepting means that the quote will probably go on to be issued; selected means that that quote is default if finalizing the policy through the /policy
API if no quote is accepted
.
Invalidating Quotes
Occasionally a quote may be accepted
in error. In this case, its acceptance can be reversed (which will move it back to quoted
state and discard any generated documents.)
Issuing Policies
After the policy is issued
, quotes are kept for reference purposes only. If no quote is accepted
then the currently selected
quote will be accepted
and used for policy issuance.
After policy issuance, changes to the policy can only be made using endorsement, renewal, cancellation, or withdrawal transactions.
Discarding Quotes
Quotes which will definitely no longer be needed can be discarded
. This means they will not be included when fetching all quotes for the policy, cannot be used for acceptance, and cannot be selected
.
The last non-discarded quote on a policy may not be discarded; nor may quotes which are accepted
.
Document Rendering
The quotes feature offers control over when documents are rendered to PDF or HTML. This is controlled by adding a generatingEvent
property to each document definition in the configuration policy.json
file.
Valid generatingEvent
values for documents are:
quote
accept
issue
Valid generatingEvent
values for invoices are:
accept
issue
For example, policy.json
could have the following documents
section:
{
"documents": [
{
"displayName": "My Document for Quotation",
"fileName": "doc_quote.pdf",
"templateName": "doc_quote.template.liquid",
"generatingEvent": "quote"
},
{
"displayName": "My Document for Acceptance",
"fileName": "doc_accept.pdf",
"templateName": "doc_accept.template.liquid",
"generatingEvent": "accept"
},
{
"displayName": "My Document for Issuance",
"fileName": "doc_issue.pdf",
"templateName": "doc_issue.template.liquid",
"generatingEvent": "issue"
}
]
}
After the quote is quoted
the first document will be rendered and available in the quote’s documents
array. After the quote is accepted
the first and second will appear, and after the policy is issued
all three documents will be available.
To control when invoice documents are rendered, add an invoicing
property to policy.json
:
{
"invoicing": {
"generatingEvent": "issue"
}
}
The default event for both standard document and invoice rendering is accept
.
Note
Configuration Studio does not yet support GUI controls for the configuration settings for the document generatingEvent
. This will be added to an upcoming release. You can use the text editor mode to add generating event properties to policy.json
.