External Numbering Support

The Socotra Insurance Suite provides a built-in numbering system for quotes and policies. However, some businesses may prefer to implement their own numbering logic for a number of reasons, including:

  • Numbering logic may depend on a large number of factors, such as policy data, account data, and producer data

  • Numbering logic may need to be executed at a specific stage in the policy lifecycle

  • The Socotra Insurance Suite may not currently support certain numbering requirements

In order to accommodate these possibilities, our platform provides the following functionality:

  • Quotes have an optional reservedPolicyNumber field, which automatically becomes the policyNumber when the resulting policy is issued

  • An API endpoint can be used to set the reservedPolicyNumber for a quote

  • The reservedPolicyNumberRequired configuration field can be used to force quotes to have a reservedPolicyNumber set in order for a policy to be issued

  • External systems can be automatically notified via system events and webhooks when numbering is requested for a quote, and when the reservedPolicyNumber for a quote is modified

  • Custom numbering logic can be implemented via the Automation Plugin

Note

Standard numbering plans can be used in combination with external numbering plans, as they do not interfere with each other.

Configuration

A list of externalNumberingPlans can be defined within the top-level ConfigurationRef object. Each list item contains a map from a numbering plan name to a settings object. Currently, settings objects only contain a trigger field, which instructs the system to trigger a policy.quote.policyNumberRequested event when quotes move to the specified state.

Here’s a configuration example:

{
    "externalNumberingPlans": {
        "examplePlan": {
            "trigger": "accepted"
        },
        "anotherPlan": {
            "trigger": "priced"
        }
    }
}

Events will only be triggered after a quote successfully moves to the specified lifecycle state.

The trigger value must be one of the following quote lifecycle states:

  • validated

  • earlyUnderwritten

  • priced

  • underwritten

  • accepted

  • issued

Note

The trigger value does not have a default value. It must be explicitly set by the user.

An external numbering plan can be added to a product by specifying the name of the plan in the externalNumberingPlan field within the corresponding ProductRef configuration object.

For example:

{
    "ExampleProduct": {
        "externalNumberingPlan": "examplePlan"
    }
}

The reservedPolicyNumberRequired field within ProductRef configuration objects can force quotes of the corresponding product type to have a reservedPolicyNumber set in order for a policy to be issued.

For example:

{
    "ExampleProduct": {
        "externalNumberingPlan": "examplePlan",
        "reservedPolicyNumberRequired": true // Default is false
    }
}

The default value for reservedPolicyNumberRequired is false.

When reservedPolicyNumberRequired is set to true, attempts to issue quotes of the corresponding product type without a reservedPolicyNumber set will fail.

Set the Reserved Policy Number

The reservedPolicyNumber can be set when creating a quote or through the Set Reserved Policy Number API endpoint.

For example:

{
    "reservedPolicyNumber": "4263716"
}

The reservedPolicyNumber field is not search-indexed, meaning quotes cannot be searched by reservedPolicyNumber. When a quote is issued, the policyNumber value will be automatically set to the current reservedPolicyNumber value, and the reservedPolicyNumber value will become searchable through the policyNumber field. You can manually set the quoteNumber value to the reservedPolicyNumber value or add the reservedPolicyNumber to a static data field if you want to search quotes by reservedPolicyNumber.

Events

A policy.quote.policyNumberRequested event is triggered when a quote moves to the state specified in the externalNumberingPlan associated with its product type, and has the following payload:

quoteLocator
quoteState

A policy.quote.policyNumberAssigned event is triggered when the reservedPolicyNumber for a quote is modified, and has the same payload as other numbering events:

entityLocator

Event Handling

Webhooks can be configured to call external API endpoints when the policy.quote.policyNumberRequested or policy.quote.policyNumberAssigned events are triggered.

Alternatively, the Automation Plugin can execute custom numbering logic in response to these events.

See the Webhooks and Automation Plugin feature guides for more information.

See Also