Deferring validation

During submission processing, PolicyCenter executes validation to ensure a submission meets all requirements. For example, suppose an insurer has a rule stating that all Personal Auto vehicles must have collision coverage. As the submission is being created, PolicyCenter identifies any vehicles without collision coverage and prevents further processing until the coverage is added.

For Cloud API, this default validation behavior is referred to as immediate validation. In this approach, validation is provided with each call. A validation error in one call can prevent later calls from executing. This approach is appropriate for caller applications the build submissions interactively, such as those backing a user interface.

There is a second behavior called deferred validation. In this approach, validation takes place only after the caller application has put the submission into what it believes to be a consistent state. This is an option for non-interactive caller applications with sufficient authorization. This approach can simplify submission processing by preventing validation checks when the submission is known to be in an inconsistent state.

The deferValidation query parameter

Deferred validation is implemented by use of the deferValidation query parameter. This is a Boolean query parameter that defaults to false. It is available on the following sets of endpoints:

  • Coverable endpoints (such as POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles)
  • Coverage endpoints (such as POST /jobs/{jobId}/lines/{lineId}/coverages)
  • Question endpoints such as POST /job/v1/jobs/{jobId}/questions)

When the query parameter is set to true, the following behaviors are implemented:

  • POST/PATCH of a coverable
    • Disable availability and editability checking for risk model fields. If a risk model field is unavailable, its availability bit will be set and it will be updated anyway.
    • Disable availability checking for typekeys
    • Disable min/max checking for risk model fields
  • POST/PATCH of a coverage
    • Disable availability checking of the coverage (or condition or exclusion) itself
    • Disable availability and editability checking of coverage terms. If a coverage term is unavailable, it will be created and set anyway during the update.
    • Disable availability checking on coverage term options and packages
    • Disable availability checking on coverage term typekeys
    • Disable min/max checking on direct and datetime covterms
  • DELETE of a coverage
    • Allow deletion even if the coverage is marked as required
  • PATCH of question answers
    • Force creation of the associated AnswerDelegate entity if it has not already been created, which means it was unavailable the last time questions were synced

For example, suppose Personal Auto submission pc:6066 has vehicle 103, which is located in Oklahoma. The caller application plans to do the following:

  1. PATCH the vehicle so that it is located in Texas
  2. POST a "PIP - Texas" coverage to the vehicle

The POST will fail. This is because, when the vehicle was created, the availability logic was cached. This logic identifies that the vehicle is in Oklahoma.

There are two solutions to the problem. You could execute a POST /vehicles/{vehicleId}/sync-coverages before POSTing the coverage. Alternately, you could use the deferValidation query parameter when POSTing the coverage For example:

POST /job/v1/jobs/pc:6066/lines/PersonalAutoLine/vehicles/103/coverages?deferValidation=true

You cannot defer validation when quoting a job. Validation is always executed when the job is quoted.

Authorization to defer validation

The deferValidation query parameter is not available to all callers by default. In order to use the query parameter, the caller must be associated with a role whose role.yaml file has the deferProductModelValidation special permission.

For more information on authorization and special permissions, see the Cloud API Authentication Guide.

Limitations to deferred validation

The deferValidation query parameter can reduce the number of times you need to call the /sync endpoints. For example, the query parameter lets you set values that are unavailable given the current state of the job, but that will be available by the time the job data is complete. (Without the query parameter, you would need to call the appropriate /sync endpoint before adding the unavailable values.)

However, the query parameter may not entirely eliminate the need to call the /sync endpoints. For example, suppose you are modifying a job using deferred validation. Initially, there is a coverage that is unavailable. Later, the state of the job data causes the coverage to become available, and the coverage is required when it is available. Because validation has been deferred, there is no indication that a required coverage is missing until you attempt to quote the job. Once the quote fails validation, you will still need to call the appropriate /sync endpoint.

The createDefaultCoverages query parameter

By default, when you create a coverable, PolicyCenter automatically creates all coverages (and conditions and exclusions) that meet the following criteria:

  • They are available when the call is made
  • They have an existence type of "Required" or "Suggested"

Sometimes, a job may not want these default coverages. But it can be cumbersome for a caller to determine what coverages were added automatically and then remove the undesired ones. In these situations, it may be easier to have a coverable with no default coverages.

You can create a coverable without default coverages using the createDefaultCoverages query parameter. This is a Boolean query parameter whose default is true. It is available on the following sets of endpoints:

  • Line endpoints
    • For example, POST /job/{jobId}/lines​
    • Note that POST /lines endpoints are present only for multi-line products
  • Non-line coverable endpoints
    • For example, POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles
  • The POST /submissions endpoint
    • This suppresses the creation of coverages, conditions, and exclusions on the default policy lines.
    • This also suppresses the creation of coverages, conditions, and exclusions on any coverable that is created automatically, such as a Commercial Property's default primary location coverable.

When the query parameter is set to false, the following behaviors are implemented:

  • POST of a coverable
    • Disable creation of default coverages, exclusions, and conditions

For example, suppose you have Personal Auto submission pc:6066. A vehicle is POSTed to the submission. The following call will create the vehicle with all default coverages.

POST /job/v1/jobs/pc:6066/lines/PersonalAutoLine/vehicles

In contrast, the following call will also create the vehicle, but with no default coverages.

POST /job/v1/jobs/pc:6066/lines/PersonalAutoLine/vehicles?createDefaultCoverages=false

This query parameter does not have special permissions. Any caller that can access coverable endpoints can also use this query parameter.