# Journey object

The [lifecycle](/developer/api-reference/customer-journey-api/lifecycle/), [create, and update](/developer/api-reference/customer-journey-api/create-update/) methods all return a journey object with the same top-level shape:

```json title="Shape"
{
  "info": { ... },        // read-only metadata (responses only)
  "params": { ... },      // journey-wide configuration (create / update)
  "points": [ ... ],      // canvas nodes and their connections
  "comments": [ ... ]     // canvas comments
}
```

When you **create** or **update** a journey you send `title`, `params`, `points`, and `comments`. Responses return `info` (which contains `params`) plus `points` and `comments`.

## Info

Read-only journey metadata. Returned by every v3 method. Not part of the request body.

| Field | Type | Description |
|---|---|---|
| `uuid` | string | [Journey ID](/developer/api-reference/api-identifiers/#journey-id). |
| `title` | string | Journey name. |
| `status` | [`JourneyStatus`](#journeystatus-enum) | Current state. |
| `created_at` | string | Creation timestamp (ISO 8601). |
| `updated_at` | string | Last update timestamp (ISO 8601). |
| `is_first_activated` | bool | Whether the journey has been started at least once. |
| `params` | [`JourneyParams`](#journeyparams) | Journey-wide configuration. |
| `category_uuid` | string | UUID of the category, or empty if uncategorized. |
| `pointCounts` | map<string, uint32> | Count of points by type. |
| `campaign_type` | [`CampaignType`](#campaigntype-enum) | How users enter the journey. |
| `stop_reason` | string | Why the journey stopped, if applicable. |
| `last_edited_by` | `User` | User who last edited the journey. |
| `dynamic_entry` | bool | Whether dynamic entry is enabled. |

## JourneyParams

Journey-wide configuration. Sent on create/update and returned inside `info.params`.

| Field | Type | Description |
|---|---|---|
| `application_code` | string | [Application code](/developer/api-reference/api-identifiers/#application-code) the journey belongs to. Required on create. |
| `silent_hours` | [`SilentHours`](#silenthours) | Hours during which messages are suppressed, per channel. |
| `capping` | [`EntryCapping`](#entrycapping) | Limits on how often a user can re-enter the journey. |
| `conversion_window` | [`ConversionWindow`](#conversionwindow) | Window for attributing goal conversions. |
| `user_id_track_change_policy` | [`UserIDTrackChangePolicy`](#useridtrackchangepolicy-enum) | How to handle a user's ID changing mid-journey. |

### SilentHours

Suppresses sending during quiet hours. Configured **per channel**: each channel takes its own `SilentHoursParams`:

| Field | Type | Description |
|---|---|---|
| `push_params` | `SilentHoursParams` | Silent hours for push notifications. |
| `inapp_params` | `SilentHoursParams` | Silent hours for in-app messages. |
| `email_params` | `SilentHoursParams` | Silent hours for emails. |
| `sms_params` | `SilentHoursParams` | Silent hours for SMS. |
| `whatsapp_params` | `SilentHoursParams` | Silent hours for WhatsApp. |
| `line_params` | `SilentHoursParams` | Silent hours for LINE. |

Each `SilentHoursParams` is:

| Field | Type | Description |
|---|---|---|
| `enabled` | bool | Whether silent hours apply to this channel. |
| `from_time` | `Time` | Start of the quiet window: `{ "hour": 0–23, "minute": 0–59 }`. |
| `to_time` | `Time` | End of the quiet window. |
| `week_days` | bool[] | Seven booleans for the days the window applies (Monday = index 0). |
| `behavior` | enum | What to do when a message falls inside silent hours: `WaitAndSend` (hold, then send when the window ends), `DropAndGo` (skip the message, continue the journey immediately), or `WaitAndDrop` (wait out the window, then continue without sending). |

### EntryCapping

Limits how often the same user can enter the journey.

| Field | Type | Description |
|---|---|---|
| `is_enabled` | bool | Whether entry capping is on. |
| `period` | uint64 | Minimum number of seconds between a user's entries. |

### ConversionWindow

| Field | Type | Description |
|---|---|---|
| `seconds` | uint64 | How long after entering a journey a user's goal completion still counts as a conversion. |

## Point

A point is a node on the journey canvas: an entry point, a message, a delay, a splitter, and so on.

| Field | Type | Description |
|---|---|---|
| `uuid` | string | Unique ID of the point within the journey. Must be a canonical [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122) UUID: 32 hex digits in 8-4-4-4-12 groups. |
| `title` | string | Display name of the point. |
| `point_type` | [`PointType`](#pointtype-enum) | The kind of node. |
| `outputs` | array of [`PointOutput`](#pointoutput) | Connections to downstream points. |
| `position` | [`Position`](#position) | Canvas coordinates. |
| `point_data` | object | Exactly one nested key, matching `point_type` (see the [point types](#point-types-and-point_data) table). |

<Aside type="note">
All UUIDs (`info.uuid`, every point `uuid`, and each output's `next_point_uuid`) must be canonical RFC 4122 UUIDs (8-4-4-4-12 hex groups).
</Aside>

### PointOutput

A point's outputs are its outgoing branches. Their keys are **not free-form**. The validator expects an exact set of keys for each point type, and rejects a journey whose point has the wrong number of outputs or a key it does not recognize.

| Field | Type | Description |
|---|---|---|
| `identity.key` | string | Branch key. Must follow the [output key rules](#output-keys) below. |
| `identity.order` | int | Display order of the branch. |
| `info.title` | string | Optional branch label. |
| `info.next_point_uuid` | string | UUID of the next point this branch connects to. |

#### Output keys

The default (first) branch is always named `"default"`. Additional branches are named `"output1"`, `"output2"`, … (the prefix `output` followed by a 1-based index). Two point types break this rule, noted below.

| Point type | Expected output keys |
|---|---|
| Entry points (`START_BY_SEGMENT`, `START_BY_API`, `EVENT`), `INAPP`, `SET_TAGS`, `WEBHOOK`, `AUDIENCE_SYNC`, and message points with no splitter (`SEND_PUSH`, `SEND_EMAIL`, `SEND_SMS`, `SEND_WHATSAPP`, `SEND_LINE`, `SEND_KAKAO`, `SEND_TELEGRAM`, `SEND_DATA`) | `default` |
| `GOAL_EVENT`, `EXIT` | none (no outputs) |
| `FILTER` | `default`, `output1` |
| `BOOLEAN_SPLITTER` | `default`, then `output1` … `outputN` (one extra branch per condition. A simple yes/no split is `default` + `output1`) |
| `WAIT` (delay) | `default`. A dynamic delay with branch splitting adds `output1` |
| `WAIT_EVENT` | `default` is the **event-not-triggered** branch. `output1` (or, with a conditions script, one branch per condition) is the triggered path |
| `SEND_PUSH` with a splitter | `default`, `output1` (and `output2` when both the message and delivery splitters are on) |
| `SEND_EMAIL` / `SEND_SMS` / `SEND_LINE` / `SEND_WHATSAPP` with a splitter | `default`, `output1` |
| `SEND_WHATSAPP` with a quick-reply preset | `default`, plus one branch per quick reply. The key is the quick-reply value itself |
| `AB_SPLITTER` | `output0`, `output1`, `output2`, … (one per variant. **There is no `default` branch**) |

### Position

| Field | Type | Description |
|---|---|---|
| `x` | float | Horizontal coordinate on the canvas. |
| `y` | float | Vertical coordinate on the canvas. |

## Point types and point_data

`point_data` is a one-of: it carries exactly one nested object whose key is determined by the point's `point_type`.

| `point_type` | `point_data` key | Purpose |
|---|---|---|
| `POINT_TYPE_START_BY_SEGMENT` | `start_by_segment` | Entry: users matching a segment. |
| `POINT_TYPE_EVENT` | `message_bus` | Entry: users triggering an event. |
| `POINT_TYPE_START_BY_API` | `start_by_api` | Entry: users injected via the [Start by API](/developer/api-reference/customer-journey-api/start-by-api/) call. |
| `POINT_TYPE_WAIT` | `delay` | Wait for a fixed or dynamic interval. |
| `POINT_TYPE_WAIT_EVENT` | `wait_event` | Wait until an event happens. |
| `POINT_TYPE_SEND_PUSH` | `send_push` | Send a push notification. |
| `POINT_TYPE_SEND_EMAIL` | `send_email` | Send an email. |
| `POINT_TYPE_SEND_SMS` | `send_sms` | Send an SMS. |
| `POINT_TYPE_SEND_WHATSAPP` | `send_whatsapp` | Send a WhatsApp message. |
| `POINT_TYPE_SEND_TELEGRAM` | `send_telegram` | Send a Telegram message. |
| `POINT_TYPE_SEND_KAKAO` | `send_kakao` | Send a Kakao message. |
| `POINT_TYPE_SEND_LINE` | `send_line` | Send a LINE message. |
| `POINT_TYPE_SEND_DATA` | `send_data` | Send a silent data message. |
| `POINT_TYPE_INAPP` | `inapp` | Show an in-app message. |
| `POINT_TYPE_BOOLEAN_SPLITTER` | `boolean_splitter` | Split users by a condition (segment, tags, or event). |
| `POINT_TYPE_AB_SPLITTER` | `ab_splitter` | Split users into A/B groups. |
| `POINT_TYPE_FILTER` | `filter` | Allow only users matching a filter to continue. |
| `POINT_TYPE_SET_TAGS` | `set_tags` | Update user tags. |
| `POINT_TYPE_WEBHOOK` | `web_hook` | Send an outbound HTTP request. |
| `POINT_TYPE_GOAL_EVENT` | `goal_event` | Track a conversion goal. |
| `POINT_TYPE_AUDIENCE_SYNC` | `audience_sync` | Sync users to an external audience. |
| `POINT_TYPE_EXIT` | `terminator` | Exit the journey. |

<Aside type="note">
The per-type `point_data` payloads are documented in the [Point reference](/developer/api-reference/customer-journey-api/point-reference/). Entry, timing, splitting, and action points are covered in full there. Messaging points are covered at the envelope level with links to the relevant channel docs.
</Aside>

### Example point

A "set tags" point with a single downstream connection:

```json
{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Tag as engaged",
  "point_type": "POINT_TYPE_SET_TAGS",
  "position": { "x": 480, "y": 120 },
  "outputs": [
    {
      "identity": { "key": "default", "order": 0 },
      "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" }
    }
  ],
  "point_data": {
    "set_tags": {
      "application_code": "XXXXX-XXXXX",
      "tags": [ { "name": "engaged", "value": "true" } ]
    }
  }
}
```

## JourneyComment

| Field | Type | Description |
|---|---|---|
| `id` | string | Comment UUID. |
| `message` | string | Comment text. |
| `position` | [`Position`](#position) | Canvas coordinates. |
| `index` | int | Display order. |
| `created_at` | string | Creation timestamp (ISO 8601). |
| `deleted` | bool | Whether the comment is deleted. |

## Enums

### JourneyStatus enum

`STATUS_DRAFT`, `STATUS_RUNNING`, `STATUS_FINISHED`, `STATUS_ARCHIVED`, `STATUS_PAUSED`, `STATUS_UNKNOWN`.

### CampaignType enum

- `TriggerBased`: users enter on an event.
- `AudienceBased`: users enter from a segment.
- `APIBased`: users enter via the Start by API call.
- `Mixed`: more than one entry type.
- `Unknown`: entry type not determined.

### PointType enum

See the [point types](#point-types-and-point_data) table above for the full list and the `point_data` key each maps to.

### UserIDTrackChangePolicy enum

Controls what happens to a user who is mid-journey when their [User ID](/developer/api-reference/api-identifiers/#user-id) changes:

- `DEFAULT`: default behavior.
- `TRACK`: keep tracking the user under the new ID.
- `DROP`: remove the user from the journey when their ID changes.

## Related

<CardGrid>
  <LinkCard title="Point reference" href="/developer/api-reference/customer-journey-api/point-reference/" />
  <LinkCard title="Create and update" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="Lifecycle" href="/developer/api-reference/customer-journey-api/lifecycle/" />
</CardGrid>