Pre-renewal directions

A pre-renewal direction is a special note attached to a policy that provides information on how to execute the policy's next renewal job. There are three broad types of pre-renewal directions:

Non-renew - The policy will not be renewed at the request of the insurer.
Not taken - The policy will not be renewed at the request of the insured.
Refer to an individual - The policy will be reviewed by the insurer to determine if it can be renewed.

The full set of possible values is defined in the PreRenewalDirection typelist.

When you create a pre-renewal direction note, you must specify:

The direction
The user that the renewal will be assigned to
A security level for the note
Text for the note

The topic of the note is set to "Pre-renewal direction".

At any given time, a policy can have only one active pre-renewal direction. A new pre-renewal direction supersedes any previous directions.

In Cloud API, pre-renewal directions can be managed from endpoints in the Policy API.

Retrieving pre-renewal directions

To determine a policy's current pre-renewal direction, execute a GET for the policy.

The pre-renewal direction is stored in the preRenewalDirection field.
The user assigned by the pre-renewal is stored in the preRenewalOwner field.
If the GET includes the policy's notes, pre-renewal notes have a topic code of prerenewal.

The following request body is a snippet of the response for a GET of policy pc:44 with its associated notes. The snippet includes the information related to pre-renewal directions.

GET /policy/v1/policies/pc:44?include=notes

{
    "data": {
        "attributes": {
            "id": "pc:44",
            "preRenewalDirection": "underwriter",
            "preRenewalOwner": {
                "assigneeId": "userId=pc:3630,groupId=pc:318",
                "groupId": "pc:318",
                "name": "Alice Applegate (Los Angeles Branch UW)",
                "userId": "pc:3630"
            }
        },
    "included": {
        "Note": [
            {
                "attributes": {
                    "bodySummary": "Refer to underwriter to investigate excessive number of claims",
                    "confidential": true,
                    "securityType": {
                        "code": "internalonly",
                        "name": "Internal Only"
                    },
                    "topic": {
                        "code": "prerenewal",
                        "name": "Pre-renewal direction"
                    }
                },
...

Setting pre-renewal directions

Use the following endpoint to set a policy's pre-renewal direction:

POST /policy/v1/policies/{policyId}/set-prerenewal-direction

Minimum creation criteria

At a minimum, the request body must provide the following:

body - The body of the pre-renewal note
direction - The pre-renewal direction (A value from the PreRenewalDirection typelist)
securityType - The security type of the note (A value from the NoteSecurityType typelist)

Additional fields may be required depending on the selected pre-renewal direction. The following table summarizes the required fields.


Pre-renewal direction	`direction` value	Additional required fields
Non-renew	`nonrenew`	`nonRenewReason` (A value from the `NonRenewalCode` typelist)
Not taken	`nottaken`	(none)
Refer to underwriter	`underwriter`	`assignTo`
Refer to underwriter assistant	`assistant`	`assignTo`
Refer to Customer Service Representative	`custrep`	`assignTo`
Non-renew and refer to underwriter	`nonrenewrefer`	`assignTo,` `nonRenewReason` (A value from the `NonRenewalCode` typelist)

Non-renew example

For a non-renew direction, you must specify the non-renewal reason. This must be a typecode from the NonRenewalCode typelist.

POST /policy/v1/policies/pc:44/set-prerenewal-direction

{
  "data": {
    "attributes": {
      "body": "Excessive claims",
      "direction": {
        "code": "nonrenew"
      },
      "nonRenewReason": {
        "code": "loss"
      },
      "securityType": {
        "code": "internalonly"
      }
    }
  }
}

Not taken example

For a non-renew direction, aside from body, direction, and securityType, no additional fields are required.

POST /policy/v1/policies/pc:44/set-prerenewal-direction

{
  "data": {
    "attributes": {
      "body": "Insured is selling their car",
      "direction": {
        "code": "nottaken"
      },
      "securityType": {
        "code": "internalonly"
      }
    }
  }
}

Refer to review example

For a "refer to underwriter" direction, you must specify the underwriter and group to assign the renewal to in the assignTo field.

POST /policy/v1/policies/pc:44/set-prerenewal-direction

{
  "data": {
    "attributes": {
      "assignTo": {
        "userId": "pc:3630",
        "groupId": "pc:318"
      },
      "body": "Refer to underwriter to investigate excessive number of claims",",
      "direction": {
        "code": "underwriter"
      },
      "securityType": {
        "code": "internalonly"
      }
    }
  }
}

Clearing pre-renewal directions

You can clear a policy's pre-renewal direction. This removes any active pre-renewal direction without setting a new one. The puts the policy in the same state it would be in if it had never had any pre-renewal direction.

Use the following endpoint to clear a policy's pre-renewal direction:

POST /policy/v1/policies/{policyId}/clear-prerenewal-direction

The request does not require a body.