# Start by API

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

Enters a set of users into a journey's **API entry point**. Use it to drive journeys from your own backend. For example, start an onboarding flow when a user completes signup on your server.

<Aside type="tip">
Do not confuse this call with [Lifecycle start](/developer/api-reference/customer-journey-api/lifecycle/#endpoints), which activates a journey and moves it into **Running**. Start by API injects users into a journey that is already running. See the [comparison table](/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api).
</Aside>

## Prerequisites

- The journey is in the **Running** state.
- The journey contains exactly one API entry point (the "Start by API" element), and that element is not deactivated.
- The attribute names you send match the attributes configured on that API entry point.

<Aside type="caution" title="Rate limit">
Each API entry point accepts **one request per minute**. A second request within that window returns an error (`Enhance your calm! only one request per minute is allowed`). Batch your recipients into a single request rather than sending many small ones.
</Aside>

## Path parameters

| Name | Type | Description |
|---|---|---|
| `id` | string | [Journey ID](/developer/api-reference/api-identifiers/#journey-id) of the running journey. |

## Request headers

| Name | Required | Value |
|---|---|---|
| `Content-Type` | Yes | `application/json` |
| `Authorization` | Yes | `Api <server_api_token>`. See [Server API token](/developer/api-reference/api-access-token/#server-api-token). |

## Request body

The body has a single `payload` object. You must provide **exactly one** of `users`, `hwids`, or `filter` to select who enters the journey.

| Field | Type | Description |
|---|---|---|
| `payload.users` | string[] | [User IDs](/developer/api-reference/api-identifiers/#user-id) to enter. Mutually exclusive with `hwids` and `filter`. |
| `payload.hwids` | string[] | [HWIDs](/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) to enter. Mutually exclusive with `users` and `filter`. |
| `payload.filter` | string | A [seglang](/developer/api-reference/segmentation-filters-api/segmentation-language/) expression selecting the audience. Mutually exclusive with `users` and `hwids`. |
| `payload.attribute_values` | map&lt;string, string&gt; | Optional. Values for the custom attributes defined on the API entry point. Each key must match a configured attribute name. |

### Request examples

##### Enter specific users

```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"]
    }
  }'
```
##### Enter specific users with attributes

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

##### Enter an audience by filter

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


## Response

<Tabs>
<TabItem label="200">

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

| Field | Type | Description |
|---|---|---|
| `request_uuid` | string | Identifier of the accepted entry request. The request is processed asynchronously. |

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

Validation errors return HTTP `400` with a descriptive message. Common cases:

| Message | Cause |
|---|---|
| `one of users, hwids or filter must be provided` | None of the three selectors was set. |
| `only one of users, hwids or filter must be provided` | More than one selector was set. |
| `Journey is not running` | The journey is not in the Running state. |
| `zero api start points` | The journey has no API entry point. |
| `there is more then one api start point` | The journey has more than one API entry point. |
| `point is deactivated` | The API entry point is deactivated. |
| `unknown attribute: <name>` | An `attribute_values` key is not configured on the API entry point. |
| `Enhance your calm! only one request per minute is allowed` | Rate limit hit (one request per minute per entry point). |

</TabItem>
</Tabs>

## Related

<CardGrid>
  <LinkCard title="Lifecycle" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Get Journey stats" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Segmentation language" href="/developer/api-reference/segmentation-filters-api/segmentation-language/" />
</CardGrid>