# External Numbering Support



The Socotra Insurance Suite provides a built-in [numbering system](/configuration/general-topics/entity-numbering) 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](/configuration/general-topics/events) and [webhooks](/configuration/general-topics/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](/configuration/plugins/automation)

<Callout>
  Standard [numbering plans](/configuration/general-topics/entity-numbering) can be used in combination with external numbering plans, as they do not interfere with each other.
</Callout>

Configuration [#configuration]

A list of `externalNumberingPlans` can be defined within the top-level <ApiLink name="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:

```json
{
	"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`

<Callout>
  The `trigger` value does not have a default value. It must be explicitly set by the user.
</Callout>

An external numbering plan can be added to a product by specifying the name of the plan in the `externalNumberingPlan` field within the corresponding <ApiLink name="ProductRef" /> configuration object.

For example:

```json
{
	"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:

```json
{
	"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 [#set-the-reserved-policy-number]

The `reservedPolicyNumber` can be set when creating a quote or through the <ApiLink name="setReservedPolicyNumber" /> API endpoint.

For example:

```json
{
	"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](/configuration/data-extensions/static-data) field if you want to search quotes by `reservedPolicyNumber`.

Events [#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:

<ApiSchema name="QuotePolicyNumberData" />

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

<ApiSchema name="NumberingData" />

Event Handling [#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](/configuration/general-topics/webhooks) and [Automation Plugin](/configuration/plugins/automation) feature guides for more information.

See Also [#see-also]

* [Entity Numbering](/configuration/general-topics/entity-numbering)
* [Events](/configuration/general-topics/events)
* [Webhooks](/configuration/general-topics/webhooks)
* [Automation Plugin](/configuration/plugins/automation)


## API Reference

QuotePolicyNumberData
Properties:
  quoteLocator (ulid, required)
  quoteState (Enum draft | validated | earlyUnderwritten | priced | underwritten | accepted | issued | underwrittenBlocked | declined | rejected | refused | discarded, required)

NumberingData
Properties:
  entityLocator (ulid, required)