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 for lookup and reference.

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.

These string are part of configured Numbering Plans. Each numberable entity type can be associated with a numbering plan which describes how numbers are to be generated, using the format property of the plan.

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 each ranging from 0 to 9, and 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, you 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 numberingPlan field (referring to the name of a specific numbering plan). Plans can specify the following:

  • format: The template used to generate an entity number from the sequential core number

  • initialCoreNumber: The starting point in the sequence, not including any delimiting characters, prefixes, suffixes, etc

  • termNumberFormat: A special format string for constructing term numbers given a policy number

  • copyFromQuote: A boolean flag to determine whether, when quotes are issued, the policy should share the same number as the quote

Numbering is disabled when the numberingPlan property on the entity type is left empty.

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.

Numbering strings can use any letter casing and/or numeric digits.

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.

Important

The backslash \ character in the format string must itself be escaped when embedding the string in JSON. So in a JSON file, the above format string would look like "\\T.{policyNumber}-{termNumberPlusOne}". This double-escaping must be done for all escaped characters in format strings that are to be embedded in a JSON payload.

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 use the policy number as a starting point, and 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 32 characters long. (Generally, core numbers should be much shorter than this.)

  • The overall format string must be no more than 64 characters long.

  • Generated numbers must be no more then 128 characters long.

  • Numbering strings for products and regions can be no more than 12 characters long.

  • Consecutive separators are not supported, for example, .- within a format string.

See Also