---
title: "Create an escalation policy"
method: POST
path: "/api-public/v1/policies"
tags: ["Escalation Policies"]
---

# Create an escalation policy

`POST /api-public/v1/policies`

Takes an entire escalation policy and creates it.

For the purpose of using this API, escalation policies are treated as immutable. The policy will not be able to be updated or modified in any way via this API once created. It will only be able to be deleted. However, The escalation policies are accessable in the UI once created and can be updated from there.

This API may be called a maximum of 2 times per second.

## Headers

- `X-VO-Api-Id` string, required
- `X-VO-Api-Key` string, required

## Request body

- CreateEscalationPolicy
  - `name` string, required — The name of the escalation policy
  - `teamSlug` string, required — The unique identifier for the team to create the policy under. The team slug is in the format `team-[\w\d]{16}`
  - `ignoreCustomPagingPolicies` boolean — True if this policy ignores a user's custom paging policy; this will page the on-call user via their Primary Paging Policy and ignore any custom paging policies they have set. We recommend enabling this if the escalation policy handles high severity incidents.
  - `steps` CreateEscalationPolicyGroup[], required — A list of groupings of entries. Each group is a "step" in the escalation policy.
    - `timeout` integer, required — The duration in minutes to wait until executing this step since the last step was executed. This value may be 0. This implies that this policy step should immediately execute.
    - `entries` CreateEscalationPolicyEntry[], required — A list of entries that this escalation policy group encapsulates
      - `executionType` 'rotation_group' | 'rotation_group_next' | 'rotation_group_previous' | 'webhook' | 'user' | 'email' | 'policy_routing', required — This is an entry containing only ONE of the available execution types. If the executionType provided is one of [rotation_group, rotation_group_next, rotation_group_previous] then you must (and only) provide the rotation group object in the body. If the executionType provided is [webhook] then you must (and only) provide the webhook object in the body. If the executionType provided is [user] then you must (and only) provide the user object in the body. If the executionType provided is [email] then you must (and only) provide the email object in the body. If the executionType provided is [policy_routing] then you must (and only) provide the target policy object in the body.
      - `rotationGroup` object
        - `slug` string — The unique identifier for the rotation group that will be executed when this escalation policy step activates. The slug is in the format `rtg-[\w\d]{16}` The rotation group must already exist and can currently only be created in the web application. In the Rotations section, the `/api-public/v1/teams/{team}/rotations` endpoint will return a list of the available rotations. The rotation must exist for the same team used in this escalation policy.
      - `webhook` object
        - `slug` string — The unique identifier for the webhook that will be executed when this escalation policy step activates The slug is in the format `wh-[\w\d]{16}` The webhook must already exist and can currently only be created in the web application. In the Webhooks section, the `/api-public/v1/webhooks` endpoint will return a list of your organization's webhooks.
      - `user` object
        - `username` string — The unique identifier for the user. This user will be notified when the escalation policy step activates.
      - `email` object
        - `address` string — The email address that will be notified when this escalation policy step activates. Any email adress may be provided here.
      - `targetPolicy` object — The escalation policy to target when executing
        - `policySlug` string — The unique slug of another escalation policy that will be executed when this escalation policy step activates. The policy slug is simply a reference to another escalation policy that already currently exists. The slug is in the format `pol-[\w\d]{16}`

## Response `200`

The newly created escalation policy

- EscalationPolicy
  - `name` string, required — The name of this escalation policy
  - `slug` string, required — A unique identifier for this escalation polcy This slug is in the format `pol-[\w\d]{16}`
  - `ignoreCustomPagingPolicies` boolean, required — True if this policy ignores a user's custom paging policy; this will page the on-call user via their Primary Paging Policy and ignore any custom paging policies they have set. We recommend enabling this if the escalation policy handles high severity incidents.
  - `steps` EscalationPolicyGroup[], required — A list of groupings of entries. Each group is a "step" in the escalation policy. Each "step" contains a group of entries to be executed.
    - `timeout` integer, required — The duration in minutes to wait until executing this step since the last step was executed. This value may be 0. This implies that this policy step should immediately execute.
    - `entries` EscalationPolicyEntry[], required — A list of entries that this escalation policy group encapsulates. These entries will all be executed once the escalation policy reaches this step.
      - `executionType` 'rotation_group' | 'rotation_group_next' | 'rotation_group_previous' | 'webhook' | 'user' | 'email' | 'policy_routing', required — The type of entry
      - `rotationGroup` object
        - `slug` string — The unique identifier for the rotation group that will be executed when this escalation policy step activates. The slug is in the format `rtg-[\w\d]{16}` To get more information about this rotation group, you can use the endpoints available in the Rotation Groups section
        - `label` string — The name of the rotation group
      - `webhook` object
        - `slug` string — The unique identifier for the webhook that will be executed when this escalation policy step activates The slug is in the format `wh-[\w\d]{16}` To get more information about this webhook, you can use the endpoints available in the Webhooks section
        - `label` string — The name of the webhook
      - `user` object
        - `username` string — The unique identifier for the user. This user will be notified when the escalation policy step activates.
        - `firstName` string — The user's first name
        - `lastName` string — The user's last name
      - `email` object
        - `address` string — The email address that will be notified when this escalation policy step activates.
      - `targetPolicy` object — The escalation policy to target when executing
        - `policySlug` string — The unique slug of another escalation policy that will be executed when this escalation policy step activates. The policy slug is in the format `pol-[\w\d]{16}`

## Other responses

- `400` — Problem with the request arguments. The response payload may include an error message.
- `401` — Authentication parameters missing
- `403` — Authentication failed or rate-limit reached
- `404` — Path not found
- `500` — Internal Server Error

---

[API](https://skmtc.net/victorops/apis/victorops-api.md) · [All operations](https://skmtc.net/victorops/apis/victorops-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/victorops/victorops-api/revisions/7a7391256058/schema)