Example: Policy hold setup

This example walks through the steps for creating a new policy hold and associating rules and geographic zones to that hold.

The policy hold created in this example places holds on Personal Auto submissions with Liability - Bodily Injury and Property Damage coverage whose effective dates are on or after April 10, 2023.

For specific details on endpoints and fields, see the following:

Create policy hold details

The first step in this example is to create a policy hold with the following details:

  • Hold Type: UnderwritingHold
  • Code: uw-hold-1
  • Description: UW hold 1
  • Hold Start Date: April 10, 2023
  • UW Issue Type: UW Policy Hold
  • Long Description: Underwriting policy hold 1

These details from the user interface equate to the following policy-holds Cloud API attributes and values, which we’ll include in the request body:

  • holdType: UWHold
  • policyHoldCode: uw-hold-1
  • description: UW hold 1
  • startDate: 2023-04-10
  • uwIssueType: UWPolicyHold
  • uwIssueLongDescription: Underwriting policy hold 1

Command

POST /admin/v1/policy-holds

Request body

{
  "data": {
    "attributes": {
      "description": "UW hold 1",
      "holdType": {
        "code": "UWHold"
      },
      "policyHoldCode": "uw-hold-1",
      "startDate": "2023-04-10",
      "uwIssueLongDescription": "Underwriting policy hold 1",
      "uwIssueType": {
        "code": "UWPolicyHold"
      }
    }
  }
}

Request response

{
    "data": {
        "attributes": {
...
            "description": "UW hold 1",
            "displayName": "UW hold 1",
            "holdType": {
                "code": "UWHold",
                "name": "Underwriting Hold"
            },
            "id": "pc:101",
            "policyHoldCode": "uw-hold-1",
            "startDate": "2023-04-10",
...
            "uwIssueLongDescription": "Underwriting policy hold 1",
            "uwIssueType": {
                "code": "UWPolicyHold",
                "displayName": "UW Policy Hold"
            }
        },
...
}

Make note of the id returned in the response, in this case pc:101. You’ll need this value to add rules and geographic zones in the next two sections.

Add rules to the policy hold

Now that we’ve created our policy hold, we need to add at least one rule.

Important: If you don’t add at least one rule to the policy hold, the hold will not take effect even if you’ve reached the start date.

In this example, we’re going to add the following rule to our policy hold:

  • Line of Business: Personal Auto
  • Policy Transaction Type: Submission
  • Transaction Date Type: Effective Date

In the Cloud API, the attributes for these values are the following:

  • policyLineType: PersonalAutoLine
  • jobType: Submission
  • jobDateType: Effective

In our endpoint we’ll use the policy hold ID we captured from the response in the previous step.

Command

POST /admin/v1/policy-holds/pc:101/rules

Request body

{
  "data": {
    "attributes": {
      "jobDateType": {
        "code": "Effective"
      },
      "jobType": {
        "code": "Submission"
      },
      "policyLineType": {
        "code": "PersonalAutoLine"
      }
    }
  }
}

Add a policy hold rule coverage

When you add a rule, you can also include a type of coverage by supplying a coverage ID. The types of coverage available will depend on the line of business (policyLineType) you’ve specified. See Policy hold rules for information on retrieving coverage IDs to apply to policy hold rules.

The following updates the rule created in the preceding step to add collision coverage.

Command

PATCH /admin/v1/policy-holds/pc:101/rules/pc:10001

Request body with coveragePattern

{
  "data": {
    "attributes": {
      "coveragePattern": {
        "code": "PACollisionCov"
      }
    }
  }
}

Add geographic zones to the policy hold

After adding one or more rules to your policy hold, you’ll most likely want to add a geographic zone.

Important: If you don’t add a geographic zone, the hold will be applied to all policies that match the associated policy hold rules, regardless of the geographic region the policy is in.

To add a zone, you first need to retrieve the zone ID.

Retrieve the geographic zone ID

Due to the large number of geographic zones available, simply querying for all of them to find the one you want isn’t ideal. Instead, you should use filters to narrow down your search to find a zone you’re looking for.

In this example, we want our policy hold to cover all policies in the state of California. So we’ve added the following filters to our endpoint:

  • Country is the U.S.: country:eq:US
  • Our geographic zone is at the state level: zoneType:eq:state
  • The state is California: code:eq:CA
GET /admin/v1/geographic-zones?filter=country:eq:US&filter=zoneType:eq:state&filter=code:eq:CA

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "code": "CA",
                "country": {
                    "code": "US",
                    "name": "United States"
                },
                "displayName": "CA",
                "id": "US:SbytI2CuZcXKoqyOiaSxI",
                "name": "CA",
                "zoneType": {
                    "code": "state",
                    "name": "State"
                }
            },
...
}

We can now see that the id for the geographic zone covering the state of California is US:SbytI2CuZcXKoqyOiaSxI. Save this value, we’ll use it in the next section.

Add the geographic zone

To add a geographic zone to the policy hold, you’ll need the IDs for the policy hold and the geographic zone. From the previous steps in this example, those values are:

  • Policy hold ID: pc:101
  • Geographic zone ID: US:SbytI2CuZcXKoqyOiaSxI

The geographic zone ID goes in the request body to specify which zone we’re applying to the policy hold:

Request body

{
    "data": {
        "attributes": {
            "geographicZone": {
                "id": " US:SbytI2CuZcXKoqyOiaSxI"
            }
        }
    }
}

This policy hold ID goes in the endpoint command to specify the policy hold to which this zone is being added.

Command

POST /admin/v1/policy-holds/pc:101/geographic-zones

You’ve now created a policy hold that will become active as soon as the start date is reached.

For more information on policy holds, see Policy holds.