# Start per API

`POST` `https://journey.pushwoosh.com/api/journey/{id}/start/external`

Fügt eine Gruppe von Benutzern in den **API-Einstiegspunkt** einer Journey ein. Verwenden Sie dies, um Journeys von Ihrem eigenen Backend aus zu steuern. Starten Sie zum Beispiel einen Onboarding-Flow, wenn ein Benutzer die Registrierung auf Ihrem Server abschließt.

<Aside type="tip">
Verwechseln Sie diesen Aufruf nicht mit dem [Lifecycle-Start](/de/developer/api-reference/customer-journey-api/lifecycle/#endpoints), der eine Journey aktiviert und in den Zustand **Wird ausgeführt** versetzt. „Start per API“ fügt Benutzer in eine bereits laufende Journey ein. Siehe die [Vergleichstabelle](/de/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api).
</Aside>

## Voraussetzungen

- Die Journey befindet sich im Zustand **Wird ausgeführt**.
- Die Journey enthält genau einen API-Einstiegspunkt (das Element „Start per API“), und dieses Element ist nicht deaktiviert.
- Die von Ihnen gesendeten Attributnamen stimmen mit den Attributen überein, die für diesen API-Einstiegspunkt konfiguriert sind.

<Aside type="caution" title="Ratenbegrenzung">
Jeder API-Einstiegspunkt akzeptiert **eine Anfrage pro Minute**. Eine zweite Anfrage innerhalb dieses Zeitfensters gibt einen Fehler zurück (`Enhance your calm! only one request per minute is allowed`). Fassen Sie Ihre Empfänger in einer einzigen Anfrage zusammen, anstatt viele kleine Anfragen zu senden.
</Aside>

## Pfadparameter

| Name | Typ | Beschreibung |
|---|---|---|
| `id` | string | [Journey-ID](/de/developer/api-reference/api-identifiers/#journey-id) der laufenden Journey. |

## Anfrage-Header

| Name | Erforderlich | Wert |
|---|---|---|
| `Content-Type` | Ja | `application/json` |
| `Authorization` | Ja | `Api <server_api_token>`. Siehe [Server-API-Token](/de/developer/api-reference/api-access-token/#server-api-token). |

## Anfrage-Body

Der Body hat ein einziges `payload`-Objekt. Sie müssen **genau einen** der Parameter `users`, `hwids` oder `filter` angeben, um auszuwählen, wer in die Journey eintritt.

| Feld | Typ | Beschreibung |
|---|---|---|
| `payload.users` | string[] | [Benutzer-IDs](/de/developer/api-reference/api-identifiers/#user-id) zum Eintragen. Schließt sich gegenseitig mit `hwids` und `filter` aus. |
| `payload.hwids` | string[] | [HWIDs](/de/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) zum Eintragen. Schließt sich gegenseitig mit `users` und `filter` aus. |
| `payload.filter` | string | Ein [seglang](/de/developer/api-reference/segmentation-filters-api/segmentation-language/)-Ausdruck, der die Zielgruppe auswählt. Schließt sich gegenseitig mit `users` und `hwids` aus. |
| `payload.attribute_values` | map&lt;string, string&gt; | Optional. Werte für die benutzerdefinierten Attribute, die am API-Einstiegspunkt definiert sind. Jeder Schlüssel muss mit einem konfigurierten Attributnamen übereinstimmen. |

### Anfragebeispiele

##### Bestimmte Benutzer eintragen

```bash
curl -X POST 'https://journey.pushwoosh.com/api/journey/<journey_id>/start/external' \
  -H 'Authorization: Api YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "users": ["user-123", "user-456"]
    }
  }'
```
##### Bestimmte Benutzer mit Attributen eintragen

```json
{
  "payload": {
    "users": ["user-123", "user-456"],
    "attribute_values": {
      "promo_code": "SUMMER25",
      "tier": "gold"
    }
  }
}
```

##### Eine Zielgruppe nach Filter eintragen

```json
{
  "payload": {
    "filter": "A(\"XXXXX-XXXXX\").tags(\"City\").eq(\"London\")"
  }
}
```


## Antwort

<Tabs>
<TabItem label="200">

```json
{
  "request_uuid": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}
```

| Feld | Typ | Beschreibung |
|---|---|---|
| `request_uuid` | string | Kennung der akzeptierten Eintragsanfrage. Die Anfrage wird asynchron verarbeitet. |

</TabItem>
<TabItem label="400">

Validierungsfehler geben HTTP `400` mit einer beschreibenden Nachricht zurück. Häufige Fälle:

| Nachricht | Ursache |
|---|---|
| `one of users, hwids or filter must be provided` | Keiner der drei Selektoren wurde gesetzt. |
| `only one of users, hwids or filter must be provided` | Es wurde mehr als ein Selektor gesetzt. |
| `Journey is not running` | Die Journey befindet sich nicht im Zustand „Wird ausgeführt“. |
| `zero api start points` | Die Journey hat keinen API-Einstiegspunkt. |
| `there is more then one api start point` | Die Journey hat mehr als einen API-Einstiegspunkt. |
| `point is deactivated` | Der API-Einstiegspunkt ist deaktiviert. |
| `unknown attribute: <name>` | Ein `attribute_values`-Schlüssel ist am API-Einstiegspunkt nicht konfiguriert. |
| `Enhance your calm! only one request per minute is allowed` | Ratenbegrenzung erreicht (eine Anfrage pro Minute pro Einstiegspunkt). |

</TabItem>
</Tabs>

## Verwandte Themen

<CardGrid>
  <LinkCard title="Lebenszyklus" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Journey-Statistiken abrufen" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Segmentierungssprache" href="/developer/api-reference/segmentation-filters-api/segmentation-language/" />
</CardGrid>