Quotes

The Quotation ("Quote to Issue") process controls how a new policy is constructed and issued. In Socotra, Quotes are entirely distinct from Policies, with a dedicated workflow. The nominal flow includes the following events:

Quote Creation in Draft state
Quote Validation (including built-in config validation and custom scripted validation)
Pricing
Underwriting Checks
Acceptance
Policy Issuance

The typical quotation workflow looks like this:

Quotes must have all the data required to create an issued policy. Policies are typically created in issued state; there is no such thing as an unissued policy. Therefore:

All custom data that a policy has for a given product must also be on the Quote; and
There is no extra requirement or opportunity to inject additional data when the Quote is issued and the policy is created, although this may become a future capability.

Quote State Flow

Quotes have a quoteState property, which can take any of the following values:

Standard Flow

draft: The quote is mutable, so its data, coverage terms, and other attributes (like startTime, endTime, etc.) can be changed. Newly created quotes are in draft state. This is the only state that allows these changes. Note: the productName is the basis for the quote, including its validation operations, and as such is not mutable after creation.
validated: The quote has been validated, both against its configuration (based on its product) and any custom validation.
priced: The quote has pricing generated.
underwritten: The quote has passed underwriting checks.
accepted: The quote has been accepted but not yet issued. This state requires successfully passing underwriting checks.
issued: The quote has been issued, creating the resultant policy.

Atypical States

underwritingBlocked: The quote cannot proceed due to underwriting flags, but is not in a denied state of declined or rejected.
declined: The quote did not pass underwriting but it can be re-underwritten or reset.
rejected: The quote did not pass underwriting and cannot be re-underwritten or reset, but can be discarded.
refused: Indicates that the customer has decided not to accept coverage. These quotes can be discarded or reset.
discarded: The quote has been disposed of so it cannot be processed further. It will not appear in any response unless directly fetched by locator.

Quote Reset

You may wish to change data or attributes on a quote that has been validated or even progressed past validation. Instead of a complex system determining and allowing "safe" mutations under such conditions, Socotra allows quotes to be "reset" to draft.

Conditions:

Quotes in states validated, priced and underwritten can be directly reset.
A quote that has progressed to an accepted state may only be reset if it has first been refused.
Issued quotes result in the creation of a policy, and cannot be reset.

When a quote is reset, it will return to draft state, and all data that is mutable in draft state can be changed. This includes:

On reset:

All pricing will be deleted.
An option will allow underwriting flags and documents to be deleted, cleared, or left intact.

The pricing information that is deleted on quote reset is not recoverable.

Grouping

See the Quote Groups guide for details on functionality that allows you to group quotes and enforce uniformity and state uniqueness rules.

Calculating End Time

When creating a quote through the Create a Quote API endpoint, the endTime can be specified manually. However, if no endTime value is provided, the system will instead calculate the endTime automatically based on the termDuration, durationBasis, and startTime values specified in the request.

For example, if the termDuration value is set to 6, and the durationBasis value is set to months, the system will set the endTime value to 6 months after the startTime.

When updating a quote through the Update a Quote API endpoint, the system will recalculate the endTime the same way if the resetEndTime flag is set to true in the request.

Time Zones

Tenants have a default time zone. If a Quote is created with a specified time zone, that time zone will be persisted on the quote. If a Quote is created without specifying a time zone, the time zone will be copied from the tenant's default. Either way, the time zone will be persisted and the tenant default is no longer used for that quote.

Time zones are mutable for quotes in draft state only.

Updating Account Locator

The accountLocator associated with a quote can be updated through the Update a Quote API endpoint as long as all of the following criteria are met:

The quote must be in the draft state
The target account must be in the validated state
The target account must be an account type that has been configured to support the quote's product type

Currencies

As with time zones, quotes will use a specified currency if specified, and otherwise copy the tenant default currency. These, too, will be mutable in draft state only.

Error Handling

When trying to advance multiple steps, say from draft to issued, the progression can stop because of things like:

Validation errors
Underwriting failures
Plugin errors

If this happens, the response might not have all the information needed to resolve the situation. For example, the QuotePriceResponse doesn't have validation error info. To resolve this,

Examine the state of the quote.
See that it is still draft, indicating there was a validation failure.
Attempt to validate it.