Part of the Phoenix Alerts Management API reference.

An escalation policy is the ordered list of who gets paged, and how long to wait between each page, when an alert isn't acknowledged. Every service needs a team with at least one escalation policy that has at least one step.

Create a policy

POST /v1/escalation-policies

Field	Type	Required	Notes
`policy_name`	string	yes	1–255 characters.
`team_uuid`	string	yes	UUID of the owning team.
`is_default`	boolean	no	Whether this is the team's default policy for severities no other policy covers.
`applicable_severities`	array of integer or null	no	Severities 1–5 this policy applies to. `null` means all.
`repeat_count`	integer	no	Extra passes through the steps after the first (0–9). Defaults to no repeat.
`auto_resolve_after_hours`	integer or null	no	Auto-resolve an alert after this many hours (1–720). `null` means never.
`steps`	array	yes	At least one initial step, created atomically with the policy. See below.

Each entry in steps takes the same fields as adding a step — step_order, wait_seconds, target_type, and target_user_id or target_team_id.

Example request body:

{
    "policy_name": "Default Policy",
    "team_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "is_default": true,
    "steps": [
      {"step_order": 1, "wait_seconds": 300, "target_type": "TEAM_NEXT_ON_CALL", "target_team_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}
    ]
  }

Response (201) — step details aren't embedded; fetch the policy to see them:

{
  "object": "escalation_policy",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Default Policy",
  "team": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Platform Team",
    "key": "platform"
  },
  "is_default": true,
  "applicable_severities": null,
  "repeat_count": 0,
  "auto_resolve_after_hours": null,
  "created_at": "2026-06-12T00:00:00.000Z",
  "updated_at": "2026-06-12T00:00:00.000Z"
}

Get a policy and its steps

GET /v1/escalation-policies/{policy_uuid}

Returns the policy with its ordered steps[], each with the resolved user or team target.

To list all policies without step detail (useful for an overview), use GET /v1/escalation-policies, optionally filtered with ?team_uuid= and/or ?is_default=.

Add a step

POST /v1/escalation-policies/{policy_uuid}/steps

Field	Type	Required	Notes
`step_order`	integer	yes	Position of this step in the sequence. Must be a unique positive number within the policy.
`wait_seconds`	integer	yes	How long to wait before escalating to this step. Must be `0` or at least `60`.
`target_type`	string	yes	`"USER"` pages a specific person. `"TEAM_NEXT_ON_CALL"`, `"TEAM_NEXT_ON_CALL_SECONDARY"`, and `"TEAM_FAN_OUT"` page a team (primary on-call, secondary, or everyone).
`target_user_id`	string or null	required (non-null) when `target_type` is `"USER"`	UUID of the target user. Omit or send `null` for the other target types.
`target_team_id`	string or null	required (non-null) for the `TEAM_*` target types	UUID of the target team. Omit or send `null` when `target_type` is `"USER"`.

Example request body:

{"step_order": 2, "wait_seconds": 300, "target_type": "USER", "target_user_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}

Response (201):

{
  "object": "escalation_step",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "step_order": 2,
  "wait_seconds": 300,
  "target_type": "USER",
  "user": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "display_name": "Alice Example",
    "jira_account_id": "5c8a9b6d4f2e1a0b3c7d8e9f"
  },
  "team": null,
  "created_at": "2026-06-12T00:00:00.000Z",
  "updated_at": "2026-06-12T00:00:00.000Z"
}

Update or delete a step

PATCH /v1/escalation-policies/{policy_uuid}/steps/{step_uuid}
DELETE /v1/escalation-policies/{policy_uuid}/steps/{step_uuid}

PATCH accepts wait_seconds, target_type, target_user_id, target_team_id — all optional, send only what changed. step_order can't be changed after a step is created.

Update or delete a policy

PATCH /v1/escalation-policies/{policy_uuid}
DELETE /v1/escalation-policies/{policy_uuid}

PATCH accepts policy_name, is_default, applicable_severities, repeat_count, auto_resolve_after_hours.

DELETE returns 409 if this is the team's last default policy — every team needs one policy that catches severities nothing else covers.

Escalation policies

Create a policy

Get a policy and its steps

Add a step

Update or delete a step

Update or delete a policy