---
title: "Einrichtungsstand und Test-Alarm"
description: "Den Fortschritt der Incident-Management-Einrichtung lesen und speichern, und dir selbst über ein Team einen Test-Alarm schicken."
---

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

Die Organisation hat ein frei gestaltbares Einrichtungsobjekt, damit sich eine Einrichtung (Team, Dienstplan, Alarmquelle, Test-Alarm) auf einem anderen Gerät oder von einem anderen Admin fortsetzen lässt. Diese Endpunkte lesen und schreiben dieses Objekt und schicken einen Test-Alarm, mit dem du prüfst, ob die Alarmierung dich erreicht.

## Authentifizierung

Alle drei brauchen eine IM-berechtigte Rolle (`admin`, `editor`, `responder`) oder einen organisationsweiten API-Token.

- Der **Einrichtungsstand** ist schon vor der [Aktivierung](/de/api/incident-management/activate) von Incident Management erreichbar. Schreiben erfordert die Rolle `admin` der Organisation.
- Der **Test-Alarm** erfordert aktiviertes Incident Management und Schreibrechte am Team: die Rolle `admin` oder Team-Admin-Mitgliedschaft. Er alarmiert **dich**, braucht also eine Benutzersitzung; ein organisationsweiter API-Token erhält `403` (`imAccessDenied`).

## Einrichtungsstand lesen

`GET /api/im/setup/state`

### Beispiel (cURL)

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

### Antwort (Response)

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

`setupState` ist das zuletzt gespeicherte Objekt (die Schlüssel oben sind nur ein Beispiel). Solange nichts gespeichert wurde, ist es `{}`.

## Einrichtungsstand speichern

`PATCH /api/im/setup/state`

Ersetzt das gespeicherte Objekt vollständig.

### Request Body

| Feld | Typ | Pflicht | Beschreibung |
|------|-----|---------|--------------|
| `setupState` | object | Ja | Ein einfaches JSON-Objekt, serialisiert höchstens 8 KB. |

### Beispiel (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}}'
```

### Antwort (Response)

Der gespeicherte Stand, in derselben Form wie beim GET.

## Test-Alarm senden

`POST /api/im/setup/test-page`

Legt im angegebenen Team einen Test-Incident an (`isTest: true`, Schweregrad `sev4`, Titel „Setup wizard test page“) und alarmiert dich auf jedem Kanal, der dich erreichen kann:

- `email`, immer
- `sms`, wenn in den [Benachrichtigungseinstellungen](/de/api/incident-management/notification-settings) eine bestätigte Telefonnummer hinterlegt ist
- `voice`, zusätzlich wenn `includeVoice` `true` ist und die Telefonnummer bestätigt ist

Test-Incidents zählt [Offene Incidents zählen](/de/api/incident-management/incident-count) nicht mit. Test-Alarme und [Test-Benachrichtigungen](/de/api/incident-management/notification-settings#test-benachrichtigung-senden) teilen sich eine Grenze von 5 pro Stunde und Person.

### Request Body

| Feld | Typ | Pflicht | Beschreibung |
|------|-----|---------|--------------|
| `teamId` | number | Ja | Ein Team deiner Organisation. |
| `includeVoice` | boolean | Nein | Zusätzlich anrufen. Standard `false`. |

### Beispiel (cURL)

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

### Antwort (Response)

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

`enqueueErrors` nennt die Kanäle, deren Alarm nicht in die Warteschlange kam. Leer bei Erfolg.

## Häufige Fehler

- `400 Bad Request` (`invalidRequestBody`) wenn `setupState` fehlt, kein Objekt oder größer als 8 KB ist, oder wenn `teamId` fehlt
- `401 Unauthorized` wenn du nicht authentifiziert bist
- `403 Forbidden` (`customerScopedTokenForbidden`) bei Verwendung eines kunden-gescopten Tokens
- `403 Forbidden` (`imAccessDenied`) wenn keine IM-berechtigte Rolle vorliegt, oder wenn der Test-Alarm mit einem API-Token angefordert wird
- `403 Forbidden` (`forbidden`) wenn jemand ohne Admin-Rolle den Einrichtungsstand schreibt
- `403 Forbidden` (`imNotEnabled`) wenn ein Test-Alarm vor der Aktivierung von Incident Management angefordert wird
- `403 Forbidden` (`imTeamWriteDenied`) wenn du das Team nicht bearbeiten darfst
- `422 Unprocessable Entity` (`invalidTeamId`) wenn das Team in deiner Organisation nicht existiert
- `429 Too Many Requests` (`imTestNotificationRateLimited`) nach 5 Test-Alarmen oder Test-Benachrichtigungen in einer Stunde; `retryAfterSeconds` sagt, wann es wieder geht