Journeys

Manage audience entry and exit for Sequences using the /api/journeys endpoints:

Enter or exit users from a Sequence can be used for either direction.
Exit users from a Sequence is exclusively for removing users already entered into the Sequence, and supports asynchronous bulk removal.

Enter or exit users from a Sequence

Enters or exits the specified audience from a Sequence, based on its configured API Entrance trigger or API Exit event identified by triggering_id. If multiple Sequences share the same triggering_id, one call affects all of them. For an API Entrance trigger, use entrance_id to run multiple concurrent, independent instances of the same Sequence for the same users without overwriting earlier entries. To exit a specific user directly, provide an audience selector that identifies just them, along with the triggering_id of a configured API Exit event.

Jump to examples ↓

POST /api/journeys/trigger

Security:

OAuth 2.0 : Journeys (jny)

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- audience object<Audience selector (max 1000)>REQUIRED
  An audience selector forms the expression that determines the set of channels to target.
- entrance_id string
  A unique identifier for differentiating entries. For an API Entrance trigger, use a different entrance_id on each call to create concurrent, independent entries for the same user without overwriting earlier ones. For an API Exit event, entrance_id identifies which users to exit, based on their entrance. When omitted, users who entered without an entrance_id exit the Sequence, and users with an entrance_id remain.
  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: map[category:mens shoes]
- triggering_id REQUIRED
  One of
  - string
    Identifier of a Sequence’s configured API Entrance trigger or API Exit event.
  - array<string>
    Min items: 1, Max items: 10

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
  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.
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
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
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
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
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
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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/1.1 200 OK
Content-Length: 11
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

from urbanairship import OAuthClient, Journeys, segment

client = OAuthClient(
    key="<app key>",
    client_id="<client_id>",
    private_key="<private_key>"
)

journeys = Journeys(client)
response = journeys.trigger(
    audience=segment("<segment-id>"),
    triggering_id="1fd202ca-9deb-4372-b052-dff0516f9518",
    entrance_id="product_123",
    global_attributes={"product_name": "widget"}
)

print(response)

Exit users from a Sequence

Exits in-flight users from a Sequence using its configured API Exit event identified by triggering_id. Specify an entrance_id to exit only users that entered with that specific entrance, or omit it to exit users that entered without one. Unlike Enter or exit users from a Sequence, this endpoint does not accept an audience and is a potentially long-running, asynchronous operation.

Jump to examples ↓

POST /api/journeys/exit

Security:

OAuth 2.0 : Journeys (jny)

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- 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 or API Exit event.
  - array<string>
    Min items: 1, Max items: 10

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
  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.
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
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
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
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
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
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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/1.1 200 OK
Content-Length: 11
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

from urbanairship import OAuthClient, Journeys

client = OAuthClient(
    key="<app key>",
    client_id="<client_id>",
    private_key="<private_key>"
)

journeys = Journeys(client)
response = journeys.exit(
    triggering_id="1fd202ca-9deb-4372-b052-dff0516f9518",
    entrance_id="product_123"
)

print(response)