Add participants to an incident

An incident’s participants are the people working it. Each has a role, so everyone can see who leads, who is helping and who is handling communication. You can add a person, whoever is on call now in a schedule, or the first level of an escalation policy, and page them as you add them.

Participants are users already in your account, so adding one never uses or bills a seat.

Roles

Role	Use for
`lead`	The person running the response. An incident has at most one.
`responder`	Anyone working the fix. The default.
`comms`	The person handling updates and communication.

The first person to acknowledge an incident that has no lead becomes its lead automatically. Making someone else lead demotes the previous lead to responder.

Add participants

Send exactly one of user_id, schedule_id or escalation_policy_id:

You send	Who is added
`user_id`	That user.
`schedule_id`	Whoever is on call in that schedule right now.
`escalation_policy_id`	The users and the on-call people at the policy’s first level.

Two optional fields shape the request: role (default responder) and page (default true). A lead is one person, so "role": "lead" needs user_id. Someone already on the incident keeps their role, and is paged again when page is true.

curl -X POST https://api.siteqwality.com/incident/$INCIDENT_ID/participants \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "schedule_id": "<schedule-id>", "role": "responder", "page": true }'

The response is the incident’s full participant list. GET /incident/{incident_id}/participants returns the same list.

Paging when you add

With page left at true, each added user is paged through their own notification rules, and the participant’s paged_at records when. Paging needs the incident to belong to a service and not be resolved; otherwise the request is refused (see Errors). Send "page": false to record someone who is already on the call without paging them.

Change a role or remove someone

curl -X PUT https://api.siteqwality.com/incident/$INCIDENT_ID/participants/$USER_ID \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "lead" }'

The response is the full list. DELETE /incident/{incident_id}/participants/{user_id} removes the person and returns 204.

Errors

Status	When
`400`	None or more than one of the three ids was sent, a `lead` was sent with a schedule or policy, or `page` is `true` on an incident with no service.
`404`	The incident, user, schedule or policy is not in your account. On a role change or removal, the user is not a participant.
`409`	`data.conflict` is `merged` (the incident was merged into another), `resolved` (`page` is `true` on a resolved incident) or `nobody_on_call` (the schedule or policy resolved to no one).
`422`	`role` is not `lead`, `responder` or `comms`.