Catastrophe perils

A catastrophe peril refers to a specific cause of loss or damage caused by a catastrophe, covered by an insurance policy. A peril is a combination of a Loss Type, such as property, and a Loss Cause, such as wind.

For a more detailed discussion of the business functionality of catastrophe perils, refer to Application Guide.

Querying for catastrophe perils

Use the following endpoints to query for catastrophe perils:

  • GET /admin/v1/catastrophes/{catastropheId}/perils
  • GET /admin/v1/catastrophes/{catastropheId}/perils/{catastrophePerilId}

For example, the following request retrieves all the perils associated with a hurricane with the id, xc:SAksedABpXZrTAczt7MRU.

Command

GET /admin/v1/catastrophes/xc:SAksedABpXZrTAczt7MRU/perils
Response
{
    "count": 2,
    "data": [
        {
            "attributes": {
                "id": "xc:S2JJ9HUSUtrQPgb9HLebR",
                "lossCause": {
                    "code": "FallingObject",
                    "name": "Falling or moving object"
                },
                "lossType": {
                    "code": "AUTO",
                    "name": "Auto"
                }
            }
        },
        {
            "attributes": {
                "id": "xc:SSZTt2C0U7t8JGtrgZQFy",
                "lossCause": {
                    "code": "waterdamage",
                    "name": "Water damage
                },
                "lossType": {
                    "code": "PR",
                    "name": "Property"
                }
            }
        }
    ]
}

You can also use a peril's id from the response to retrieve information about only that peril. For example, the following request retrieves information about the water damage peril by its id, xc:SSZTt2C0U7t8JGtrgZQFy.

Command

GET /admin/v1/catastrophes/xc:SAksedABpXZrTAczt7MRU/perils/xc:SSZTt2C0U7t8JGtrgZQFy

Response


{
    "data": {
        "attributes": {
            "id": "xc:SSZTt2C0U7t8JGtrgZQFy",
            "lossCause": {
                "code": "waterdamage",
                "name": "Water damage"
            },
            "lossType": {
                "code": "PR",
                "name": "Property"
            }
        }
    }
}

Creating catastrophe perils

Use the following endpoint to create a catastrophe peril:

  • POST /admin/v1/catastrophes/{catastropheId}/perils

A catastrophe peril consists of a Loss Cause, such as wind, and a Loss Type, such as property damage. To create a catastrophe peril, you must specify the code associated with the Loss Cause and the code associated with the Loss Type.

Note: The code within lossCause and lossType is a string that represents a TypeKey from a TypeList of available codes, so you can only use a value enumerated in that list. To learn how to find more information about which typekeys are available for the lossCause and lossType typelists, refer to The /business-line-metadata endpoint.

For example, the following request creates a peril associated with xc:SAw_jS2RygUX4uS9idwqV, consisting of wind damage to someone's property.

Command
POST /admin/v1/catastrophes/xc:SAw_jS2RygUX4uS9idwqV/perils
Request

{
    "data": {
        "attributes": {
            "lossCause": {
                "code": "wind"
            },
            "lossType": {
                "code": "pr"
            }
        }
    }
}

The API returns the created peril, along with the display names associated with the codes provided in the request.

Response


{
    "data": {
        "attributes": {
            "id": "xc:St4ZZkgWl3PoqwgloIdy8",
            "lossCause": {
                "code": "wind",
                "name": "Wind"
            },
            "lossType": {
                "code": "PR",
                "name": "Property"
            }
        }
    }
}

Modifying catastrophe perils

Use the following endpoint to modify a catastrophe peril:

  • PATCH /admin/v1/catastrophes/{catastropheId}/perils/{catastrophePerilId}

You can modify the following fields:

  • lossCause/code
  • lossType/code
Note: The code within lossCause and lossType is a string that represents a TypeKey from a TypeList of available codes, so you can only use a value enumerated in that list. To learn how to find more information about which typekeys are available for the lossCause and lossType typelists, refer to The /business-line-metadata endpoint.

For example, the following request changes the peril from wind damage to mold damage for peril xc:St4ZZkgWl3PoqwgloIdy8.

Command

PATCH /admin/v1/catastrophes/xc:SAw_jS2RygUX4uS9idwqV/perils/xc:St4ZZkgWl3PoqwgloIdy8

Request


{
    "data": {
        "attributes": {
            "lossCause": {
                "code": "mold"
            }
        }
    }
}

The API responds with the updated peril.

Response


{
    "data": {
        "attributes": {
            "id": "xc:St4ZZkgWl3PoqwgloIdy8",
            "lossCause": {
                "code": "mold",
                "name": "Mold"
            },
            "lossType": {
                "code": "PR",
                "name": "Property"
            }
        }
    }
}

Deleting catastrophe perils

Use the following endpoint to delete a peril from its associated catastrophe:

  • DELETE /admin/v1/catastrophes/{catastropheId}/perils/{catastrophePerilId}

For example, the following request deletes the catastrophe zone, xc:SUHNlpXQePg82I-hWKa3v.

Command

DELETE /admin/v1/catastrophes/xc:SAw_jS2RygUX4uS9idwqV/perils/xc:S2JJ9HUSUtrQPgb9HLebR

When the API has successfully deleted the peril from its associated catastrophe, it will return an empty body in response.