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.


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 be accepted 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.

  • Draft and Quoted quotes may be Discarded.

  • 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.


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.


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.


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.


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.