Renewals

A renewal is a policy transaction that creates a new term for an existing policy at the end of the latest term. This topic covers how to manage renewals through Cloud API.

For details on the business functionality of renewals, see the Application Guide.

Overview of policy transaction management

Work with policy transactions typically involves endpoints from two different APIs:

  • The Policy API, which has endpoints to:
    • Initiate all types of policy transactions except for submissions
  • The Job API, which has endpoints to:
    • Initiate submissions
    • Modify the contents of a policy (such as its coverables, coverages, and policy contacts)
    • Quote jobs
    • Bind and issue jobs, or withdraw jobs
    • Work with objects owned by jobs, such as activities and underwriting issues

Conceptually, a policy transaction is completed in four steps:

  1. Initiate the policy transaction.
    • This creates a new Job element whose status is "Draft".
  2. Modify the job as needed.
    • The status remains "Draft".
  3. Quote the job.
    1. The rating engine or rating service generates a quote for the job.
    2. The status advances to "Quoted".
    3. The job can be modified at this point. But if it is modified, the policy transaction falls back to the previous step. In other words, the status reverts to "Draft" and the job must be later requoted.
  4. Complete the job.
    1. This can be done by binding the job or by withdrawing or canceling the job.
    2. The status advances to "Bound", "Declined", or "Withdrawn", depending on the outcome and job type.

Initiating a renewal

Renewals are initiated from the policy itself. Use the following endpoint to create a renewal for a given policy:

  • POST /policy/v1/policies/{policyId}/renew

The request requires an empty body (a body with no specified attributes).

For example, the following initiates a renewal for policy pc:44.

POST /policy/v1/policies/pc:44/renew

{
  "data": {
    "attributes": {
    }
  }
}

This call creates a new job instance whose job type is "Renewal".

Actions PolicyCenter takes when a renewal is initiated

PolicyCenter manages renewals using workflows. A renewal workflow is a set of events to execute to process a renewal. PolicyCenter has multiple types of renewal workflows to manage the different stages a renewal could be in and the different outcomes as defined by any pre-renewal direction.

For some policies (such as policies with no material changes, pre-renewal direction, or underwriting issues), no further action is required. PolicyCenter automatically binds the policy at the appropriate time.

For other policies, additional actions may be required. For example, the renewal may require material changes. In this case, the renewal must be converted to a draft state, the changes must be made, and the renewal must be requoted. Also, the renewal may have underwriting issues that block its progress. For these policies, it may be necessary to modify, quote, and/or complete the renewal through the user interface or through Cloud API.

Pre-renewal directions

A policy can have a pre-renewal direction. A pre-renewal direction is a special note attached to a policy that provides information on how to execute the policy's renewal job when the renewal job is initiated automatically.

For more information on how to set and clear pre-renewal directions, see Pre-renewal directions.

Modifying the renewal

Some policies may require modification at renewal time, such as policies for which coverages need to be added or removed.

Moving a quoted renewal to a draft state

Some renewals, such as renewals with no pre-renewal direction, are automatically quoted. Before the job can be changed, the renewal's job must be set to "Draft". To do this, use the POST /job/v1/jobs/{jobId}/make-draft endpoint, which reverts the job's status to "Draft".

For example, the following request moves the quoted job pc:4040 back to a draft state:

POST /job/v1/jobs/pc:4040/make-draft

<no request body>

Modifying the renewal

The specific information added, removed, or changed in a draft renewal varies based on the lines of business associated with the job's product. This information is specified using LOB-specific endpoints. For an overview of these endpoints, see Overview of modifying jobs.

The following is an example of adding a "limited liability for Mexico" line-level liability coverage to job pc:4040, which was moved to a draft state in the previous example.

PATCH /job/v1/jobs/pc:4040/lines/PersonalAutoLine/coverages

{
  "data": {
    "attributes": {
        "pattern": {
            "id": "PALimitedMexicoCov"
        }
    }
  }
}

Risk analysis information

PolicyCenter gathers information that an underwriter can use to process a job, such as a renewal. In the user interface, this information is referred to as Risk Analysis information. This includes the following:

  • Loss history - This is a list of prior losses that have been incurred by the insured. This information can be edited during a submission or outside of the context of a job. For more information, see Loss history.
  • Prior policies - This is a list of policies that the insured has had prior to this policy. They could be policies with the insurer or with other insurers. This information can be edited during a submission or outside of the context of a job. For more information, see Prior policies.

Changes to a policy after a renewal is created

It is possible to start a policy change on a policy that already has a pending renewal. When the policy change is bound, there is no requirement for those changes to be copied to the renewal. However, you can opt to copy the changes to the renewal, either from the user interface or from Cloud API. For more information on applying changes to a renewal, see Applying changes to a renewal.

Quoting the renewal

To quote a job (such as a renewal), use the following endpoint:

  • POST /job/v1/jobs/{jobId}/quote

The request object does not require a request body.

For example, the following request quotes job pc:4040:
POST /job/v1/jobs/pc:4040/quote

<no request body>

If the job lacks all the information required for rating, the call fails. For example, for the base configuration Personal Auto product, a submission will fail if you specify a covered vehicle, but you do not specify a driver for the vehicle.

If the call succeeds, a quote is generated for the job. The status of the job is advanced to "Quoted".

Additional quoting capabilities

Cloud API has access to additional PolicyCenter quoting functionality. This includes:

  • Retrieving payment information
  • Generating multiple "side-by-side" quotes for a single job
  • Overriding rating

For additional information, see Quoting.

Completing the renewal

The following table summarizes the different endpoints that can be used to complete a renewal.

Outcome Endpoint Action taken
Bind the renewal now /job/v1/jobs/{jobId}/bind-and-issue Issue the renewal immediately
Complete the job at a later date as a renewal /job/v1/jobs/{jobId}/pending-renew Change the policy period's status to renewing and start the PendingRenewalWF workflow
Complete the job at a later date as a non-renewal /job/v1/jobs/{jobId}/pending-non-renew Change the policy period's status to nonrenewing and start the PendingNonRenewalWF workflow
Complete the job at a later date as a not taken /job/v1/jobs/{jobId}/pending-not-take Change the policy period's status to nottaking and start the PendingNotTakenWF workflow
Withdraw the renewal /job/v1/jobs/{jobId}/withdraw Withdraw the renewal

Example of binding the renewal immediately

Use the following endpoint to bind a renewal immediately:

  • POST /job/v1/jobs/{jobId}/bind-and-issue

The request object does not require a request body.

For example, the following request binds and issues job pc:333.

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

<no request body>

The renewal's status is changed to "Bound".

Example of withdrawing a renewal

Use the following endpoint to withdraw the renewal:

  • POST /job/v1/jobs/{jobId}/withdraw

The request object does not require a body.

For example, the following request withdraws job pc:333.

POST /job/v1/jobs/pc:333/withdraw

<no request body>

The renewal's status is changed to "Withdrawn".