---
title: "Organization Settings"
description: "Read and update the Incident Management settings of your organization: monitoring bridge, SMS/voice overage and the fallback channel."
---

`GET /api/im/org-settings` · `PATCH /api/im/org-settings`

The Incident Management settings of your organization. Both endpoints also work while Incident Management is **not yet enabled**, so you can check the state and prepare the configuration before activation. Activation itself is done in the dashboard, not through this endpoint.

## Authentication

Requires an IM-eligible role (`admin`, `editor` or `responder`) or an organization-wide API token. Unlike the rest of this API, Incident Management does not have to be enabled. Reading is open to any IM-eligible role. **Updating** requires the `admin` role. An organization-wide API token runs with the role of the user who created it.

## Get settings

`GET /api/im/org-settings`

### Example (cURL)

```bash
curl -X GET "$BASE_URL/api/im/org-settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

### Response

`200 OK`

```json
{
  "organizationId": 1,
  "enabled": true,
  "overageEnabled": false,
  "monitoringBridge": "both",
  "fallbackChannelId": 10,
  "fallbackChannel": null
}
```

| Field | Description |
|-------|-------------|
| `enabled` | Whether Incident Management is active. Read-only here. |
| `overageEnabled` | Whether SMS and voice notifications may continue beyond the included quota (billed). Default `false`. |
| `monitoringBridge` | How monitoring incidents relate to Incident Management. `both` (default): monitoring incidents also open IM incidents, and classic alerts are still sent. `im_only`: monitoring incidents open IM incidents, classic alerts are suppressed. `classic_only`: no bridge, only classic alerts. |
| `fallbackChannelId` | ID of the [channel](/api/incident-management/channels) paged when an escalation runs out of tiers, or `null`. |
| `fallbackChannel` | Legacy field, read-only, no effect. Use `fallbackChannelId`. |

## Update settings

`PATCH /api/im/org-settings`

Partial update. At least one field is required; any other key is a `400`.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `overageEnabled` | boolean | No | Allow SMS/voice beyond the included quota. |
| `monitoringBridge` | string | No | `im_only`, `classic_only` or `both`. |
| `fallbackChannelId` | integer \| null | No | An **active** channel of your organization, or `null` to clear. |

`enabled` cannot be set here, and the legacy `fallbackChannel` is rejected.

### Example (cURL)

```bash
curl -X PATCH "$BASE_URL/api/im/org-settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "fallbackChannelId": 10, "monitoringBridge": "im_only" }'
```

### Response

`200 OK`: the updated settings, same shape as the GET response.

## Common errors

- `401 Unauthorized` when not authenticated
- `403 Forbidden` (`imAccessDenied`) when using a customer-scoped token, or a session without an IM-eligible role
- `403 Forbidden` (`forbidden`) when updating without the `admin` role
- `400 Bad Request` (`invalidRequestBody`) when the body is empty or contains an unsupported key (including `enabled`), `overageEnabled` is not a boolean, `monitoringBridge` is not an allowed value, or `fallbackChannelId` is not a positive integer, `null`, or a channel of your organization
- `400 Bad Request` (`imChannelInactive`) when `fallbackChannelId` points to an inactive channel
- `400 Bad Request` (`imFallbackChannelDeprecated`) when the body contains `fallbackChannel`