Policy hold geographic zones

Policy hold geographic zones allow you to limit the policy hold to one or more geographic regions (referred to as Hold Regions in the user interface). If you don’t define at least one geographic zone, the hold will apply to all policies that match the specified rules.

The following endpoints are available for policy hold geographic zones:

  • GET /admin/v1/policy-holds/{policyHoldId}/geographic-zones
  • GET /admin/v1/policy-holds/{policyHoldId}/geographic-zones/{policyHoldZoneId}
  • POST /admin/v1/policy-holds/{policyHoldId}/geographic-zones
  • DELETE /admin/v1/policy-holds/{policyHoldId}/geographic-zones/{policyHoldZoneId}

Querying for policy hold geographic zones

To retrieve all geographic zones associated with a policy hold, use the GET endpoint.

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

For example:

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

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "code": "OR:Wasco",
                "country": {
                    "code": "US",
                    "name": "United States"
                },
                "id": "pc:12001",
                "zoneType": {
                    "code": "county",
                    "name": "County"
                }
            },
            ...
        },
        {
            "attributes": {
                "code": "CA",
                "country": {
                    "code": "US",
                    "name": "United States"
                },
                "id": "pc:12002",
                "zoneType": {
                    "code": "state",
                    "name": "State"
                }
            },
            ...

}

To retrieve only a single geographic zone, include the zone ID with the GET endpoint.

GET /admin/v1/policy-holds/{policyHoldId}/geographic-zones/{policyHoldZoneId}

For example:

GET /admin/v1/policy-holds/pc:101/geographic-zones/pc:12001

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "code": "OR:Wasco",
                "country": {
                    "code": "US",
                    "name": "United States"
                },
                "id": "pc:12001",
                "zoneType": {
                    "code": "county",
                    "name": "County"
                }
            },
            ...
}

Retrieving geographic zone IDs

Before you can add a geographic zone to a policy hold, you need to find the ID for the zone you want to add. You can retrieve geographic zones using the following endpoint:

/admin/v1/geographic-zones

It's best practice to always include filters in your command when searching for a geographic zone due to the large number of zones available. For example, if you want to retrieve the ID for the U.S. state of California, use the following command:

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"
                }
            },
...
}

Adding policy hold geographic zones

To add a geographic zone to a policy hold, use the following command:

POST /admin/v1/policy-holds/{policyHoldId}/geographic-zones

The only field you can populate when adding a geographic zone to a policy hold is the id. Here’s an example:

Command

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

Request body

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

Modifying policy hold geographic zones

You cannot modify a geographic zone on a policy hold. To modify the list of geographic zones applied to your policy hold, you need to delete existing zones and add new ones.

Deleting policy hold geographic zones

To remove a geographic zone from a policy hold, use the following command:

DELETE /admin/v1/policy-holds/{policyHoldId}/geographic-zones/{policyHoldZoneId}

For example:

DELETE /admin/v1/policy-holds/pc:101/geographic-zones/pc:12001