Entity Numbering
Overview
Entity numbering is a structured way for the system to generate “numbers” of various kinds, such as an account number or policy number.
Numbering is available for these entities:
Accounts
Quotes
Policies
Policy Terms
Invoices
Disbursements
Entities that are insured-facing and are likely to be attached to a paper document or shown prominently on a screen are generally capable of being assigned a number. This is particularly important in customer service situations, where the insured will present a problem and then can be asked for the relevant number.
Note
While the data described here are called “numbers,” they really are strings and aren’t typically interesting from a numerical perspective.
Process
For each entity type that is to have numbers assigned, a template string called format
is added in configuration to describe how the numbers should be generated. Then, when entities are created, the format string is applied to the next sequential “core number” to create a full number.
For example, a format string for a personal auto product might look like: X#####\-{product}
. For this, the system will generate a sequence of core numbers, each starting with a character from A
to Z
, based on the X
in the format, and then five digits, based on the #
signs in the format. If the personal auto product defined a numbering string of “PA”, then the numbers would have a -PA
suffix. The number sequence for personal auto policies would then be:
A00000-PA
A00001-PA
…
A99999-PA
B00000-PA
B00001-PA
etc.
The starting point of the “core” part of the sequence above is A00000
. This starting point can be controlled using the inititialCoreNumber
property of the numbering plan. For example, yuou can set it to "G51234"
and then the first generated number will be G51234-PA
. (See Configuration, below.)
The numbering process is triggered immediately after validation for entities that have a validation step. For other entity types, numbers are generated on creation.
Configuration
Each numberable entity type has an optional numberingPlan
property, with the name of the numbering plan for that type. Any number of numbering plans can be created, and each one can have a different will have a numbering name field (referring to a numberingPlan). Plans can specify the following:
format
: The template used to generate an entity number from the sequential core numberinitialCoreNumber
: The starting point in the sequence, not including any delimiting characters, prefixes, suffixes, etctermNumberFormat
: A special format string for constructing term numbers given a policy numbercopyFromQuote
: A boolean flag to determine whether, when quotes are issued, the policy should share the same number as the quote
Numbering is enabled by setting the numberingPlan
property on the entity, with the name of one of the plans defined as above.
Note
For invoices, the plan is defined for the account type using the account configuration’s invoiceNumberingPlan
property.
Prefixes, Suffixes, and Numbering Strings
Numbering Strings are assigned to product types and regions and can be used in format
templates to add additional context. For example, if the US_WEST
region has numberingString: "USW"
and the Business Auto product has numberingString: "BA"
, then a business auto policy created in the US West region with a format of "{product}-XX-#####-{region}"
could then have a number assigned like "BA-TQ-23456-USW"
.
The {product}}
string only applies to quotes and policies. The region string applies to any supported entity type, and will use the relevant account’s region for all but quotes and policies. Quotes and policies will use their own assigned region.
Numbering strings can be used anywhere in the format, and do not need to be strictly defined as prefixes or suffixes. For example, "##{product}-#X"
is a valid format string.
Additional Characters
Other valid characters can be inserted into the format string by escaping them: \A\B\C\9-#######
would result in a prefix of "ABC9"
in generated numbers.
Note
Hyphens (-
), periods (.
) and underscores ( _
) in the format string do not require escaping.
Term Numbers
Term numbers can be generated, but they are configured in a different way. They always use the policy number as a starting point, but can be decorated with additional characters, or the product or region numbering strings.
To enable term numbers, set the termNumberFormat
property in the numbering plan. You can use any of the following in this format:
{policyNumber}
{termNumber}
(starts with zero for the initial issuance term){termNumberPlusOne}
(starts with one for the inital issuance term)Separators (periods, hyphens, and underscore characters)
Escaped characters
For example, if policy number ABC123Z
was created, and the term number format is specified as \T.{policyNumber}-{termNumberPlusOne}
, then the first term number for that policy will be T.ABC123Z-1
.
Overriding Automatically Generated Numbers
Entity numbers can be set or changed by calling the associated PATCH
endpoint. These include:
If a user provided Number is a duplicate for an entity of that type, the operation will fail.
Note
Setting numbers is not supported for entities are have automatic numbering enabled.
Fetch
Usually there will be at most one entity with a given number, but there can be more than one match if numbers have been overridden in the API, or duplicate numbers are used in migrated data. Each of these endpoints will return the matching entities as an array:
Error Handling
If a number fails to generate, the number for that entity will remain empty and an event stream event will be generated.
Limitations
The
initialCoreNumber
must be at least one character long, and not more than 36 characters long.The overall
format
string must be no more than 64 characters long.Generated numbers must be no more then 128 characters long.
Consecutive separators are not supported, for example,
.-
within a format string.