Organization Settings
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)
curl -X GET "$BASE_URL/api/im/org-settings" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"Response
200 OK
{
"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 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)
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 Unauthorizedwhen not authenticated403 Forbidden(imAccessDenied) when using a customer-scoped token, or a session without an IM-eligible role403 Forbidden(forbidden) when updating without theadminrole400 Bad Request(invalidRequestBody) when the body is empty or contains an unsupported key (includingenabled),overageEnabledis not a boolean,monitoringBridgeis not an allowed value, orfallbackChannelIdis not a positive integer,null, or a channel of your organization400 Bad Request(imChannelInactive) whenfallbackChannelIdpoints to an inactive channel400 Bad Request(imFallbackChannelDeprecated) when the body containsfallbackChannel
Status Page Rules
Couple Incident Management to your status pages: rules that flip a page to warning or degraded on incidents of a team, plus a manual override.
Analytics
Incident volume, MTTA and MTTR per day, the alerts-to-incidents noise ratio and on-call load per user for a date range, in one call.