Policy change

A policy change modifies a policy in between the effective and expiration dates. This transaction type can be used to apply changes to a policy, except for those that involve revising its effective date or the producer of record. For a general overview of how to conduct policy transactions using the system APIs, see Policy transactions. For details on the business functionality of policy changes and other policy transactions in PolicyCenter, see Application Guide.

Change the policy

Initiate a policy change transaction.
Submit a business action POST to the /policy/v1/policies/{policyId}/change endpoint. The request payload must include the job effective date.
```
{
    "data": {
        "attributes": {
            "jobEffectiveDate": "2020-08-18"
        }
    }
}
```
The response payload contains the associated job, which is in Draft state. Use the job ID in subsequent calls.
Modify the job as necessary.
Modifying actions will depend on the LOB and product. For example, in the case of a personal auto line, a caller could add a driver or revise driving percentages of a vehicle.
For more information on how to modify a policy within the context of a job, see Overview of modifying jobs.
Sync coverages and modifiers.
To apply coverages, submit a business action POST to the /job/v1/jobs/{jobId}/lines/{lineId}/sync-coverages endpoint. To apply modifiers, submit a business action POST to the /job/v1/jobs/{jobId}/lines/{lineId}/sync-modifiers endpoint.
Generate a quote.
Submit a business action POST to the /job/v1/jobs/{jobId}/quote endpoint.

Complete the policy change transaction.

The following table illustrates the two ways that a quoted policy change job can be completed:


Transaction outcome	Condition	Job status	Endpoint
Accepted	The account holder and insurer agree to the quote, and all necessary paperwork has been received by the insurer. The policy is bound and issued.	Bound	`/job/v1/jobs/{jobId}/bind-and-issue`
Withdrawn	The quote contains erroneous data.	Withdrawn	`/job/v1/jobs/{jobId}/withdrawn`

Submit a business action POST to the relevant endpoint.

Preemptions

A preemption is an event that occurs when two or more jobs are created from the same base policy period. The first job to be bound preempts the second job. If you want to continue with the second job, it must be modified to handle the changes made by the first job. Preemptions occurs most commonly with policy changes.

For example, suppose that there is a bound personal auto policy with a single car. A policy change is started to add a motorcycle to the policy. Then, while the first job is still in progress, a second policy change is started that adds a van to the policy. The motorcycle job has no knowledge of the van, and the van job has no knowledge of the motorcycle. If the motorcycle job is bound first, it will preempt the van job. The policy now has both a car and a motorcycle on it. The van job was only aware of the car. Before the van policy change can be completed, it must be modified to include the motorcycle.

PolicyCenter provides support for working with preemptions. PolicyCenter identifies when a job has been preempted. It provides a list of information on the preempting job that is not present in the preempted job. It also provides "handle preemption" functionality that copies information from the preempting job over to the preempted job. For more information, see the Application Guide.

Similarly, Cloud API provides support for preemptions. For a preempted job, you can view information about the preempting job and execute "handle preemption" functionality. Similarly, when a policy change is bound and there is an existing renewal for the policy, you can apply changes from the policy change to the renewal.

Identifying that a job has been preempted

When a job has been preempted, attempts to bind the job fail. PolicyCenter returns a BadInputException similar to the following:

"userMessage": "Cannot take action 'bind-and-issue'. See the details element for further 
information.",
"details": [
  {
    "message": "Branch 7888143943, 12/07/2021, 06/07/2022, 0006260834 has preemptions."
  }
]

You can view information about the preempting job. If you want to bind the current job, you must handle the preemptions.

Viewing preemption information

Use the following endpoint to view information about a job's preemptions:

GET /jobs/{jobId}/preemptions

The /preemptions endpoint returns two main types of information:

An array of job diffs
Information about the preempting job

The `diffs` array

The diffs array identifies all of the changes between the base job and the preempting job. These are the changes that are not in the preempted job but would need to be for the preempted job to be bindable.

Each member of the array identifies one difference between the base job and the preempting job. This includes the object (entity), the label of the diff field (field), the base job value (existingValue) and the preempting job value (changedValue). The following code shows the syntax of each job diff array member.

{
  "changedValue": <value>,
  "entity": {
    "displayName": <display name>,
    "id": <id>
  },
  "existingValue": <value>,
  "field": <value>
}

The difference can pertain to the value of a single field. For example, the following payload indicates that on a Medical Payments coverage object, the choiceTerm1 field in the base job was 5000, but the preempting job changed it to 15000.

{
  "changedValue": "15,000",
  "entity": {
    "displayName": "Medical Payments",
    "id": "85"
  },
  "existingValue": "5,000",
  "field": "choiceTerm1"
}

The difference can also pertain to the addition or removal of an object. When this occurs, a "√" is used to indicate the object is present, and a "" (an empty string) is used to indicate the object is absent. For example, the following payload indicates that a 2000 Honda Civic was not present in the base job but was present in the preempting job. (In other words, the preempting job added a Honda Civic.)

{
  "changedValue": "√",
  "entity": {
    "displayName": "2000 Honda Civic in California",
    "id": "32"
  },
  "existingValue": "",
  "field": "2000 Honda Civic in California"
},

The preempting job

The payload also includes information about the preempting job, including:

The job itself
The job's effective date
The job number
The job type

Preemption payload example

For example, suppose that there is a personal auto policy with an Acura Integra. At roughly the same time, two policy changes are started:

First policy change:
- Job number: 0004375724
- Job id of pc:421
- Effective date: 11/05/2021
- Material changes: Adds a Honda Civic and associated coverages for driver Alicia Shirley
Second policy change:
- Job number: 0004408964
- Job id of pc:505
- Effective date: 11/06/2021
- Material changes: Adds a Toyota Prius and associated coverages for driver Alicia Shirley

The first policy change is bound, causing that job to preempt the second job. As a result, the second job now has a preemption.

The following shows a portion of the response payload for a GET /preemptions for job pc:505. Note that the array of diffs in the payload contains the following information.

The effective date for the preempting job
The vehicle for the preempting job
The vehicle's collision coverage for the preempting job
The vehicle's comprehensive coverage for the preempting job
The vehicle driver for the preempting job

The payload also contains information about the preempting job.

GET /job/v1/jobs/pc:505/preemptions

{
  "count": 1,
  "data": [
    {
      "attributes": {
        "diffs": [
          {
            "changedValue": "11/05/2021",
            "entity": {
              "displayName": "4509454228, 11/04/2021, 05/04/2022, 0004375724",
              "id": "pc:421",
              "type": "Job",
              "uri": "/job/v1/jobs/pc:421"
            },
            "existingValue": "11/04/2021",
            "field": "writtenDate"
          },
          {
            "changedValue": "√",
            "entity": {
              "displayName": "2000 Honda Civic in California",
              "id": "32"
            },
            "existingValue": "",
            "field": "2000 Honda Civic in California"
          },
          {
            "changedValue": "√",
            "entity": {
              "displayName": "Collision",
              "id": "64"
            },
            "existingValue": "",
            "field": "Collision"
          },
          {
            "changedValue": "√",
            "entity": {
              "displayName": "Comprehensive",
              "id": "63"
            },
            "existingValue": "",
            "field": "Comprehensive"
          },
          {
            "changedValue": "√",
            "entity": {
              "displayName": "Alicia Shirley",
              "id": "15"
            },
            "existingValue": "",
            "field": "Assigned Driver: Alicia Shirley"
          }
        ],
        "job": {
          "displayName": "0004375724",
          "id": "pc:421",
          "type": "Job",
          "uri": "/job/v1/jobs/pc:421"
          },
        "jobEffectiveDate": "2021-11-05T00:01:00.000Z",
        "jobNumber": "0004375724",
        "jobType": {
          "code": "PolicyChange",
          "name": "Policy Change"
        }
      },
...

Handling preemptions

Once a job has been preempted, it can no longer be bound in its current state. This is because the base policy period has been modified by the preempting job, and the preempted job is now missing information present in the base policy period.

PolicyCenter provides the ability to handle preemptions. This is an action you can take on a preempted job to copy over the changes made by the preempting job. Handling a preemption brings a preempted job in line with the new version of the base period. Once you have handled preemptions for a job, you can bind it.

To handle preemptions through Cloud API, use the following endpoint:

POST /job/v1/jobs/{jobId}/handle-preemptions

You do not need to provide a request body.

Typically, handling a preemption modifies the contents of a job. Therefore, you need to quote the job prior to binding it, even if you quoted the job prior to the preemption.

Example of handling preemptions

In the previous topic, there was an example of a personal auto policy with an Acura Integra. At roughly the same time, two policy changes are started:

First policy change:
- Job number: 0004375724
- Job id of pc:421
- Effective date: 11/05/2021
- Material changes: Adds a Honda Civic and associated coverages for driver Alicia Shirley
Second policy change:
- Job number: 0004408964
- Job id of pc:505
- Effective date: 11/06/2021
- Material changes: Adds a Toyota Prius and associated coverages for driver Alicia Shirley

The first policy change is bound, causing that job to preempt the second job. As a result, the second job now has a preemption.

Now, suppose you want to handle preemptions for the second job and then bind it. (For clarity sake, portions of the response payload have been omitted in the following examples.)

First, you must handle preemptions.

POST /job/v1/jobs/pc:505/handle-preemptions

<no request body>

RESPONSE:
{
  "data": {
    "attributes": {
      "job": {
        "id": "pc:505", 
        "isPreempted": false,
        "jobNumber": "0004408964",
        "jobStatus": {
            "code": "Draft",
            "name": "Draft"
          },
        "jobType": {
          "code": "PolicyChange",
          "name": "Policy Change"
        }
      }
    }
  }
}

Next, you must quote the job.

POST /job/v1/jobs/pc:505/quote

<no request body>

RESPONSE:
{
  "data": {
    "attributes": {
      "id": "pc:505",
      "isPreempted": false,
      "jobNumber": "0004408964",
      "jobStatus": {
        "code": "Quoted",
        "name": "Quoted"
      },
      "jobType": {
        "code": "PolicyChange",
        "name": "Policy Change"
      },
      "taxesAndSurcharges": {
        "amount": "94.00",
        "currency": "usd"
      },
      "totalCost": {
        "amount": "1396.00",
        "currency": "usd"
      },
      "totalPremium": {
        "amount": "1302.00",
        "currency": "usd"
      }
    }
  }
}

And finally, you can bind and issue the job.

POST /job/v1/jobs/pc:505/bind-and-issue

<no request body>

RESPONSE:
{
  "data": {
    "attributes": {
      "id": "pc:505",
      "isPreempted": false,
      "jobNumber": "0004408964",
      "jobStatus": {
        "code": "Bound",
        "name": "Bound"
      },
      "jobType": {
        "code": "PolicyChange",
        "name": "Policy Change"
      }
    }
  }
}

Applying changes to a renewal

It is possible for a policy change to preempt a future renewal whose state is either draft or bound. When the policy change is bound, the user interface provides the option of applying the changes in the preempting job to the renewal. This is similar to "handle preemption" functionality, but there are differences:

The copying of information is initiated from the preempting job, not the preempted job.
The copying of information is optional. If you choose to not copy the information, you can still bind the renewal.

To apply changes from a policy change to a renewal through Cloud API, use the following endpoint:

POST job/v1/jobs/{jobId}/apply-changes-to-renewal

You do not need to provide a request body.

Once the changes are applied to the renewal, you need to quote (or requote) the renewal before it can be bound.

Identifying when a renewal exists

When you execute a policy change from the PolicyCenter user interface, there is a button that identifies a renewal exists and that gives you the option to copy changes to the renewal.

When you execute a policy change from Cloud API, you can identify whether there is an existing renewal by checking the links array of the response payload. If there is an apply-changes-to-renewal member, the job's policy has a renewal and you may want to consider applying the policy changes to that renewal.

For example, the following response payload snippet contains an apply-changes-to-renewal member, indicating the changed policy has a renewal.

"links": {
  ..
  "activity-patterns": {
    "href": "/job/v1/jobs/pc:232/activity-patterns",
    "methods": [
      "get"
    ]
  },
  "apply-changes-to-renewal": {
    "href": "/job/v1/jobs/pc:232/apply-changes-to-renewal",
      "methods": [
        "post"
      ]
  },
  "contacts": {
    "href": "/job/v1/jobs/pc:232/contacts",
      "methods": [
        "get"
      ]
  },
  ...