# Create escalation policy

Returns either a newly created escalation policy, or validation errors.

[endpoint]
base_url = "https://uptime.betterstack.com"
path = "/api/v3/policies"
method = "POST"

[[body_param]]
name = "team_name"
description = "Required if using [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) to specify the team which should own the resource"
required = false
type = "string"

[[body_param]]
name = "name"
description = "The name of this Policy."
required = true
type = "string"

[[body_param]]
name = "repeat_count"
description = "How long in seconds to wait before each repetition."
required = false
type = "integer"

[[body_param]]
name = "repeat_delay"
description = "Incident token that can be used for manually reporting incidents."
required = false
type = "integer"

[[body_param]]
name = "steps"
description = "An array of escalation policy steps. See the [list of escalation policy API parameters](https://betterstack.com/docs/uptime/api/escalation-policies-api-response-params/) for details."
required = false
type = "Array of PolicyStep"


[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content_Type"
description = "application/json"
required = false
type = "string"
[/endpoint]


[responses]
[[response]]
status = 201
description = '''Returns newly created escalation policy'''
body = '''{
  "data": {
    "id": "456789",
    "type": "policy",
    "attributes": {
      "name": "Standard Escalation Policy",
      "repeat_count": 3,
      "repeat_delay": 1800,
      "incident_token": "AND63ccyT18oKcSFnbJfxlFi1",
      "policy_group_id": null,
      "team_name": "Test Team",
      "steps": [
        {
          "type": "escalation",
          "urgency_id": 123456,
          "step_members": [
            {
              "type": "current_on_call"
            }
          ],
          "wait_before": 0
        },
        {
          "type": "escalation",
          "urgency_id": 123456,
          "step_members": [
            {
              "type": "entire_team"
            }
          ],
          "wait_before": 600
        }
      ]
    }
  }
}'''

[/responses]

#### Example cURL 

[code-tabs]
```shell
[label Escalation policy]
curl -X "POST" "https://uptime.betterstack.com/api/v3/policies/" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
  "name": "Standard Escalation Policy",
  "repeat_count": 3,
  "repeat_delay": 1800,
  "steps": [
    {
      "type": "escalation",
      "wait_before": 0,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "current_on_call" }
      ]
    },
    {
      "type": "escalation",
      "wait_before": 600,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "entire_team" }
      ]
    }
  ]
}'
```
```shell
[label Branching]
curl -X "POST" "https://uptime.betterstack.com/api/v3/policies/" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
  "name": "Business Hours Branching",
  "steps": [
    {
      "type": "time_branching",
      "wait_before": 0,
      "timezone": "America/New_York",
      "days": ["mon", "tue", "wed", "thu", "fri"],
      "time_from": "09:00",
      "time_to": "17:00",
      "policy_metadata_key": "business_hours_policy"
    },
    {
      "type": "metadata_branching",
      "wait_before": 0
      "metadata_key": "urgency",
      "metadata_values": [
        {
          "type": "String",
          "value": "low"
        }
      ],
      "action_type": "do_not_escalate",
    },
    {
      "type": "escalation",
      "wait_before": 300,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "current_on_call" },
        { "type": "all_slack_integrations" }
      ]
    }
  ]
}'
```
```shell
[label Instructions]
curl -X "POST" "https://uptime.betterstack.com/api/v3/policies/" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
  "name": "Policy with Instructions and Todo list",
  "steps": [
    {
      "type": "instructions",
      "wait_before": 0,
      "instructions_comment": "IMMEDIATE ACTIONS:\n1. Check system status at status.example.com\n2. Verify in monitoring dashboard\n3. Check #incidents Slack channel\n4. If database-related, run: kubectl get pods -n production",
      "instructions_reminder_enabled": false
    },
    {
      "type": "escalation",
      "wait_before": 0,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "current_on_call" },
        { "type": "all_slack_integrations" }
      ]
    },
    {
      "type": "instructions",
      "wait_before": 900,
      "instructions_comment": "ESCALATION REQUIRED:\n- [] Page backup on-call\n- [] Start incident bridge: dial 1-800-XXX-XXXX, code: 12345#\n- [] Update status page\n- [] Notify stakeholders via #incident-comms",
      "instructions_reminder_enabled": true,
      "instructions_reminder_interval_hours": 2
    },
    {
      "type": "escalation",
      "wait_before": 300,
      "urgency_id": "'$SEVERITY_ID'",
      "step_members": [
        { "type": "entire_team" },
        { "type": "user", "email": "manager@example.com" }
      ]
    }
  ]
}'
```
[/code-tabs]

[info]
#### Looking for the details of a specific parameter?
Explore [the list of all escalation policies API parameters](https://betterstack.com/docs/uptime/api/escalation-policies-api-response-params/)
[/info]