Working with policy holds

Querying for policy holds

To retrieve a list of all policy holds, use the following endpoint:

GET /admin/v1/policy-holds

For example:

GET /admin/v1/policy-holds

{
    "data": [
        {
            "attributes": {
                "description": "UW Hold 5",
                "displayName": "UW Hold 5",
                "holdType": {
                    "code": "UWHold",
                    "name": "Underwriting Hold"
                },
                "id": "pc:105",
                "policyHoldCode": "uw-hold-5",
                "startDate": "2023-03-30",
                "uwIssueLongDescription": "UW policy hold 5",
                "uwIssueType": {
                    "code": "UWPolicyHold",
                    "displayName": "UW Policy Hold"
                }
            },
            ...
        },
        {
            "attributes": {
                "description": "UW Hold 4",
                "displayName": "UW Hold 4",
                "endDate": "2023-09-10",
                "holdType": {
                    "code": "UWHold",
                    "name": "Underwriting Hold"
                },
                "id": "pc:104",
                "policyHoldCode": "uw-hold-4",
                "startDate": "2023-03-30",
                "uwIssueLongDescription": "UW policy hold 4",
                "uwIssueType": {
                    "code": "UWPolicyHold",
                    "displayName": "UW Policy Hold"
                }
            },
            ...

To retrieve a single policy hold, include the policy hold ID with the endpoint.

GET /admin/v1/policy-holds/{policyHoldId}

For example, the following query returns information about the policy hold with the id pc:104:

GET /admin/v1/policy-holds/pc:104

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "description": "UW Hold 4",
                "displayName": "UW Hold 4",
                "endDate": "2023-09-10",
                "holdType": {
                    "code": "UWHold",
                    "name": "Underwriting Hold"
                },
                "id": "pc:104",
                "policyHoldCode": "uw-hold-4",
                "startDate": "2023-03-30",
                "uwIssueLongDescription": "UW policy hold 4",
                "uwIssueType": {
                    "code": "UWPolicyHold",
                    "displayName": "UW Policy Hold"
                }
            },
            ...

Creating policy holds

To create a new policy hold, use the following method:

POST /admin/v1/policy-holds

Provide the following fields in the request:


Property	Description	Required?
`description`	A description of the policy hold.	Yes
`holdType`	The type of hold. Values are from the `UWIssueCheckingSet` typelist with the `PolicyHoldsTypeFilter` applied. By default, available values are: `UWHold` `RegulatoryHold`	Yes
`policyHoldCode`	A unique code for this policy hold. This value cannot contain spaces.	Yes
`startDate`	The start date of the policy hold. Must be in the format YYYY-MM-DD.	Yes
`uwIssueLongDescription`	A description of the underwriting issue.	Yes
`endDate`	The end date of the policy hold. Must be in the format YYYY-MM-DD.	No
`uwIssueType`	The underwriting issue type. With the base configuration, the following are required: If `holdType` is `UWHold`, this value must be `UWPolicyHold` If `holdType` is `RegulatoryHold`, this value must be `RegulatoryPolicyHold`	Yes

The following examples show how to create new underwriting and regulatory policy holds.

Creating an underwriting policy hold

Command

POST /admin/v1/policy-holds

Request body

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

Creating a regulatory policy hold

Creating a regulatory policy hold is similar to creating an underwriting hold. Note the values in the holdType and uwIssueType fields.

Request body

{
  "data": {
    "attributes": {
      "description": "Reg Hold 1",
      "holdType": {
        "code": "RegulatoryHold"
      },
      "policyHoldCode": "reg-hold-1",
      "startDate": "2023-03-30",
      "uwIssueLongDescription": "Regulatory policy hold 1",
      "uwIssueType": {
        "code": "RegulatoryPolicyHold"
      }
    }
  }
}

Modifying policy holds

Use the following endpoint to modify a policy hold:

PATCH /admin/v1/policy-holds/{policyHoldId}

The following fields can be updated with the PATCH endpoint:

description
startDate
endDate
uwIssueLongDescription

Command

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

Request body

{
  "data": {
    "attributes": {
      "endDate": "2023-05-30"
    }
  }
}

Deleting policy holds

You can delete a policy hold with the DELETE endpoint.

DELETE /admin/v1/policy-holds/{policyHoldId}

For example:

DELETE /admin/v1/policy-holds/pc:101

Policy hold components

Policy holds include additional components that further define the hold.

Policy hold rules: Defines the types of policies to which the hold applies.
Important: If you create a policy hold without creating any rules, the policy hold will not take effect even if you’ve reached the start date.
See Adding policy hold rules for more information.
Note: If you create a policy hold without creating any rules for that hold, in addition to the policy hold not taking effect, the details of that policy hold will not be updateable in the user interface until policy hold rules are added, either through the UI or the Cloud API.
Policy hold geographic zones: Defines the geographic regions to which the hold applies. If you create a policy hold without defining at least one geographic zone, the policy hold will apply to all geographic zones.

See Policy hold geographic zones for more information.