Journeys

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

Enter or exit a Sequence

Enters an audience segment into a Sequence 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 ↓

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 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: map[category:mens shoes]
- triggering_id REQUIRED
  One of
  - string
    Identifier of a Sequence’s configured API Entrance trigger.
  - 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
}

Exit in-flight users from a Sequence

Exits in-flight users from a Sequence 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 ↓

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.
  - 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
}`