Previews

Socotra enables users to preview the outcome of certain key operations without committing to the changes.

Overview

As detailed in the feature guides for Quotes and Policy Transactions, the results of data validation, pricing, and underwriting are persisted once the entity is successfully transitioned to that step of the lifecycle. For many entities in the system, once they have transitioned to or beyond the validated state, their extension data becomes immutable, which may prove too rigid for certain quoting experiences.

To provide implementers with flexibility in developing tailored experiences for selling and servicing policies, Socotra enables previews of the results of certain key Quote and Policy Transaction operational functions, including:

  • Validation

  • Pricing

  • Underwriting

  • Invoicing

In most cases, this preview can be executed in both a stateful or stateless fashion.

Stateful Preview

In this context, “stateful preview” refers to a request that the system produce what the result of some state transition will be, for an entity (quote or transaction) that has already been created and stored in the system. This is achieved by setting the stateless boolean query parameter to true.

Example

Request a preview of the validation result for an existing quote that is in a draft state, without advancing to the validated state:

PATCH /policy/{tenantLocator/quotes/{quoteLocator}/validate?stateless=true

Stateless Preview

“Stateless preview” refers to a request that the system produce what the result of some key function would be, for an entity (quote or transaction) that has not yet been created in the system.

For example, before asking the system to persist a draft quote via a Create Quote request, a user can use the same request payload to have the system show what the price for the hypothetical quote would be, without having to create and store the entity or the price.

In order for the system to produce a preview of a hypothetical policy transaction, the underlying base policy must exist, and be specified in the stateless preview request.

Example

Request a price preview for a hypothetical quote that has not yet been created in the system:

POST /policy/{tenantLocator}/quotes/pricePreview

Request a preview of the underwriting result for a hypothetical quote that has not yet been created in the system:

POST /policy/{tenantLocator}/quotes/underwritingPreview

Note

In order for the system to produce either a stateful or stateless preview result for pricing or underwriting, it is necessary that the request entity would pass validation.

Invoice Preview

Often insureds will want to know the specific details of payments they will be required to make, given a prospective quote or policy transaction. Socotra enables this by extending the preview capability to the billing service in a predominantly stateful manner. See the Preview Invoices for Quote and Preview Invoices for Transaction endpoints in the Invoices API for details.

Note

Currently, the prospective quote or policy transaction must be in the priced state to request a preview of the prospective invoices.

Support for a fully stateless invoicing preview may be added in a subsequent release.