Part of the Phoenix Alerts Management API reference.

A user is a person Phoenix Alerts can page. Each user has one or more contact methods (phone or email) that must be verified before they're used for paging.

Create a user

POST /v1/users

Field	Type	Required	Notes
`jira_account_id`	string	yes	1–256 characters. Your identifier for this person.
`display_name`	string	yes	1–256 characters.
`email`	string	yes	Used for notifications and seeded as the user's first contact method.
`role`	string	no	`"OWNER"` or `"MEMBER"`. Defaults to `"MEMBER"`.
`timezone`	string or null	no	IANA timezone, e.g. `America/New_York`.

Example request body:

{"jira_account_id": "5c8a9b6d4f2e1a0b3c7d8e9f", "display_name": "Alice Example", "email": "[email protected]"}

Response (201):

{
  "object": "user",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "jira_account_id": "5c8a9b6d4f2e1a0b3c7d8e9f",
  "display_name": "Alice Example",
  "email": "[email protected]",
  "timezone": "America/New_York",
  "role": "MEMBER",
  "status": "ACTIVE",
  "created_at": "2026-06-12T00:00:00.000Z",
  "updated_at": "2026-06-12T00:00:00.000Z",
  "teams": [],
  "reactivated": false
}

If a user with that jira_account_id already exists and is inactive, this reactivates them and returns 200 with "reactivated": true instead of 201. If they're already active, it returns 409.

List users

GET /v1/users

Useful query params: jira_account_id (look up one user), status (ACTIVE, INACTIVE, or ALL; defaults to ACTIVE), expand (contact_methods, teams, comma-separated).

Add a contact method

POST /v1/users/{user_uuid}/contact-methods

Field	Type	Required	Notes
`method_type`	string	yes	`"PHONE"` or `"EMAIL"`.
`value`	string	yes	Phone number in E.164 format, or an email address.
`label`	string or null	no	Human-readable label, e.g. "Work phone".
`is_primary`	boolean	no	Whether this is the primary contact of its type.
`is_enabled`	boolean	no	Whether this contact is used for paging. Defaults to `true`.

Example request body:

{"method_type": "PHONE", "value": "+14155550100", "label": "Work phone", "is_primary": true}

Response (201):

{
  "object": "contact_method",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "method_type": "PHONE",
  "value": "+14155550100",
  "label": "Work phone",
  "is_primary": true,
  "verification_status": "UNVERIFIED",
  "is_enabled": true,
  "created_at": "2026-06-12T00:00:00.000Z",
  "updated_at": "2026-06-12T00:00:00.000Z"
}

A new contact method starts UNVERIFIED. It won't be paged until it's verified.

Verify a contact method

Start verification — this sends a code to the contact method:

POST /v1/users/{user_uuid}/contact-methods/{contact_uuid}/verify/start

Example request body:

{"channel": "sms"}

channel is "sms", "voice", or "email" and defaults to "sms". Response (202):

{
  "verification_started_at": "2026-06-12T00:00:00.000Z",
  "expires_at": "2026-06-12T00:10:00.000Z",
  "channel": "sms",
  "rate_limit": {
    "max_sends_per_window": 5,
    "min_seconds_between_sends": 60,
    "sends_remaining": 4,
    "next_allowed_at": "2026-06-12T00:01:00.000Z"
  }
}

Then submit the code the person received:

POST /v1/users/{user_uuid}/contact-methods/{contact_uuid}/verify/check

Example request body:

{"code": "482913"}

Response (200) on success:

{
  "verification_status": "VERIFIED",
  "verified_at": "2026-06-12T00:05:00.000Z"
}

A wrong code returns 400. An expired or already-used-up verification attempt returns 410 — start again.

Update or delete a contact method

PATCH /v1/users/{user_uuid}/contact-methods/{contact_uuid}
DELETE /v1/users/{user_uuid}/contact-methods/{contact_uuid}

PATCH accepts value, label, is_primary, is_enabled. Changing value resets verification_status back to UNVERIFIED.

Both return 409 if the change would leave an on-call person with no way to reach them (for example, deleting their last verified contact method while they're a direct escalation target).

Users and contact methods

Create a user

List users

Add a contact method

Verify a contact method

Update or delete a contact method