Customer Journey API overview

The Customer Journey API lets a backend manage Customer Journeys programmatically: create and edit journey definitions, move journeys through their lifecycle (start, pause, finish, draft, archive), trigger a running journey from your own systems, and pull per-journey statistics.

It is the same API the Customer Journey builder uses, exposed over REST/JSON through a gRPC-Gateway bridge.

Base URL

https://journey.pushwoosh.com

Tip

If you use a dedicated region or private deployment, confirm the exact base URL with your Pushwoosh Customer Success Manager.

Authentication

Every request must include an Authorization header with a server-side Pushwoosh API access token:

Authorization: Api YOUR_API_TOKEN

Note

The token is bound to the account that owns it. All operations apply to that account. Use the same token you issue for other server-to-server API calls, and never expose it in client applications.

Methods

Manage journeys

• Lifecycle: POST /api/v3/journeygateway/{action}. Start, pause, finish, draft, or archive a journey by its UUID.
• Create and update: POST /api/v3/journeygateway and PUT /api/v3/journeygateway/{uuid}. Create a new journey definition or replace an existing one.

Trigger journeys

• Start by API: POST /api/journey/{id}/start/external. Inject users into the API entry point of a journey that is already running.

Statistics and audience

• Get Journey stats: GET /api/journey/{id}/statistics/external. Per-point delivery and conversion metrics.
• Remove users from journeys: POST /api/journey/drop-users/external. Drop users from all or selected active journeys.

Reference

• Journey object: the shape of the journey definition (info, params, points, comments) returned by the lifecycle, create, and update methods.
• Point reference: the point_data structure for each point type: entry, timing, splitting, action, and messaging elements.

Lifecycle start vs Start by API

Customer Journey has two operations that sound similar but behave differently.

Lifecycle start changes the journey state (for example, from Draft to Running). Start by API injects users into an already-running journey. The table below compares them side by side.

	Lifecycle Start	Start by API
Endpoint	POST /api/v3/journeygateway/start	POST /api/journey/{id}/start/external
What it does	Activates the journey and moves it into the Running state	Injects users into the API entry point of an already-running journey
Journey state required	Draft or Paused	Running (with an API Start point)
Run frequency	Once per state change	Repeatedly, as users need to enter

Request and response format

• Content type: application/json.
• The v3 field names use snake_case. Enum values are serialized as their string names (for example, "STATUS_RUNNING", "POINT_TYPE_SEND_PUSH").
• The gRPC-Gateway methods (/api/v3/journeygateway/...) return the journey object on success and the standard gRPC-Gateway error envelope on failure: { "code": ..., "message": ..., "details": [...] }.
• The legacy external methods (/api/journey/...) return a method-specific JSON body on success and { "success": false, "message": ... } with HTTP 400 on validation errors.

Quick start

Start a journey

curl -X POST https://journey.pushwoosh.com/api/v3/journeygateway/start \
  -H "Authorization: Api YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "11111111-2222-3333-4444-555555555555" }'

Next steps

Lifecycle

Create and update

Start by API

Get Journey stats

Remove users from journeys

Journey object

Point reference