---
title: "Team Overrides"
description: "List, add, edit and delete the on-call overrides of a team, both team-level overrides and those attached to one of the team's schedules."
---

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](/api/incident-management/team-insights#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](/api/incident-management/schedule-overrides), addressed through the team.

The fields and their meaning (`type`, covers, scope, tier, precedence) are described under [Override fields](/api/incident-management/schedule-overrides#override-fields). This page adds one field:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `scheduleId` | integer \| null | No | A schedule of this team to attach the override to. Omitted or `null` = team-level. |

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.

## Authentication

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 overrides

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

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

### Example (cURL)

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

### Response

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

```json
[
  {
    "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 override

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

### Example (cURL)

Bob takes tier 1 over Christmas:

```bash
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"
  }'
```

### Response

`200 OK`

```json
{
  "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 override

`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)

```bash
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"
  }'
```

### Response

`200 OK`: same shape as when adding.

## Delete an override

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

### Example (cURL)

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

### Response

`200 OK`

```json
{ "success": true }
```

## Common errors

- `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](/api/incident-management/schedule-overrides#common-errors)
- `400 Bad Request` (`imUserNotEligible`) when the subject or a covering user is inactive or does not have the organization role `admin`, `editor` or `responder`