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.

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.

Path parameters

Name	Type	Description
`id`	string	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.

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 to enter. Mutually exclusive with `hwids` and `filter`.
`payload.hwids`	string[]	HWIDs to enter. Mutually exclusive with `users` and `filter`.
`payload.filter`	string	A seglang expression selecting the audience. Mutually exclusive with `users` and `hwids`.
`payload.attribute_values`	map<string, string>	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

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

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

Enter an audience by filter

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

Response

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

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

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

Lifecycle

Get Journey stats

Segmentation language