---
title: "Sammelaktionen"
description: "Wendet eine Aktion auf mehrere Kunden gleichzeitig an, für Mehrfachauswahl-Workflows."
---

`POST /api/customers/bulk`

Wendet eine einzelne Aktion auf eine Liste von Kunden-IDs an. Jede ID wird unabhängig
verarbeitet: Ein einzelner Konflikt oder ein fehlender Kunde bricht die restlichen nicht ab. Die
Antwort ist immer **`200 OK`**, auch wenn einzelne IDs fehlgeschlagen sind. Prüfe daher `failed`
statt dich allein auf den HTTP-Status zu verlassen.

## Authentifizierung

```bash
BASE_URL="https://uptimeify.io"
TOKEN="<your-api-token>"
```

## Anfrage (Request Body)

```json
{
  "ids": [101, 102, 103],
  "action": "reports",
  "payload": {
    "enabled": true
  }
}
```

| Feld | Typ | Erforderlich | Beschreibung |
|------|-----|---------------|--------------|
| `ids` | number[] | ja | Kunden-IDs (die numerische `id`, nicht `publicId`). Nicht leer, maximal **200** Einträge, positive Ganzzahlen, keine Duplikate. |
| `action` | string | ja | Eine von `reports`, `activate`, `deactivate`, `delete`, `package`. |
| `payload` | object | abhängig von `action` | Erforderlich für `reports` und `package` (siehe unten). Wird bei `activate`, `deactivate`, `delete` ignoriert. |

### Aktionen

| Aktion | Wirkung | `payload` |
|--------|---------|-----------|
| `reports` | Setzt `monthlyReportsEnabled` bei jedem Kunden. | `{ "enabled": boolean }` (erforderlich) |
| `activate` | Setzt den Kundenstatus auf `active` (kein Effekt, falls bereits aktiv) und kaskadiert die Monitor-Status entsprechend. | keins |
| `deactivate` | Setzt den Kundenstatus auf `inactive` (kein Effekt, falls bereits inaktiv) und kaskadiert die Monitor-Status entsprechend. | keins |
| `delete` | Löscht den Kunden endgültig (Hard Delete). Monitore und Check-Historie werden per Kaskade mitgelöscht. **Nicht rückgängig zu machen.** | keins |
| `package` | Weist dem Kunden ein anderes Paket per ID zu. | `{ "packageId": number }` (erforderlich) |

`package` akzeptiert ausschließlich eine numerische `packageId`, die zur **Organisation des
jeweiligen Kunden** gehört. Für alle Aufrufenden außer globalen Admins ist das dasselbe wie die
eigene Organisation, denn nur deren Kunden sind überhaupt adressierbar. Ein globaler Admin, der
Kunden mehrerer Organisationen bearbeitet, braucht je Kunde eine `packageId` aus dessen eigener
Organisation; eine fremde wird mit `invalidPackageType` abgelehnt. Anders als bei [Kunden aktualisieren](/de/api/customers/update-customer)
wird kein legacy `packageType`-String oder Display-Name aufgelöst, denn das Erraten des gemeinten
Pakets über bis zu 200 Zeilen hinweg ist genau das, was der Sammelaktions-Endpunkt nicht tut. Die
ID lässt sich zuvor über [Paket-Konfigurationen auflisten](/de/api/organization/list-package-configs) ermitteln.

`payload.enabled` und `payload.packageId` werden **einmalig im Voraus** validiert, bevor
irgendein Kunde angefasst wird. Ein fehlerhaftes Payload lässt die gesamte Anfrage mit
`400 invalidRequestBody` fehlschlagen; es wird niemals zu 200 identischen Einzel-Fehlern pro ID.

## Beispiel-Request

```bash
curl -X POST "$BASE_URL/api/customers/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [101, 102, 103],
    "action": "reports",
    "payload": { "enabled": true }
  }'
```

## Beispiel-Response (Teilergebnis)

```json
{
  "ok": [101, 103],
  "failed": [
    { "id": 102, "reason": "customerNotFound" }
  ]
}
```

`ok` listet die aktualisierten IDs. `failed` listet die nicht aktualisierten IDs, jeweils mit
einem `reason`-String. Zeige das Teilergebnis an (zum Beispiel „2 von 3 aktualisiert"), niemals
einen pauschalen Erfolg allein aufgrund des `200`-Status der Anfrage.

## Häufige Fehler

Diese lassen die **gesamte Anfrage** fehlschlagen, bevor überhaupt ein Kunde angefasst wird:

- `401 unauthorized` du bist nicht eingeloggt
- `403 forbidden` deine Rolle ist `readonly`, oder du bist Global Supporter (beide sind für diesen Endpunkt nur lesend)
- `400 invalidRequestBody` `ids` fehlt/ist leer/ist kein Array, enthält mehr als 200 Einträge, enthält eine Nicht-Ganzzahl, einen Wert `<= 0` oder ein Duplikat; `action` ist keine der fünf unterstützten Aktionen; oder `payload.enabled` bzw. `payload.packageId` fehlt oder hat den falschen Typ für die gewählte Aktion

Diese erscheinen pro ID, innerhalb von `failed[].reason`, ohne die Anfrage fehlschlagen zu lassen:

| Reason | Bedeutung |
|--------|-----------|
| `customerNotFound` | Die ID existiert nicht oder gehört zu einer anderen Organisation (Global Admins dürfen jede ID ansprechen; alle anderen sind auf ihre eigene Organisation beschränkt). Bewusst nicht von „existiert nicht" zu unterscheiden, damit dieser Endpunkt nicht zum Aufspüren fremder IDs missbraucht werden kann. |
| `invalidPackageType` | Nur bei Aktion `package`: `payload.packageId` löst sich nicht auf eine Paket-Konfiguration auf, die zur Organisation dieses Kunden gehört. |
| `organizationIdRequired` | Die Session des Aufrufers hat weder einen Organisationsbezug noch Global-Admin-Scope. Nur bei einer fehlerhaften Session/einem fehlerhaften Token möglich; ein normal authentifizierter Aufrufer sieht das nie. |
| `unknown` | Jede andere Ablehnung, am häufigsten ein kunden-gescopter Aufrufer (eine eingeschränkte Rolle, oder ein kunden-gescoptes API-/Agent-Token), der eine ID außerhalb seiner zugewiesenen Kunden anspricht. Außerdem die Rückfallebene für jeden Fehler ohne stabilen `data.code`. |