---
title: "Setup Progress and Test Page"
description: "Read and store the progress of the Incident Management setup, and send yourself a test page through a team."
---

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

## Authentication

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](/api/incident-management/activate). 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 state

`GET /api/im/setup/state`

### Example (cURL)

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

### Response

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

`PATCH /api/im/setup/state`

Replaces the stored object as a whole.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `setupState` | object | Yes | A plain JSON object, at most 8 KB serialized. |

### Example (cURL)

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

### Response

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

## Send a test page

`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](/api/incident-management/notification-settings)
- `voice`, additionally when `includeVoice` is `true` and the phone number is verified

Test incidents are not counted by [Count Open Incidents](/api/incident-management/incident-count). Test pages and [test notifications](/api/incident-management/notification-settings#send-a-test-notification) share one limit of 5 per hour per user.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `teamId` | number | Yes | A team of your organization. |
| `includeVoice` | boolean | No | Also place a voice call. Default `false`. |

### Example (cURL)

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

### Response

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

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

## Common errors

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