# Customer Journey API overview

The Customer Journey API lets a backend manage [Customer Journeys](/product/customer-journey/pushwoosh-journey-overview/) 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
```

<Aside type="tip">
If you use a dedicated region or private deployment, confirm the exact base URL with your Pushwoosh Customer Success Manager.
</Aside>

## Authentication

Every request must include an `Authorization` header with a server-side Pushwoosh [API access token](/developer/api-reference/api-access-token/#server-api-token):

```
Authorization: Api YOUR_API_TOKEN
```

<Aside type="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.
</Aside>

## Methods

### Manage journeys

- [Lifecycle](/developer/api-reference/customer-journey-api/lifecycle/): `POST /api/v3/journeygateway/{action}`. Start, pause, finish, draft, or archive a journey by its UUID.
- [Create and update](/developer/api-reference/customer-journey-api/create-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](/developer/api-reference/customer-journey-api/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](/developer/api-reference/customer-journey-api/statistics/): `GET /api/journey/{id}/statistics/external`. Per-point delivery and conversion metrics.
- [Remove users from journeys](/developer/api-reference/customer-journey-api/drop-users/): `POST /api/journey/drop-users/external`. Drop users from all or selected active journeys.

### Reference

- [Journey object](/developer/api-reference/customer-journey-api/journey-object/): the shape of the journey definition (info, params, points, comments) returned by the lifecycle, create, and update methods.
- [Point reference](/developer/api-reference/customer-journey-api/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](/developer/api-reference/customer-journey-api/lifecycle/#endpoints) changes the journey state (for example, from Draft to **Running**). 
[Start by API](/developer/api-reference/customer-journey-api/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](/developer/api-reference/customer-journey-api/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

```bash title="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

<CardGrid>
  <LinkCard title="Lifecycle" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="Create and update" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Start by API" href="/developer/api-reference/customer-journey-api/start-by-api/" />
  <LinkCard title="Get Journey stats" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="Remove users from journeys" href="/developer/api-reference/customer-journey-api/drop-users/" />
  <LinkCard title="Journey object" href="/developer/api-reference/customer-journey-api/journey-object/" />
  <LinkCard title="Point reference" href="/developer/api-reference/customer-journey-api/point-reference/" />
</CardGrid>