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 transaction that has not yet been created in the system:

POST /policy/{tenantLocator}/policies/{policyLocator}/{transactionType}/underwritePreview

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.

Billing Previews

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 both a stateful and stateless manner.

A stateful preview of prospective invoices may be generated for a prospective quote or policy transaction, given that the quote or policy transaction has been created and is in a priced state. See the Preview Invoices for Quote and Preview Invoices for Transaction endpoints in the Invoices API for details.

A stateless preview of prospective installments or invoices may be generated for a hypothetical quote by providing the results of its stateless pricing preview in the request. See the Preview Installments for Stateless Quote endpoint in the Installments API and the Preview Invoices for Stateless Quote endpoint in the Invoices API for details.