Setup Progress and Test Page

GET /api/im/setup/state · PATCH /api/im/setup/state · POST /api/im/setup/test-page

The organization keeps one free-form setup object, so a setup flow (team, schedule, alert source, test page) can be resumed on another device or by another admin. These endpoints read and write that object, and send a test page to check that paging reaches you.

AuthenticationCopy Anchor Link

All three need an IM-eligible role (admin, editor, responder) or an organization-wide API token.

• The setup state is reachable before Incident Management is activated. Writing it requires the admin role of the organization.
• The test page requires Incident Management to be enabled and write access to the team: the admin role, or team-admin membership. It pages you, so it needs a user session; an organization-wide API token receives 403 (imAccessDenied).

Get the setup stateCopy Anchor Link

GET /api/im/setup/state

Example (cURL)Copy Anchor Link

curl -X GET "$BASE_URL/api/im/setup/state" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

ResponseCopy Anchor Link

{
  "organizationId": 42,
  "setupState": {
    "teamId": 7,
    "sourceCreated": true
  }
}

setupState is whatever was last stored (the keys above are only an example). It is {} until something was stored.

Store the setup stateCopy Anchor Link

PATCH /api/im/setup/state

Replaces the stored object as a whole.

Request BodyCopy Anchor Link

Example (cURL)Copy Anchor Link

curl -X PATCH "$BASE_URL/api/im/setup/state" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"setupState":{"teamId":7,"sourceCreated":true}}'

ResponseCopy Anchor Link

The stored state, in the same shape as the GET.

Send a test pageCopy Anchor Link

POST /api/im/setup/test-page

Creates a test incident (isTest: true, severity sev4, title "Setup wizard test page") in the given team and pages the caller on every channel that can reach them:

• email, always
• sms, when a verified phone number is set in the notification settings
• voice, additionally when includeVoice is true and the phone number is verified

Test incidents are not counted by Count Open Incidents. Test pages and test notifications share one limit of 5 per hour per user.

Request BodyCopy Anchor Link

Example (cURL)Copy Anchor Link

curl -X POST "$BASE_URL/api/im/setup/test-page" \
  -H "Content-Type: application/json" \
  -b "$SESSION_COOKIE" \
  -d '{"teamId":7}'

ResponseCopy Anchor Link

{
  "incidentId": 1834,
  "channels": ["email", "sms"],
  "enqueueErrors": []
}

enqueueErrors lists the channels whose page could not be queued. Empty on success.

Common errorsCopy Anchor Link

• 400 Bad Request (invalidRequestBody) when setupState is missing, not an object or larger than 8 KB, or when teamId is missing
• 401 Unauthorized when not authenticated
• 403 Forbidden (customerScopedTokenForbidden) when using a customer-scoped token
• 403 Forbidden (imAccessDenied) when the caller has no IM-eligible role, or when the test page is requested with an API token
• 403 Forbidden (forbidden) when a non-admin writes the setup state
• 403 Forbidden (imNotEnabled) when sending a test page before Incident Management is enabled
• 403 Forbidden (imTeamWriteDenied) when the caller may not write the team
• 422 Unprocessable Entity (invalidTeamId) when the team does not exist in your organization
• 429 Too Many Requests (imTestNotificationRateLimited) after 5 test pages or test notifications in an hour; retryAfterSeconds says when to retry