# Journeys

Manage audience entry and exit for [Sequences](/guides/messaging/messages/sequences/about/) using the `/api/journeys` endpoints.


## Enter or exit a Sequence {#triggerjourneyssegment}

Enters an audience segment into a [Sequence](/docs/guides/messaging/messages/sequences/about/) identified by `triggering_id`, or exits one from it. If multiple Sequences share a `triggering_id`, the call enters or exits audiences in all of them. Use `entrance_id` to run multiple concurrent, independent instances of the Sequence for the same users without overwriting earlier enrollments.

[Jump to examples ↓](#triggerjourneyssegment-examples)

### `POST /api/journeys/trigger`

**Security:**

- [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-oauth2Token): jny

**Request body**

**Content-Type:** `application/json`

- **`audience`** `object` <[Audience selector (max 1000)]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#audienceselector1000)> **REQUIRED**

  An audience selector forms the expression that determines the set of channels to target.

- **`entrance_id`** `string`

  A unique identifier for enrolling the same users in multiple concurrent, independent instances of a Sequence.  Each call with a different `entrance_id` creates a new enrollment without overwriting earlier ones.

  Min length: 1, Max length: 64

- **`global_attributes`** `object`

  The global attributes object may contain an arbitrary set of keys and values, including arrays and nested objects,  which will be used for personalization of triggered pushes. Top-level keys cannot start with the reserved prefix ``ua_``.

  Example: `[object Object]`

- **`triggering_id`** **REQUIRED**
  **One of:**

  - `string`

    Identifier of a Sequence's configured [API Entrance trigger](/docs/guides/messaging/messages/sequences/triggers/#api-entrance).

  - `array<string>`

**Responses**

**`200`** Returned if the request has successfully been sent.  This does not indicate that an existing Sequence successfully received the request.

Response body:

**Content-Type:** `application/vnd.urbanairship+json; version=3`

[OK response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#okresponseobject)

**`400`** There was a parsing or validation error in the request. Bad Request errors typically include `path` and `location` in the response to help you find the cause of the error.

Response body:

**Content-Type:** `application/json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing.

Response body:

**Content-Type:** `text/plain`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`403`** Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

Response body:

**Content-Type:** `application/json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`429`** Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.

Response body:

**Content-Type:** `application/json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**Examples**

*Example enter an audience into a Sequence*

```http
POST /api/journeys/trigger HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience" : {
        "segment": "<segment-id>"
    },
    "triggering_id" : "1fd202ca-9deb-4372-b052-dff0516f9518",
    "entrance_id" : "product_123",
    "global_attributes" : {
        "product_name": "widget"
    }
}

```

```http
HTTP/1.1 200 OK
Content-Length: 11
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

```

---

## Exit in-flight users from a Sequence {#exitjourneys}

Exits in-flight users from a [Sequence](/docs/guides/messaging/messages/sequences/about/) identified by `triggering_id`.  Specify an `entrance_id` to exit only users from that specific entrance, or omit it to exit users that entered without an `entrance_id`.  This is a potentially long-running, asynchronous operation.

[Jump to examples ↓](#exitjourneys-examples)

### `POST /api/journeys/exit`

**Security:**

- [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-oauth2Token): jny

**Request body**

**Content-Type:** `application/json`

- **`entrance_id`** `string`

  Identifies a specific entrance for exit. If provided, only users that entered with this `entrance_id` are exited.  If omitted, only users that entered without an `entrance_id` are exited.

  Min length: 1, Max length: 64

- **`triggering_id`** **REQUIRED**
  **One of:**

  - `string`

    Identifier of a Sequence's configured [API Entrance trigger](/docs/guides/messaging/messages/sequences/triggers/#api-entrance).

  - `array<string>`

**Responses**

**`200`** Returned if the exit request has successfully been sent.  This does not indicate that an existing Sequence successfully received the request.

Response body:

**Content-Type:** `application/vnd.urbanairship+json; version=3`

[OK response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#okresponseobject)

**`400`** There was a parsing or validation error in the request. Bad Request errors typically include `path` and `location` in the response to help you find the cause of the error.

Response body:

**Content-Type:** `application/json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing.

Response body:

**Content-Type:** `text/plain`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`403`** Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

Response body:

**Content-Type:** `application/json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`429`** Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.

Response body:

**Content-Type:** `application/json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**Examples**

*Example exit in-flight users from a Sequence*

```http
POST /api/journeys/exit HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "triggering_id" :"1fd202ca-9deb-4372-b052-dff0516f9518",
    "entrance_id" : "product_123"
}

```

```http
HTTP/1.1 200 OK
Content-Length: 11
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}`

```

---