Team Overrides

These endpoints manage every override a team owns in one place:

• Team-level overrides (scheduleId: null) need no schedule. They apply whenever the team's on-call set is resolved (paging, on-call now, the calendar), so a team can be driven by overrides alone.
• Schedule overrides (scheduleId set) are the same overrides as on Schedule Overrides, addressed through the team.

The fields and their meaning (type, covers, scope, tier, precedence) are described under Override fields. This page adds one field:

An offline team-level override only removes the subject while they actually have a shift in that tier. For a subject who is not on call there, it has no effect.

AuthenticationCopy Anchor Link

Base IM access: an IM-eligible role or an organization-wide API token, and Incident Management activated for the organization. Listing is open to any caller with that access. Adding, editing and deleting need the team write bar: organization admin role, or team admin of this team. An API token runs with the role of the user who created it, so only a token created by an organization admin passes.

List overridesCopy Anchor Link

GET /api/im/teams/:id/overrides

Returns all of the team's overrides, team-level and schedule-attached, ordered by id.

Example (cURL)Copy Anchor Link

curl -X GET "$BASE_URL/api/im/teams/3/overrides" \
  -H "Authorization: Bearer $TOKEN"

ResponseCopy Anchor Link

200 OK: same item shape as the schedule override list.

[
  {
    "id": 31,
    "scheduleId": null,
    "userId": "u_def456",
    "userName": "Bob Fixit",
    "userImage": null,
    "type": "online",
    "applyScope": "this_team",
    "escalationTierOrder": 1,
    "startsAt": "2026-12-24T18:00:00.000Z",
    "endsAt": "2026-12-26T08:00:00.000Z",
    "createdAt": "2026-10-09T10:00:00.000Z",
    "coveredBy": []
  }
]

Add an overrideCopy Anchor Link

POST /api/im/teams/:id/overrides

Example (cURL)Copy Anchor Link

Bob takes tier 1 over Christmas:

curl -X POST "$BASE_URL/api/im/teams/3/overrides" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "u_def456",
    "type": "online",
    "escalationTierOrder": 1,
    "startsAt": "2026-12-24T18:00:00.000Z",
    "endsAt": "2026-12-26T08:00:00.000Z"
  }'

ResponseCopy Anchor Link

200 OK

{
  "id": 31,
  "teamId": 3,
  "scheduleId": null,
  "userId": "u_def456",
  "type": "online",
  "applyScope": "this_team",
  "escalationTierOrder": 1,
  "startsAt": "2026-12-24T18:00:00.000Z",
  "endsAt": "2026-12-26T08:00:00.000Z",
  "createdAt": "2026-10-09T10:00:00.000Z",
  "coveredByUserIds": []
}

Edit an overrideCopy Anchor Link

PATCH /api/im/teams/:id/overrides/:overrideId

A full replace: send every field again. This includes scheduleId: leaving it out turns a schedule override into a team-level one. Changing it moves the override between team-level and one of the team's schedules. The override keeps its id and therefore its precedence.

Example (cURL)Copy Anchor Link

curl -X PATCH "$BASE_URL/api/im/teams/3/overrides/31" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "u_def456",
    "type": "online",
    "escalationTierOrder": null,
    "scheduleId": null,
    "startsAt": "2026-12-24T18:00:00.000Z",
    "endsAt": "2026-12-27T08:00:00.000Z"
  }'

ResponseCopy Anchor Link

200 OK: same shape as when adding.

Delete an overrideCopy Anchor Link

DELETE /api/im/teams/:id/overrides/:overrideId

Example (cURL)Copy Anchor Link

curl -X DELETE "$BASE_URL/api/im/teams/3/overrides/31" \
  -H "Authorization: Bearer $TOKEN"

ResponseCopy Anchor Link

200 OK

{ "success": true }

Common errorsCopy Anchor Link

• 401 Unauthorized (unauthorized) when not authenticated
• 403 Forbidden (imAccessDenied) for a customer-scoped token, or a session without an IM-eligible role
• 403 Forbidden (imNotEnabled) when Incident Management is not activated for the organization
• 403 Forbidden (imTeamWriteDenied) on add, edit or delete when you are neither organization admin nor team admin of this team
• 404 Not Found (imTeamNotFound) when the team does not exist or belongs to another organization
• 404 Not Found (imOverrideNotFound) when :overrideId is not an override of this team
• 404 Not Found (imScheduleNotFound) when scheduleId is not a schedule of this team
• 404 Not Found (userNotFound) when userId or a covering user does not exist or belongs to another organization
• 400 Bad Request (invalidRequestBody) when a path id is not a positive integer, scheduleId is neither a positive integer nor null, or a field fails the checks listed under Schedule Overrides
• 400 Bad Request (imUserNotEligible) when the subject or a covering user is inactive or does not have the organization role admin, editor or responder