Airship API

Airship’s REST APIs for messaging, content personalization and audience management.

Libraries

Airship maintains open source server libraries to support your integrations with our APIs in multiple languages. Click below for library documentation.

Introduction

Airship provides a number of REST API endpoints collectively known as the Airship API Version 3, in support of our messaging product lines and related features. Version 3 is the current and only supported version of the Airship API.

API Request Format

All API requests are HTTP requests. For all requests with a body, the body may be in JSON  format or other formats like CSV as specified for the endpoint. The proper Content-Type for JSON is application/json and the proper content type for CSV is text/csv.

Date-Time Format

All date-time values are represented as a string according to ISO 8601  in UTC.

  • The string must be in the format YYYY-MM-dd['T']hh:mm:ss['Z'] where the T can be replaced by a space and the Z is optional.
  • A T separator is preferred but not required. It will be included in all date-time values generated by the API. For example:
    • 2023-11-13T09:42:30Z
    • 2023-11-13T09:42:30
    • 2023-11-13 09:42:30Z
    • 2023-11-13 09:42:30
  • A trailing time zone identifier or offset should not be included.
  • UTC is implicit.

Color Format

All color values are represented by a string format reminiscent of CSS color values used for web programming. The format is #rrggbb, a literal # character followed by 6 hexadecimal digits representing 3 values in the range 00 to FF. The values are red, green, and blue color components.

API Response Format

All API responses are HTTP responses, making use of appropriate HTTP response codes. When a body is present, it SHALL be in JSON  format, except in certain cases where reporting data MAY be returned in CSV format. The body of all JSON responses SHALL consist of a single JSON object, which SHALL contain a boolean ok attribute indicating overall success or failure. When a request results in a return value containing multiple entities, they SHALL be contained in an array-valued attribute, the name of which MAY vary by endpoint. For example, /api/tag will return a list of tags in the tags attribute, while /api/schedules will return a list of schedules in the schedules attribute. The name of the response object attribute containing the list of returned entities SHALL be contained in the Data-Attribute HTTP header.

Operation ID

All API calls that create or modify resources, or cause side effects, SHALL generate an operation ID. An operation ID is an opaque unique string that identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs. For example, the batch push API call can be used to send multiple pushes in one call. Each push has a unique push ID, but they will all share a common operation ID. This enables roll-ups of multiple related operations (such as push to local time or push to language) and better end-to-end tracing in the push pipeline. Operation IDs are returned in the JSON body of the response, in the operation_id attribute of the root response object. An operation ID will be generated even for error responses.

Response Codes

The API makes use of standard HTTP response codes, with standard HTTP semantics. Response codes in the 200 range indicate success. Codes in the 400 range indicate errors of a correctable nature. Codes in the 500 range indicate system errors.

This table lists general response definitions. Refer to the actual response definition per endpoint.

Response codeDescription
200 OKThe payload was accepted.
201 CreatedAn API request to create a new entity or entities was successful, and the entities were created.
202 AcceptedAn API request was successfully accepted into a processing queue to be processed later.
204 No ContentAn entity was successfully deleted.
400 Bad RequestParsing or validating the request failed.
401 UnauthorizedAuthentication information (the app key and secret) was either incorrect or missing.
403 ForbiddenAuthentication was correct, but the user does not have permission to access the requested API. This can happen if a feature is not included in the user’s Airship plan.
404 Not FoundA request was made for a non-existent entity.
405 Method Not AllowedA request was made using an HTTP method not supported by the endpoint. For example, sending a DELETE to /api/schedules.
406 UnacceptableThe client requested a version of the API that cannot be satisfied, because no compatible version is currently deployed.
409 ConflictAn entity could not be updated due to state conflict.
429 Too Many RequestsA request was denied because the app made too many requests to an API in a short period of time.

Validation

All requests must be validated. Proper validation at the API level can prevent invalid pushes from using resources in our delivery pipeline and educate API users about their own mistakes without involving Support. In the event of an error processing the request, the response body will contain one or more error objects. Parsing errors, arising from syntactically invalid JSON, should return an HTTP 400 Bad Request response. Semantic errors, arising from requests that are syntactically valid but otherwise malformed (for example, missing required fields), should return an HTTP 400 response, with a JSON body indicating details about the validation failure.

Some examples of specific validation cases that cause pushes to be rejected with an HTTP 400 error:

  • Invalid attributes — Any additional JSON keys that are not explicitly allowed by the spec will result in an HTTP 400 error, except where arbitrary keys are explicitly allowed (for example, the extra sections of a push payload).
  • Unconfigured open platform — Any open platform specified in the device_types array must be configured and active for the appKey. If the open platform is not configured, we will return an HTTP 400.
  • Missing payload — A push that specifies delivery to a platform but does not supply a payload for that platform is invalid.
  • Device identifier/restriction mismatch — A push that includes a device identifier in the audience selection but does not include the corresponding platform in the device_types specifier is invalid.
  • Schedule times — Requests to schedule pushes for times that have already passed will return an HTTP 400 response. However, requests to schedule local time pushes for a time that has elapsed in a local time zone will be accepted.
  • Unsupported platform feature — A push that includes features not supported on all platforms must explicitly target the supported platforms. Location is the only feature not supported across all platforms. This includes location expressions in predefined segments. Location pushes must specify device_types : [ ios, android ], or either iOS or Android explicitly.

Pagination

Some resource collections, such as tags and segments, may have a very large number of items, necessitating iterating through them in chunks (or pages) if an API consumer wishes to retrieve them all.

Request Parameters

There are two methods for pagination results:

  • start and limit
  • page and page_size

Using a non-unique identifier for the start parameter is unsound and will not paginate correctly. For endpoints that support sorting, if sorting is applied to a non-unique field, a secondary sort on a unique field must be used internally to ensure stable pagination results.

  • start — Optional string or integer. Identifies the starting element for paginating results. It can be either a unique string identifier or a zero-based offset, depending on the API.
  • limit — Optional integer. The maximum number of elements to return.
  • page — Optional integer. Specifies which page to retrieve, starting with 1.
  • page_size — Optional integer. The number of elements to return per page. The last page may have fewer elements.
  • sort — Optional string. The name of the field to sort results by. This is not necessarily supported by all endpoints.
  • order — Optional asc or desc. If the sort parameter is available, this parameter may be used to specify the direction of the sort as ascending or descending.

Link Header

Collections of entities SHALL be paginated by specifying a start point and a limit on the number of returned items as parameters of the request. The response SHALL include the requested items and a link to the next page of results. A link to the previous page MAY also be included if the underlying service supports it. For example, the Segments API supports previous page links. The links SHALL be provided in the Link HTTP header, as per RFC 5988 Web Linking , using the relations next and prev.

Count and Total

The number of items in the response SHALL be returned in the custom HTTP header Count, as well as in the "count" field of the response object. The total number of items in the collection MAY be returned in the custom HTTP header Total-Count, as well as in the "total_count" field of the response object, if the collection is countable and the total number of items is known.

Version Syntax

You must specify the version of the API you are using with the Accept HTTP header. If you do not specify an API version in the Accept header, a 406 is returned.

The content type used is a vendor-specific media type (see RFC 4288 Media Type Specifications and Registration Procedures ) and must be specified as: application/vnd.urbanairship+json; version=3.

Transport Layer Security

As of October 6, 2020, Airship supports only Transport Layer Security (TLS) versions 1.2 and 1.3 in our APIs, in accordance with PCI Security Standards Council  recommendations.

If your API integration uses TLS 1.0 or 1.1, contact our Support team  for assistance migrating to TLS 1.2 or 1.3.

Delivery Speed Options

The Airship push API is designed for extremely high throughput to ensure delivery to your entire audience as fast as possible. Depending on the size and/or complexity of your audience and the urgency of the message, you may find that you need to either slow down or speed up the delivery. To that end, we offer the following add-on services: Boost and Throttling.

If you are interested in enabling Boost or Throttling, contact Support .

Boost

Boost optimizes your segmented messages through parallel processing. Consider adding Boost if your notifications are extremely time-sensitive. Boost is a paid add-on. Contact your Account Manager for details.

Throttling

For less time-sensitive messages, our standard delivery speed may cause undue pressure on your internal systems or APIs, for example, when millions of users open your app at the same time. Use Throttling to tune delivery to a level that doesn’t put strain on those systems.

Complex segments can cause delays in processing

When creating segments or pushes with logical expressions, keep in mind that one or more NOT statements may cause latency when sending notifications, as NOT operations are inherently more expensive to perform than OR or AND operations. For example, tag_a AND NOT tag_b is basically the same speed as tag_a AND tag_b, but just NOT tag_b is likely to be slower than just tag_b.

Latency is more significant with larger audiences. We recommend using AND statements in place of NOT statements whenever possible as a best practice.

Device changes can take a few minutes

Some requests to register or unregister information about a device may take a few minutes to process before you are able to see the changes. Keep this in mind when performing PUT or POST requests.

Base URL

Select the domain associated with your Airship project.

Authentication

For additional information, including steps for creating bearer tokens and OAuth client credentials, see Airship API Security.

  • HTTP Authentication

    Basic Auth (App)
    Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your App Key and App Secret in appKey:appSecret format. For example, Basic YXBwX2tleTphcHBfc2VjcmV0.

  • HTTP Authentication

    Basic Auth (Master)
    Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your App Key and Master Secret in appKey:masterSecret format. For example, Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0.

  • HTTP Authentication

    Basic Auth (OAuth)
    Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your OAuth Client ID and Client Secret in client_id:client_secret format. For example, Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0. Used only for requesting OAuth tokens. See OAuth.

  • HTTP Authentication

    Bearer Token
    Authorization header containing the word Bearer followed by a space and a bearer token generated from the Airship dashboard. You can generate tokens for different roles. If your role does not grant you access to a feature, the endpoint will respond with a 401 status code. Tokens can be revoked at will.

  • OAuth Authentication

    OAuth 2.0
    Authorization header containing the word Bearer followed by a space and an OAuth 2.0 JWT bearer token provided by our authorization server. See OAuth.

OAuth

Request an OAuth 2.0 token using Basic Auth or an assertion.

Request token

Example request token with Basic Auth

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic <base64 encoded string of "client_id:client_secret">

grant_type=client_credentials&sub=app:JQIMcndxIHWy2QISpt1SpZ&scope=chn&scope=nu&ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "scope": "chn nu",
  "expires_in": 3600
}
OAuthCredentials oAuthCredentials = OAuthCredentials.newBuilder("<client_id>")
        .setClientSecret("<client_secret>")
        .setSub("<sub>")
        .setScopes(Arrays.asList("<scope1>","<scope2>","<...>"))
        .setIpAddresses(Arrays.asList("<IP1>","<IP2>",<...>))
        .build();

UrbanAirshipClient oAuthClient = UrbanAirshipClient.newBuilder()
        .setKey("yourAppKey")
        .setOAuthCredentials(oAuthCredentials)
        .build();
This operation is not currently supported.
This operation is not currently supported.

Example request token with assertion

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials&assertion=<encoded_jwt>
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "scope": "chn nu",
  "expires_in": 3600
}
OAuthCredentials oAuthCredentials = OAuthCredentials.newBuilder("<client_id>")
        .setAssertionJWT("<encoded_jwt>")
        .build();

UrbanAirshipClient oAuthClient = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setOAuthCredentials(oAuthCredentials)
        .build();
# The python OAuth client handles JWT creation 
# and token refresh automatically.
# Once instantiated, this can be used as any other Airship client.

airship_client = OAuthClient(
  client_id="<client_id>",
  private_key="<private_key>",
  key="<project_key>",
  scope=["<scopes>",],
  id_addr=["<ip list>",],
  timeout="<timeout seconds int>",
  retries="<attempts on failure int>"
)
require 'urbanairship'

UA = Urbanairship
app_key = '<application_key>'

oauth = UA::Oauth.new(
  client_id: '<client_id>',
  key: app_key,
  assertion_private_key: '<your_private_key>',
  scopes: ['psh', 'chn'], # Optional
  ip_addresses: ['23.74.131.15/22'], # Optional
  oauth_server: 'api.asnapieu.com' # Optional
)

airship = UA::Client.new(key: app_key, oauth: oauth)

POST /token

Request an OAuth access token with Basic Auth or an assertion. When making a request with an assertion, do not provide the Basic Auth header. See also OAuth 2.0 in the API Security documentation.

Use oauth2.asnapius.com for Airship’s North American cloud site and oauth2.asnapieu.com for Airship’s European cloud site when requesting an OAuth token.

Security:

header PARAMETERS

  • Content-Type : StringREQUIRED

    The request must have a Content-Type of application/x-www-form-urlencoded.

Request Body

  • Content-Type: application/x-www-form-urlencoded

    One of

    • Request token with Basic Auth : Object

      OBJECT PROPERTIES

      • grant_type : StringREQUIRED

        Possible values: client_credentials

      • ipaddr : String

        A list of CIDR representations of valid IP addresses to which the issued token is restricted. IP addresses can be sent as a URL-encoded, space-delimited list (example: ipaddr=24.20.40.0%2F24%202001%3A4860%3A4860%3A%3A8888%2F32) or as a list as expected in a query parameter form (example: ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32).

      • scope : OAuth Scope

        A list of scopes to which the issued token will be entitled. Scopes can be sent as URL-encoded, space-delimited list (example: scope=chn%20nu) or as a list as expected in a query parameter form (example: scope=chn&scope=nu).

      • sub : SubjectREQUIRED

        A space-delimited set of identifiers for which subjects a token is allowed. An app subject is required. Example: app:JQIMcndxIHWy2QISpt1SpZ.

    • Request token with assertion : Object

      OBJECT PROPERTIES

      • assertion : Assertion JWTREQUIRED

        An encoded JWT that contains the required headers and claims and is signed with the client credentials’ private key.

      • grant_type : StringREQUIRED

        Possible values: client_credentials

Responses

  • 200

    Returned on token request success.

    RESPONSE HEADERS

    • Cache-Control : String

      Possible values: no-store

    • Content-Type : String

      Possible values: application/json

    • Pragma : String

      Possible values: no-cache

    RESPONSE BODY

    • Content-Type: application/json

      Issued access token.

      OBJECT PROPERTIES

      • access_token : String

        The issued token that can be used for all endpoints as allowed by set scopes.

      • expires_in : Integer

        The number of seconds from the time the token is generated until it expires.

      • scope : OAuth Scope

        A space-delimited list of scopes of the issued token. There may be undocumented scopes in this list.

      • token_type : String

        The type of issued token.

        Possible values: Bearer

  • 400

    Token not generated.

    RESPONSE BODY

    • Content-Type: application/json

      Token request error.

      OBJECT PROPERTIES

      • error : StringREQUIRED

        Error code.

        Possible values: invalid_scope, invalid_request, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_client

      • error_description : String

        A plain-text description of the error.

  • 401

    Unauthorized.

    RESPONSE HEADERS

    • WWW-Authenticate : String

      The HTTP authentication methods that can be used to request an access token.

    RESPONSE BODY

    • Content-Type: application/json

      Authentication via the Authorization request header failed.

      OBJECT PROPERTIES

      • error : StringREQUIRED

        Error code.

        Possible values: invalid_client

      • error_description : String

        A plain-text description of the error.

  • 406

    Not acceptable.

    RESPONSE BODY

    • Content-Type: application/json

      Unsupported Accept header. The request only supports application/json, application/x-www-form-urlencoded, text/plain.

      OBJECT PROPERTIES

      • error : StringREQUIRED

        Error code.

        Possible values: invalid_request

      • error_description : String

        A plain-text description of the error.

Key verification

Example key verification

GET /verify/public_key/8817e96 HTTP/1.1
Host: oauth2.asnapius.com
Accept: text/plain
HTTP/1.1 200 OK
Content-Type: application/x-pem-file
Cache-Control: max-age=600, must-revalidate

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE7tcTz03ypC7PSPa73Cbgl7AbDDo+92eH
DWgjAi6vt1gmlHE35e+GhpcwbywBByOiooY+5bvfUHkc0aKy4R8VbBK0rYwlp8B+
fxyDr9Ye/oiUewMwwlp0z5AMPjgBUIKS
-----END PUBLIC KEY-----
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PublicKeyVerificationRequest request = PublicKeyVerificationRequest.newRequest("<kid>");
Response<String> response = client.execute(request);
require 'urbanairship'

UA = Urbanairship
app_key = '<application_key>'

oauth = UA::Oauth.new(
  client_id: '<client_id>',
  key: app_key,
  assertion_private_key: '<your_private_key>',
  scopes: ['psh', 'chn'], # Optional
  ip_addresses: ['23.74.131.15/22'], # Optional
  oauth_server: 'api.asnapieu.com' # Optional
)

public_key = oauth.verify_public_key('<key_id>')

GET /verify/public_key/{kid}

Retrieve the public key of a key ID. Use oauth2.asnapius.com for Airship’s North American cloud site and oauth2.asnapieu.com for Airship’s European cloud site when when verifying an OAuth public key.

path PARAMETERS

  • kid : StringREQUIRED

    The private key ID used to sign the token. Example: 8817e96

Responses

  • 200

    Returned on success with the public key for the given kid.

    RESPONSE HEADERS

    • Cache-Control : String

      The response contains a Cache-Control header which must be respected.

    RESPONSE BODY

    • Content-Type: application/x-pem-file

      The PEM-formatted public key.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/json

      The error includes as much information as possible to help you understand the reason for the failure.

Push

Send notifications or rich messages to supported channels, or validate JSON payloads.

Send a push

Example

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    "notification": {
        "alert": "Hello!"
    },
    "device_types": [ "ios" ]
}
HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078"
    ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
        .setNotification(Notifications.alert("Hello!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .build();

PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship(key="<app key>", secret="<master secret>", location="<us|eu>")

push = airship.create_push()
push.audience = ua.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
push.notification = ua.notification(alert='Hello!')
push.device_types = ua.device_types('ios')
push.send()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.or( UA.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5'))
push.notification = UA.notification(alert: 'Hello!')
push.device_types = UA.device_types(['ios'])
push.send_push

Example push with localizations

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "device_types": [ "ios", "android" ],
   "audience": {
      "tag": "needs_a_greeting",
      "group": "new_customer"
   },
   "notification": {
      "alert": "Hi!"
   },
   "localizations": [
       {
          "language": "de",
          "country": "AT",
          "notification": {
             "alert": "Grüss Gott"
          }
       },
       {
          "language": "de",
          "country": "DE",
          "notification": {
             "alert": "Guten Tag"
          }
       }
    ]
 }
HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078",
        "1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6",
        "939c3796-a755-413b-a36b-3026b1f92df8"
    ],
    "localized_ids": [
       "1a38a2ba-c174-d32f-d01b-481a5d241934"
    ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Localization localization = Localization.newBuilder()
        .setCountry("AT")
        .setLanguage("de")
        .setNotification(Notifications.alert("Grüss Gott"))
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.or(Selectors.tagWithGroup("needs_a_greeting", "new_customer")))
        .addLocalization(localization)
        .setNotification(Notifications.alert("Hi!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
        .build();

PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship(key="<app key>", secret="<master secret>", location="<us|eu>")

push = airship.create_push()

push.audience = ua.tag_group(tag_group="new_customer", tag="needs_a_greeting")
push.notification = ua.notification(alert='Hello!')
push.localizations = [
   ua.localization(country='at', language='de', notification=ua.notification(alert="Grüss Gott")),
   ua.localization(country='de', language='de', notification=ua.notification(alert="Guten Tag")),
]
push.device_types = ua.device_types('ios')
push.send()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag("needs_a_greeting", group:'new_customer')
push.notification = UA.notification(alert: 'Hi!')
push.device_types = UA.device_types(['ios'])
push.localizations = {
  "language": "de",
  "country": "AT",
  "notification": {
  "alert": "Grüss Gott"
  }
}
push.send_push

Example email being sent using Push API with template ID

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
        "tag": "needs_a_greeting",
        "group": "new_customer"
    },
    "device_types": [
        "email"
    ],
    "notification": {
      "email": {
        "message_type": "commercial",
        "reply_to": "no-reply@airship.com",
        "sender_address": "team@airship.com",
        "sender_name": "Airship",
        "template": {
            "template_id": "876624ff-0120-4364-bf02-dba3d0cb5b85"
        }
      }
    }
}
HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "be97b696-8d6b-4aec-ac50-c9cfc4be57d6",
    "push_ids": [
        "72ce9ade-aa71-4fbe-b960-246f1a2ca9ee"
    ],
    "message_ids": [],
    "content_urls": [],
    "localized_ids": []
}
This operation is not currently supported.
This operation is not currently supported.
This operation is not currently supported.

POST /api/push

Send a push notification to a specified audience. The body of the request must be a Push object or an array of push objects.

Security:

Request Body

A single push object or an array of push objects.

  • Content-Type: application/json

    One of

    • Push object

      A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

    • Array of Push Objects. : Array [Push object]

      Max items: 100 Min items: 1

Responses

  • 202

    The push notification has been accepted for processing. The response contains push_id, message_id, and/or content_url arrays based on the type of push.

    RESPONSE BODY

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

      A push response contains a list of identifiers for the notifications sent in the request.

      OBJECT PROPERTIES

      • content_urls : Array [String]

        An array of URLs where the push payload contains a landing page action. Max items: 100

      • localized_ids : Array [String]

        An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).

      • message_ids : Array [String]

        An array of message IDs, each uniquely identifying a Message Center message.

      • ok : Boolean

        Success.

      • operation_id : String

        A unique string identifying the operation, useful for reporting and troubleshooting. Format: uuid

      • push_ids : Array [String]

        An array of push IDs, each uniquely identifying a push. Max items: 100 Min items: 1

  • 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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    The request included a payload larger than the maximum size of 5 MiB.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 429

    There were too many similar requests in a short amount of time.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate push

Example

POST /api/push/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    "notification": {
        "alert": "Hello!"
    },
    "device_types": [ "ios" ]
}
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
        .setNotification(Notifications.alert("Hello!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .build();

PushRequest request = PushRequest.newRequest(payload).setValidateOnly(true);
Response<PushResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship(key="<app key>", secret="<master secret>", location="<us|eu>")

push = airship.create_push()
push.audience = ua.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
push.notification = ua.notification(alert='Hello!')
push.device_types = ua.device_types('ios')
push.validate()
This operation is not currently supported.

POST /api/push/validate

Accept the same range of payloads as POSTing to /api/push, but parse and validate only, without sending any pushes. The body of the request must be a Push Object or an array of push objects.

Security:

Request Body

A single push object or an array of push objects.

  • Content-Type: application/json

    One of

    • Push object

      A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

    • Array of Push Objects. : Array [Push object]

      Max items: 100 Min items: 1

Responses

  • 200

    The payload was valid.

    RESPONSE BODY

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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    The request included a payload larger than the maximum size of 5 MiB.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete multiple messages from inbox

Example

POST /api/user/messages/batch-delete HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "message_ids": [
        "drKa4OdxEeyhSwJC9TkdtQ",
        "W5ersOdxEeyvwAJCxz92iA"
    ]
}
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "deleted_message_ids": [
        "W5ersOdxEeyvwAJCxz92iA",
        "drKa4OdxEeyhSwJC9TkdtQ"
   ],
   "errors": []
}
HTTP/1.1 404 Not Found
Content-Type: application/vnd.urbanairship+json; version=3

{
    "deleted_message_ids": [],
    "errors": [
        {
            "message_id": "drKa4OdxEeyhSwJC9Tkdt1",
            "error_message": "Message not found.",
            "error_code": 40404
        },
        {
            "message_id": "W5ersOdxEeyvwAJCxz92i1",
            "error_message": "Message not found.",
            "error_code": 40404
        }
    ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
 List<String> arrayList = new ArrayList<>();
 arrayList.add("9dWD3LBIS5iZ51Y1GwOi4Q");
 arrayList.add("lsDtpTBJTN6KpQTwfOSNbw");

 InboxBatchDeleteRequest inboxBatchDeleteRequest = InboxBatchDeleteRequest.newRequest(arrayList);
 Response<InboxBatchDeleteResponse> response = client.execute(inboxBatchDeleteRequest);
This operation is not currently supported.
This operation is not currently supported.

POST /api/user/messages/batch-delete

Deletes multiple Message Center messages (up to 50 messages per request) completely, removing them from every user’s inbox. This is an asynchronous call; a success response means that the deletion has been queued for processing.

It is not possible to delete Message Center messages generated by an automation, a recurring message, or a Sequence.

Security:

Request Body

A request body containing an array of message IDs to be deleted.

  • Content-Type: application/json

    Object

    An array of message IDs, each uniquely identifying a Message Center message.

    OBJECT PROPERTIES

    • message_ids : Array [String]REQUIRED

      Array of Message IDs. Max items: 50 Min items: 1

Responses

  • 202

    The request has been accepted for processing.

    RESPONSE BODY

    • Content-Type: application/json

      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.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete message from inbox

Example

DELETE /api/user/messages/(push_id) HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

 InboxDeleteRequest request = InboxDeleteRequest.newRequest("68b2d71f-1c10-4592-bd96-2725aee0ae57");
 Response<GenericResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship(key="<app key>", secret="<master secret>", location="<us|eu>")

ua.Push.message_center_delete(airship=airship, 
                              push_id="941086fd-f7db-493b-a8a7-1f5a7dc6aae4")
This operation is not currently supported.

DELETE /api/user/messages/{push_id}

Delete a Message Center message completely, removing it from every user’s inbox. This is an asynchronous call; a success response means that the deletion has been queued for processing.

This delete call will work with either the message_id or the push_id of the accompanying push notification.

This endpoint will not work with a group_id from an automated message or a push to local time delivery. To delete a rich message that was part of an automated or local time delivery, you must use the relevant push_id from the operation.

 Note

For time-sensitive messages you should consider including an expiry time, as detailed in the In-App Message Object. Setting an expiry value will prevent you from having to manually remove messages.

Security:

path PARAMETERS

  • push_id : StringREQUIRED

    The push_id or message_id of the Rich Message you want to delete from users` inboxes.

    Format: uuid

Responses

  • 202

    The request has been accepted for processing.

    RESPONSE BODY

    • Content-Type: application/json

      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.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedules

Schedule notifications.

 Important

The API prohibits batch sizes of larger than 1,000 for scheduled pushes, and batches of larger than 100 for push to local time scheduled pushes.

List schedules

Example

GET /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Count: 2
Data-Attribute: schedules
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "count": 2,
    "total_count": 4,
    "next_page": "https://go.urbanairship.com/api/schedules/?start=5c69320c-3e91-5241-fad3-248269eed104&limit=2&order=asc",
    "schedules": [
        {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
            "schedule": { },
            "push": { }
        },
        {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed10A",
            "schedule": { },
            "push": { }
        }
    ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleListingRequest request = ScheduleListingRequest.newRequest();
Response<ListAllSchedulesResponse> response = client.execute(request);
List<SchedulePayloadResponse> schedules = response.getBody().get().getSchedules();
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')

for schedule in ua.ScheduledList(airship):
    print(
    schedule.name, schedule.url, schedule.push_ids,
    schedule.schedule, schedule.push
    )
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

scheduled_push_list = UA::ScheduledPushList.new(client: airship)
scheduled_push_list.each do |schedule|
    puts(schedule)
end

GET /api/schedules

List all existing schedules. Returns an array of schedule objects in the schedules attribute.

Security:

query PARAMETERS

  • start : String

    An optional string ID of the starting element for paginating results.

  • limit : Integer

    An optional integer as maximum number of elements to return. The default limit is 200 Schedule Objects per request. Set the limit to 200 or fewer in your API calls.

Responses

  • 200

    Returned on success, with the JSON representation of the scheduled pushes in the body of the response.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • count : Integer

      • next_page : String

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results. Format: url

      • ok : Boolean

        Success.

      • schedules : Array [Schedule object]

        An array of schedule objects.

      • total_count : Integer

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule a notification

Example

POST /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
  {
    "name": "Morning People",
    "schedule": {
        "scheduled_time": "2020-06-03T09:15:00"
    },
    "push": {
        "audience": { "tag": "earlyBirds" },
        "notification": { "alert": "Good Day Sunshine" },
        "device_types": [ "ios", "android" ]
    }
  },
  {
    "name": "Everybody Else",
    "schedule": {
        "best_time": {
          "send_date": "2020-06-03"
        }
    },
    "push": {
        "audience": { "tag": "normalPeople" },
        "notification": { "alert": "Stay Up Late" },
        "device_types": [ "ios", "android" ]
    }
  }
]
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("Morning People")
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-06-03T09:15:00Z"))
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Good Day Sunshine"))
                .setAudience(Selectors.tag("earlyBirds"))
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newRequest(schedulePayload);
Response<ScheduleResponse> response = client.execute(scheduleRequest);
import datetime
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
sched = airship.create_scheduled_push()
sched.name = 'Morning People'
sched.schedule = ua.scheduled_time(
  datetime.datetime.(2020, 6, 3, 9, 15, 0)
)
sched.push = airship.create_push()
sched.push.audience = ua.tag('earlyBirds')
sched.push.notification = ua.notification(alert='Good Day Sunshine')
sched.push.device_types = ['ios', 'android']
sched.send()

response = sched.send()
print ('Created schedule. URL:', response.schedule_url)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag('earlyBirds')
push.notification = UA.notification(alert: 'Morning People')
push.device_types = UA.device_types(['ios','android'])

schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "Morning People"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)

Example schedule with localizations

POST /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
  {
    "name": "Greetings",
    "schedule": {
        "best_time": {
          "send_date": "2020-11-15"
        }
    },
    "push": {
        "device_types": [
          "ios",
          "android"
        ],
        "audience": {
          "tag": "needs_a_greeting",
          "group": "new_customer"
        },
        "notification": {
          "alert": "Hi!"
        },
        "localizations": [
          {
              "language": "de",
              "country": "AT",
              "notification": {
                "alert": "Grüss Gott"
              }
          },
          {
              "language": "de",
              "country": "DE",
              "notification": {
                "alert": "Guten Tag"
              }
          }
        ]
    }
  }
]
HTTP/1.1 201 Created
Data-Attribute: schedule_urls
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
   "schedule_urls": [
        "https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
        "https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
    ],
    "schedule_ids": [
        "eac2ace6-349a-41a2-b874-5496d7bf0100",
        "6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
    ],
   "schedules": [
      {
         "url": "https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
         "schedule": {
            "scheduled_time": "2020-06-03T09:15:00"
         },
         "name": "Morning People",
         "push": {
            "audience": { "tag": "earlyBirds" },
            "notification": { "alert": "Good Day Sunshine" },
            "device_types": [ "ios", "android" ]
         },
         "push_ids": [ "83046227-9b06-4114-9f23-0df349792bbd" ]
      }
      {
          "url": "https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e",
          "schedule": {
            "best_time": {
              "send_date": "2020-06-03"
            }
          },
          "name": "Everybody Else",
          "push": {
            "audience": { "tag": "normalPeople" },
            "notification": { "alert": "Stay Up Late" },
            "device_types": [ "ios", "android" ]
         },
         "push_ids": [ "8438e81-bb31-82a9-5feb-e7fd5b21ca7e" ]
      }
   ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Localization one = Localization.newBuilder()
        .setCountry("AT")
        .setLanguage("de")
        .setNotification(Notifications.alert("Grüss Gott"))
        .build();

Localization two = Localization.newBuilder()
        .setCountry("DE")
        .setLanguage("de")
        .setNotification(Notifications.alert("Guten Tag"))
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("Greetings")
        .setSchedule(Schedule.newBuilder()
                .setBestTime(BestTime.newBuilder()
                        .setSendDate(DateTime.parse("2020-11-15T00:00:00Z"))
                        .build())
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Hi!"))
                .setAudience(Selectors.tagWithGroup("needs_a_greeting", "new_customer"))
                .addLocalization(one)
                .addLocalization(two)
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newRequest(schedulePayload);
Response<ScheduleResponse> response = client.execute(scheduleRequest);
import datetime
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

sched = airship.create_scheduled_push()
sched.name = 'Greetings'
sched.schedule = ua.best_time(datetime.datetime(2020, 11, 15))

sched.push = airship.create_push()
sched.push.audience = ua.tag_group(tag_group="new_customer", tag="needs_a_greeting")
sched.push.notification = ua.notification(alert='Good Day!')
sched.push.device_types = ['ios', 'android']
sched.push.localizations = [
    ua.localization(country='at', language='de', notification=ua.notification(alert="Grüss Gott")),
    ua.localization(country='de', language='de', notification=ua.notification(alert="Guten Tag")),
 ]

response = sched.send()
print ('Created schedule. URL:', response.schedule_url)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag('needs_a_greeting', group:'new_customer')
push.notification = UA.notification(alert: 'Hi!')
push.device_types = UA.device_types(['ios', 'android'])
push.localizations = {
  "language": "de",
  "country": "AT",
  "notification": {
  "alert": "Grüss Gott"
  }
}

schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "Greetings"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)

POST /api/schedules

Scheduled notifications are created by POSTing to the schedule URI. The body of the request must be one of a single schedule object or an array of one or more schedule objects.

Security:

Request Body

A single schedule object or an array of schedule objects. For Local Time Delivery, include no more than 100 Schedule Objects in your batch request.

  • Content-Type: application/json

    One of

    • Array [Schedule object]

      Max items: 1000

    • Schedule object

      A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

Responses

  • 201

    The response body will contain an array of response objects with the created resource URIs.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : Boolean

        Success.

      • operation_id : String

        A unique string which identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs. Format: uuid

      • schedule_ids : Array [String]

        An array of schedule IDs, each string uniquely identifying a schedule. Max items: 100 Min items: 1

      • schedule_urls : Array [String]

        An array of schedule URLs. Max items: 100

      • schedules : Array [Schedule object]

        An array of schedule objects.

  • 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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    The number of schedules in the array exceeded the maximum amount (error_code 41301). The request included a payload larger than the maximum size of 5 MiB (error_code 41307).

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List a specific schedule

Example

GET /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "name": "I would like to subscribe to your newsletter",
   "schedule": {
      "scheduled_time": "2020-04-01T18:45:30"
   },
   "push": {
      "audience": {
         "tag": [
            "intriguing",
            "ideas"                       ]
      },
      "notification": {
         "alert": "Check your inbox!"
      },
      "device_types": [ "ios", "android" ]
   }
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleListingRequest request = ScheduleListingRequest.newRequest("5cde3564-ead8-9743-63af-821e12337812");
Response<ListAllSchedulesResponse> response = client.execute(request);
SchedulePayloadResponse schedule = response.getBody().get().getSchedules().get(0);
// Get the schedule's name
Optional<String> name = schedule.getName();
// Get the push IDs
Set<String> pushIds = schedule.getPushIds();
// Get the scheduled time
Schedule sched = schedule.getSchedule();
// Get the associated push payload
PushPayload payload = schedule.getPushPayload();
// Get the URL
Optional<String> url = schedule.getUrl();
This operation is not currently supported.
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

schedule = airship.create_scheduled_push
scheduled_push = UA::ScheduledPush.new(airship)
schedule_details = scheduled_push.list(schedule_id: '5cde3564-ead8-9743-63af-821e12337812')
puts(schedule_details)

GET /api/schedules/{schedule_id}

Fetch the current definition of a single schedule resource. Returns a single schedule object.

Security:

path PARAMETERS

  • schedule_id : StringREQUIRED

    The ID of a schedule.

Responses

  • 200

    Returned on success, with the JSON representation of the scheduled push in the body of the response.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update schedule

Example

PUT /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "name": "I would like to subscribe to your newsletter",
   "schedule": {
      "scheduled_time": "2020-04-01T18:45:30"
   },
   "push": {
      "audience": {
         "tag": [
            "intriguing",
            "ideas",
            "thought_leadership"
         ]
      },
      "notification": {
         "alert": "Check your inbox!"
      },
      "device_types": [ "ios", "android" ]
   }
}
HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "7c56d013-5599-d66d-6086-6205115d85e2",
    "schedule_urls": [ "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e" ],
    "schedules": [
        {
            "url": "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e",
            "schedule": {
                "scheduled_time": "2020-04-01T18:45:30"
            },
            "name": "I would like to subscribe to your newsletter",
            "push": {
                "audience": {"tag": ["intriguing", "ideas", "thought_leadership"] },
                "notification": {"alert": "Check your inbox!"},
                "device_types": [ "ios", "android" ]
            },
            "push_ids": [ "48fb8e8a-ee51-4e2a-9a47-9fab9b13d846" ]
        }
    ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("I would like to subscribe to your newsletter")
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-04-01T18:45:00Z"))
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Check your inbox!"))
                .setAudience(Selectors.tag("intriguing"))
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newUpdateRequest(schedulePayload, "5cde3564-ead8-9743-63af-821e12337812");
Response<ScheduleResponse> response = client.execute(scheduleRequest);
import datetime
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
schedule = ua.ScheduledPush.from_url(airship, 'https://go.urbanairship.com/api/schedules/5cde3564-ead8-9743-63af-821e12337812')

# change scheduled time to tomorrow
schedule.schedule = ua.scheduled_time(
    datetime.datetime.utcnow() + datetime.timedelta(days=1))
resp = schedule.update()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

schedule = airship.create_scheduled_push
schedule = UA::ScheduledPush.from_url(client: airship, url: 'https://go.urbanairship.com/api/schedules/5cde3564-ead8-9743-63af-821e12337812')
# change scheduled time to tomorrow
schedule.schedule = UA.scheduled_time(Time.now.utc + (60 * 60 * 24))
schedule.update

PUT /api/schedules/{schedule_id}

Update the state of a single schedule resource. The body must contain a single schedule object. A PUT cannot be used to create a new schedule; it can only be used to update an existing one. A push to local time schedule cannot be updated once it has begun sending pushes to a time zone.

Security:

path PARAMETERS

  • schedule_id : StringREQUIRED

    The ID of a schedule.

Request Body

A single schedule object.

  • Content-Type: application/json

    Schedule object

    A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

Responses

  • 200

    Returned if the scheduled push has been successfully updated.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : Boolean

        Success.

      • operation_id : String

        A unique string which identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs. Format: uuid

      • schedule_urls : Array [String]

        An array of schedule URLs. Max items: 100

      • schedules : Array [Schedule object]

        An array of schedule objects.

  • 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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 409

    Returned if the local time scheduled push is in progress.

  • 413

    The request included a payload larger than the maximum size of 5 MiB.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete schedule

Example

DELETE /api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 204 No Content
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleDeleteRequest request = ScheduleDeleteRequest.newRequest("b384ca54-0a1d-9cb3-2dfd-ae5964630e66");
Response<GenericResponse> response = client.execute(request);
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
schedule = ua.ScheduledPush.from_url(airship, 'https://go.urbanairship.com/api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66')

# Cancel schedule
schedule.cancel()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

schedule = airship.create_scheduled_push
schedule = UA::ScheduledPush.from_url(client: airship, url: 'https://go.urbanairship.com/api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66')
schedule.cancel

DELETE /api/schedules/{schedule_id}

Delete a schedule resource, which will result in no more pushes being sent. If the resource is successfully deleted, the response does not include a body.

Security:

path PARAMETERS

  • schedule_id : StringREQUIRED

    The ID of a schedule.

Responses

  • 204

    The delete operation was successful.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Pause a schedule

Example

POST /api/schedules/5cde3564-ead8-9743-63af-821e12337812/pause HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleStatusRequest pauseRequest = ScheduleStatusRequest.pauseScheduleRequest("68b2d71f-1c10-4592-bd96-2725aee0ae57");
Response<GenericResponse> pauseResponse = client.execute(pauseRequest);      
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

sched = ua.ScheduledPush(airship)
sched.url = "http://go.urbanairship/api/schedules/5cde3564-ead8-9743-63af-821e12337812"

sched.pause()
This operation is not currently supported.

POST /api/schedules/{schedule_id}/pause

Pause a recurring scheduled message, preventing Airship from sending messages on a recurring scheduled message interval. Use the /resume endpoint to resume a schedule. The pause operation cannot be completed for recurring schedules that have schedule end times in the past.

 Note

Paused schedules bear a "paused": true boolean.

Security:

path PARAMETERS

  • schedule_id : StringREQUIRED

    The ID of the schedule you want to pause.

Request Body

A pause request is empty.

  • Content-Type: application/json

    Object

Responses

  • 204

    The pause operation was successful.

  • 400

    Returned if the schedule end time for a recurring schedule is in the past.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 500

    Occurs if a schedule fails to pause. The error includes a list of failed_triggers, detailing the schedule triggers that caused this operation to fail.

    RESPONSE BODY

    • Content-Type: application/json

      OBJECT PROPERTIES

      • error : String

        A description of the error.

      • error_code : Integer

        An error code representing the HTTP status and a more specific Airship error, if known.

      • failed_triggers : Array [Object]

        ARRAY ITEM
        • OBJECT PROPERTIES

          • id : String

            The list of failed schedule triggers. Format: uuid

          • state : String

            The reason that the operation failed.

            Possible values: BLOCKED, FAILED

      • ok : Boolean

        If false, an error occurred.

Resume a schedule

Example

POST /api/schedules/5cde3564-ead8-9743-63af-821e12337812/resume HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleStatusRequest resumeRequest = ScheduleStatusRequest.resumeScheduleRequest("68b2d71f-1c10-4592-bd96-2725aee0ae57");
Response<GenericResponse> resumeResponse = client.execute(resumeRequest);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

sched = ua.ScheduledPush(airship)
sched.url = "http://go.urbanairship/api/schedules/5cde3564-ead8-9743-63af-821e12337812"

sched.resume()
This operation is not currently supported.

POST /api/schedules/{schedule_id}/resume

Resume a recurring schedule that you previously paused, beginning with the next scheduled interval. The resume operation cannot be completed for recurring schedules that have schedule end times in the past.

 Note

Paused schedules bear a "paused": true boolean.

Security:

path PARAMETERS

  • schedule_id : StringREQUIRED

    The ID of the schedule you want to resume.

Request Body

A resume request is empty.

  • Content-Type: application/json

    Object

Responses

  • 204

    The operation was successful.

  • 400

    Returned if the schedule end time is in the past.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 500

    Occurs if a schedule fails to resume. The error includes a list of failed_triggers, detailing the specific schedule IDs that caused the operation to fail.

    RESPONSE BODY

    • Content-Type: application/json

      OBJECT PROPERTIES

      • error : String

        A description of the error.

      • error_code : Integer

        An error code representing the HTTP status and a more specific Airship error, if known.

      • failed_triggers : Array [Object]

        ARRAY ITEM
        • OBJECT PROPERTIES

          • id : String

            The list of failed schedule triggers. Format: uuid

          • state : String

            The reason that the operation failed.

            Possible values: BLOCKED, FAILED

      • ok : Boolean

        If false, an error occurred.

Automation

Manage Automated notifications using the /api/pipelines endpoints.

 Note

In the dashboard UI, we refer to pipelines as Automation or Automated Messages.

List existing pipelines

Example

GET /api/pipelines/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "pipelines": [
      {
          "creation_time": "2020-03-20T18:37:23",
          "enabled": true,
          "immediate_trigger": {
            "tag_added": { "tag": "bought_shoes" }
          },
          "last_modified_time": "2020-03-20T19:35:12",
          "name": "Shoe buyers",
          "outcome": {
            "push": {
                "audience": "triggered",
                "device_types": [ "android" ],
                "notification": { "alert": "So you like shoes, huh?" }
            }
          },
          "status": "live",
          "uid": "3987f98s-89s3-cx98-8z89-89adjkl29zds",
          "url": "https://go.urbanairship.com/api/pipelines/3987f98s-89s3-cx98-8z89-89adjkl29zds"
      },
      {
          "..."
      }
    ]
}
This operation is not currently supported.
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')

for automation in ua.Automation(airship).list_automations():
  print(automation)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.limit = 5
automation.list_automations

GET /api/pipelines

List existing pipelines. Pipelines are ordered by creation_date from newest to oldest.

Security:

query PARAMETERS

  • limit : Integer

    The maximum number of results to return. This is effectively the page size for the response. No default limit. For maximum performance, set your limit between 25 and 100.

    Min: 1

  • enabled : Boolean

    If true, limits the listing to enabled pipelines ("enabled": true). If false or omitted, lists all pipelines, whether enabled is true or false.

  • offset : Integer

    The first result you want to return. This parameter assists in pagination.

Responses

  • 200

    Returned on success, with a JSON representation of pipelines matching your query parameters.

    RESPONSE BODY

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

      The response body for a pipelines request.

      OBJECT PROPERTIES

      • next_page : String

        An URI that points to the next page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a next page we omit the next page link.

      • ok : Boolean

        Success.

      • operation_id : String

        A unique string identifying a single API call. Format: uuid

      • pipeline_ids : Array [String]

        An array of pipeline IDs.

      • pipeline_urls : Array [String]

        An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.

      • pipelines : Array [Pipeline object]

        A list of pipeline objects.

      • prev_page : String

        An URI that points to the previous page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a previous page we omit the previous page link.

      • total_count : Integer

        The total count of pipelines.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create pipeline (automated message)

Example

POST /api/pipelines HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name":"The Darkest Pipeline",
    "enabled":true,
    "immediate_trigger":"first_open",
    "outcome":{
      "push":{
          "audience":"triggered",
          "device_types":[
            "ios",
            "android",
            "web"
          ],
          "notification":{
            "alert":"Cool goatee, Abed"
          }
      }
    },
    "timing":{
      "delay":{
          "seconds":7200
      },
      "schedule":{
          "type":"local",
          "miss_behavior":"wait",
          "dayparts":[
            {
                "days_of_week":[
                  "thursday"
                ],
                "allowed_times":[
                  {
                      "preferred":"21:30:00"
                  }
                ]
            }
          ]
      }
    }
}
HTTP/1.1 201 Created
Content-Length: 123
Data-Attribute: pipeline_urls
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
    "pipeline_urls": [
      "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
    ]
}
This operation is not currently supported.
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')

automation = ua.Automation(airship)
pipeline = ua.Pipeline(
    name='The Darkest Pipeline',
    enabled=True,
    immediate_trigger=['first_open'],
    outcome={
        'audience': 'triggered',
        'device_types': ua.device_types('ios', 'android', 'web'),
        'notification': ua.notification(alert='Cool goatee, Abed')
    },
    timing={
        delay': {'seconds': 7200},
        'schedule': {
            'type': 'local',
            'miss_behavior': 'wait',
            'dayparts': [{
                'days_of_week': ['thursday'],
                'allowed_times': [
                    {'preferred': '21:30:00'}
                ]
            }]
        }
    }
)
response = automation.create(pipeline.payload)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = "first_open"
pipeline.outcome = {
    "push": {
        "audience": "triggered",
        "device_types": ['ios','android','web'],
        "notification": {
            "alert": "Cool goatee, Abed"
        }
    }
}
automation = UA::Automation.new(client: airship)
automation.pipeline_object = pipeline.payload
details = automation.create_automation
puts(details)

POST /api/pipelines

Create one or more pipelines. You can provide a single pipeline object or an array of pipeline objects.

Security:

Request Body

A single pipeline object or an array of pipeline objects.

  • Content-Type: application/json

    One of

    • Pipeline object

      A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

    • Array [Pipeline object]

Responses

  • 201

    If creating more than one pipeline, pipeline URIs are returned in the same order as the pipeline objects in the request.

    RESPONSE BODY

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

      The response body for a create pipeline request.

      OBJECT PROPERTIES

      • ok : Boolean

        Success.

      • operation_id : String

        A unique string identifying a single API call. Format: uuid

      • pipeline_urls : Array [String]

        An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.

  • 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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 409

    The application has exceeded the maximum number of active or total pipelines. In order to increase pipeline maximum, contact Airship Support.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    The request included a payload larger than the maximum size of 5 MiB.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List pipelines constraints

Example

GET /api/pipelines/constraints/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "constraints" : [
        {
            "rate" : {
                "pushes" : 30,
                "lifetimes" : 1
            }
        },
        {
            "rate" : {
                "pushes" : 15,
                "days" : 3
            }
        },
        {
            "rate" : {
                "pushes" : 4,
                "hours" : 6
            }
        }
    ]
}
This operation is not currently supported.
This operation is not currently supported.
This operation is not currently supported.

GET /api/pipelines/constraints

Returns an array of cross-pipeline rate limit constraints. These are the rates that the combination of all pipelines for an app may not exceed.

Security:

Responses

  • 200

    Returns an array of cross-pipeline rate limit constraints.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • constraints : Array [Object]

        An array of rate objects determining the maximum number of messages each audience member can receive over a period of time.

        ARRAY ITEM

        • Rate limit constraint

          A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.

          OBJECT PROPERTIES

          • rate : Any

            A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.

            One of

            • Pushes/days constraint : Object

              Limits the number of pushes any individual audience member will receive from the pipeline over a number of days.

              OBJECT PROPERTIES

              • days : Integer

                An integer, specifying the time period in number of days. Max: 90

              • pushes : Integer

                An integer, specifying the maximum number of pushes to any individual audience member per time period.

            • Pushes/hours constraint : Object

              Limits the number of pushes any individual audience member will receive from the pipeline over a number of hours.

              OBJECT PROPERTIES

              • hours : Integer

                An integer, specifying the time period in number of hours. Max: 72

              • pushes : Integer

                An integer, specifying the maximum number of pushes to any individual audience member per time period.

            • Pushes/lifetime constraint : Object

              Limits the number of pushes any individual audience member will ever receive from the pipeline.

              OBJECT PROPERTIES

              • lifetimes : Integer

                An integer specifying a lifetime. Max: 1 Min: 1

              • pushes : Integer

                An integer, specifying the maximum number of pushes to any individual audience member per time period.

      • ok : Boolean

        Success.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update pipelines constraints

Example

PUT /api/pipelines/constraints/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "constraints" : [
        {
            "rate" : {
                "pushes" : 15,
                "days" : 3
            }
        },
        {
            "rate" : {
                "pushes" : 4,
                "hours" : 6
            }
        }
    ]
}
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}
This operation is not currently supported.
This operation is not currently supported.
This operation is not currently supported.

PUT /api/pipelines/constraints

Update the pipelines constraints.

Security:

Request Body

An array of no more than 5 cross-pipeline rate limit constraints.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES

    • constraints : Array [Object]

      An array of rate objects determining the maximum number of messages each audience member can receive over a period of time. Max items: 5

      ARRAY ITEM

      • Rate limit constraint

        A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.

        OBJECT PROPERTIES

        • rate : Any

          A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.

          One of

          • Pushes/days constraint : Object

            Limits the number of pushes any individual audience member will receive from the pipeline over a number of days.

            OBJECT PROPERTIES

            • days : Integer

              An integer, specifying the time period in number of days. Max: 90

            • pushes : Integer

              An integer, specifying the maximum number of pushes to any individual audience member per time period.

          • Pushes/hours constraint : Object

            Limits the number of pushes any individual audience member will receive from the pipeline over a number of hours.

            OBJECT PROPERTIES

            • hours : Integer

              An integer, specifying the time period in number of hours. Max: 72

            • pushes : Integer

              An integer, specifying the maximum number of pushes to any individual audience member per time period.

          • Pushes/lifetime constraint : Object

            Limits the number of pushes any individual audience member will ever receive from the pipeline.

            OBJECT PROPERTIES

            • lifetimes : Integer

              An integer specifying a lifetime. Max: 1 Min: 1

            • pushes : Integer

              An integer, specifying the maximum number of pushes to any individual audience member per time period.

    • ok : Boolean

      Success.

Responses

  • 200

    Returned if the constraints have been successfully updated.

    RESPONSE BODY

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

      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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List deleted pipelines

Example

GET /api/pipelines/deleted/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "pipelines": [
      {
          "deletion_time": "2020-03-31T20:54:45",
          "pipeline_id": "0sdicj23-fasc-4b2f-zxcv-0baf934f0d69"
      },
      {
          "..."
      }
    ]
}
This operation is not currently supported.
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
response = ua.Automation(airship).list_deleted_automations()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.start = 2020-11-23
automation.list_deleted_automations

GET /api/pipelines/deleted

Produces a list of all deleted pipelines starting with the most recently deleted entry.

Security:

query PARAMETERS

  • start : String

    The date-time of the starting element for paginating results.

    Format: date-time

  • limit : Integer

    The maximum number of elements to return.

Responses

  • 200

    Returns an array of deleted pipeline objects.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : Boolean

        Success.

      • pipelines : Array [Object]

        ARRAY ITEM
        • OBJECT PROPERTIES

          • deletion_time : String

            The date-time indicating when the pipeline was deleted. Format: date-time

          • pipeline_id : String

            The unique identifier for a pipeline. Format: uuid

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List filtered pipelines

GET /api/pipelines/filtered

Lists all pipelines, which fulfill the provided filter criteria. Returns a response container, which contains an array of pipeline objects in the pipelines attribute. The response container also provides total count and links to the next page next_page and previous page prev_page, if applicable. We also always apply a sort order. By default we apply an ascending sort order on the name name field, but we also support a sort order on the started date started_date field. Pagination is always applied, which means that the pipeline result list is not the complete list of pipelines if the total count is greater than the page limit.

Security:

query PARAMETERS

  • start : Integer

    Non-negative zero-based index of the starting element for paginating results. Default value 0.

    Min: 1

  • limit : Integer

    The maximum number of results to return. This is effectively the page size for the response.

    Min: 1

  • enabled : Boolean

    If true, limits the listing to enabled pipelines. If false or omitted, lists all pipelines, whether enabled is true or false.

  • started_date_mills : Integer

    Limits the listing to only pipelines that were started after the specified date in milliseconds.

    Format: int64

  • prefix : String

    Search term, which is used as a prefix search term.

  • triggers : String

    0 or more trigger types. The triggers filter limits the listing of pipelines by the specified trigger types. For example, if you specify REGION_EXITED and REGION_ENTERED, only pipelines that are associated with region entry and region exit triggers will be shown. If no trigger types are specified, no triggers filter will be applied and all pipelines will be listed.

    Possible values: TAG_ADDED, TAG_REMOVED, FIRST_REG, FIRST_OPT_IN, ACTIVITY, REGION_ENTERED, REGION_EXITED, CUSTOM_EVENT, SUBSCRIPTION_ADDED, SUBSCRIPTION_REMOVED

  • sort : String

    Specifies the field, which should be sorted. Two fields are supported: name and started_date. If you omit the sort parameter, the default value name is used. If you provide an unknown field name, we will default to the name field.

    Possible values: name, started_date

  • order : String

    Specifies the sort order as ascending (asc) or descending (desc). If you omit the order parameter, the default value asc is used.

    Possible values: asc, desc

Responses

  • 200

    Returned on success, with a JSON representation of pipelines matching your query parameters.

    RESPONSE BODY

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

      The response body for a pipelines request.

      OBJECT PROPERTIES

      • next_page : String

        An URI that points to the next page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a next page we omit the next page link.

      • ok : Boolean

        Success.

      • operation_id : String

        A unique string identifying a single API call. Format: uuid

      • pipeline_ids : Array [String]

        An array of pipeline IDs.

      • pipeline_urls : Array [String]

        An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.

      • pipelines : Array [Pipeline object]

        A list of pipeline objects.

      • prev_page : String

        An URI that points to the previous page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a previous page we omit the previous page link.

      • total_count : Integer

        The total count of pipelines.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List pipelines limits

Example

GET /api/pipelines/limits/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "limits" : {
        "total_limit" : 50,
        "active_limit" : 20,
        "total_count" : 23,
        "active_count" : 7
    }
}
This operation is not currently supported.
This operation is not currently supported.
This operation is not currently supported.

GET /api/pipelines/limits

Return the currently configured limits for number of total and active pipelines, as well as the total and active counts.

Security:

Responses

  • 200

    Returns a JSON dictionary in the limits attribute.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • limits : Object

        OBJECT PROPERTIES

        • active_count : Integer

          An integer indicating the number of pipelines created by the application which are currently enabled.

        • active_limit : Integer

          An integer indicating the total number of active pipelines that the app is allowed to have.

        • total_count : Integer

          An integer indicating the total number of pipelines that currently exist for the application, regardless of their enabled state.

        • total_limit : Integer

          An integer indicating the total number of pipelines that the app is allowed to have, regardless of their enabled state.

      • ok : Boolean

        Success.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate pipeline

Example

POST /api/pipelines/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name":"The Darkest Pipeline",
    "enabled":true,
    "immediate_trigger":"first_open",
    "outcome":{
      "push":{
          "audience":"triggered",
          "device_types":[
            "ios",
            "android"
          ],
          "notification":{
            "alert":"Cool goatee, Abed"
          }
      }
    },
    "timing":{
      "delay":{
          "seconds":7200
      },
      "schedule":{
          "type":"local",
          "miss_behavior":"wait",
          "dayparts":[
            {
                "days_of_week":[
                  "thursday"
                ],
                "allowed_times":[
                  {
                      "preferred":"21:30:00"
                  }
                ]
            }
          ]
      }
    }
}
HTTP/1.1 200 OK
Content-Length: 11
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}
This operation is not currently supported.
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')

automation = ua.Automation(airship)
pipeline = ua.Pipeline(
    name='The Darkest Pipeline',
    enabled=True,
    immediate_trigger=['first_open'],
    outcome={
        'audience': 'triggered',
        'device_types': ua.device_types('ios', 'android', 'web'),
        'notification': ua.notification(alert='Cool goatee, Abed')
    },
    timing={
        delay': {'seconds': 7200},
        'schedule': {
            'type': 'local',
            'miss_behavior': 'wait',
            'dayparts': [{
                'days_of_week': ['thursday'],
                'allowed_times': [
                    {'preferred': '21:30:00'}
                ]
            }]
        }
    }
)
response = automation.validate(pipeline.payload)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = "first_open"
pipeline.outcome = {
    "push": {
        "audience": "triggered",
        "device_types": ['ios','android','web'],
        "notification": {
            "alert": "Cool goatee, Abed"
        }
    }
}
automation = UA::Automation.new(client: airship)
automation.pipeline_object = pipeline.payload
automation.validate_automation

POST /api/pipelines/validate

This endpoint accepts the same range of payloads as a POST to /api/pipelines, but only parses and validates the payload, without creating the pipeline. The body of the request must be a single pipeline object or an array of pipeline objects.

Security:

Request Body

A single pipeline object or an array of pipeline objects.

  • Content-Type: application/json

    One of

    • Pipeline object

      A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

    • Array of push templates : Array [Pipeline object]

Responses

  • 200

    The payload was valid.

    RESPONSE BODY

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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    The request included a payload larger than the maximum size of 5 MiB.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Individual pipeline lookup

Example

GET /api/pipelines/4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "pipeline": {
      "creation_time": "2020-02-14T19:19:19",
      "enabled": true,
      "immediate_trigger": { "tag_added": "new_customer" },
      "last_modified_time": "2020-03-01T12:12:54",
      "name": "New customer",
      "outcome": {
          "push": {
            "audience": "triggered",
            "device_types": [ "ios", "android" ],
            "notification": { "alert": "Hello new customer!" }
          }
      },
      "status": "live",
      "uid": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
      "url": "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
    }
}
This operation is not currently supported.
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
response = ua.Automation(airship).lookup('4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4')
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.pipeline_id = '4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4'
automation.lookup_automation

GET /api/pipelines/{pipeline_id}

Fetch a single pipeline resource. Returns an array containing a single pipeline object in the pipeline attribute.

Security:

path PARAMETERS

  • pipeline_id : StringREQUIRED

    The pipeline you want to return or modify.

Responses

  • 200

    Returned on success, with the JSON representation of the pipeline in the body of the response.

    RESPONSE BODY

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

      The response body for a pipelines request.

      OBJECT PROPERTIES

      • next_page : String

        An URI that points to the next page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a next page we omit the next page link.

      • ok : Boolean

        Success.

      • operation_id : String

        A unique string identifying a single API call. Format: uuid

      • pipeline_ids : Array [String]

        An array of pipeline IDs.

      • pipeline_urls : Array [String]

        An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.

      • pipelines : Array [Pipeline object]

        A list of pipeline objects.

      • prev_page : String

        An URI that points to the previous page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a previous page we omit the previous page link.

      • total_count : Integer

        The total count of pipelines.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update pipeline

Example

PUT /api/pipelines/0f927674-918c-31ef-51ca-e96fdd234da4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json;

{
    "enabled": true,
    "immediate_trigger": {
      "tag_added": "new_customer"
    },
    "outcome": {
      "push": {
          "audience": "triggered",
          "device_types": [
            "ios"
          ],
          "notification": {
            "alert": "Hello new customer!"
          }
      }
    }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}
This operation is not currently supported.
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')

automation = ua.Automation(airship)
pipeline = ua.Pipeline(
    enabled=True,
    immediate_trigger={
        'tag_added': 'new_customer'
    },
    outcome={
        'audience': 'triggered',
        'device_types': ua.device_types('ios'),
        'notification': ua.notification(alert='Hello new customer!')
    }
)
response = automation.update(
    pipeline_id='0f927674-918c-31ef-51ca-e96fdd234da4',
    pipeline=pipeline.payload
)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = {
  "tag_added": {
     "tag": "new_customer",
     "group": "crm"
    }
}
pipeline.outcome = {
  "push": {
     "audience": "triggered",
     "device_types": ["ios"],
     "notification": {
         "alert": "Hello new customer!"
        }
    }
}
automation = UA::Automation.new(client: airship)
automation.pipeline_id = '0f927674-918c-31ef-51ca-e96fdd234da4'
automation.pipeline_object = pipeline.payload
automation.update_automation

PUT /api/pipelines/{pipeline_id}

Update the state of a single pipeline resource. You must include the complete payload from a POST response, with changes you want to make to the resource. You cannot provide a partial payload. If you omit optional fields during this operation that were already set for the pipeline, they will be nullified.

Security:

path PARAMETERS

  • pipeline_id : StringREQUIRED

    The pipeline you want to return or modify.

Request Body

A single pipeline object or an array of pipeline objects.

  • Content-Type: application/json

    Pipeline object

    A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

Responses

  • 200

    Returned if the pipeline has been successfully updated.

    RESPONSE BODY

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

      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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 409

    The application has exceeded the maximum number of active or total pipelines. In order to increase pipeline maximum, contact Airship Support.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 413

    The request included a payload larger than the maximum size of 5 MiB.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete pipeline

Example

DELETE /api/pipelines/0f927674-918c-31ef-51ca-e96fdd234da4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 204 No Content
This operation is not currently supported.
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
response = ua.Automation(airship).delete('0f927674-918c-31ef-51ca-e96fdd234da4')
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.pipeline_id = '0f927674-918c-31ef-51ca-e96fdd234da4'
automation.delete_automation

DELETE /api/pipelines/{pipeline_id}

Delete a pipeline.

Security:

path PARAMETERS

  • pipeline_id : StringREQUIRED

    The pipeline you want to return or modify.

Responses

  • 204

    Returned if the pipeline has been successfully deleted.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

A/B Tests

Create A/B Tests using the /api/experiments endpoint. An experiment or A/B test is a set of distinct push notification variants sent to subsets of an audience. You can create up to 26 notification variants and send each variant to an audience subset.

Experiment listing

Example

GET /api/experiments HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiments
Count: 2
Total-Count: 2
Content-Type: application/vnd.urbanairship+json; version=3

 {
   "ok" : "true",
   "count" : 2,
   "total_count" : 2,
   "experiments" : [{
     "name" : "Experiment 1",
     "control" : 0.33,
     "audience" : "all",
     "device_types": [ "ios", "android" ],
     "variants" : [{
       "push" : {
         "notification" : {
           "alert" : "message 1"
         }
       },
       "id" : 0,
     },
     {
       "push" : {
           "notification" : {
             "alert" : "message 2"
           }
       },
       "id" : 1,
     }],
     "id" : "b5bc3dd1-9ea4-4208-b5f1-9e7ac3fe0502",
     "created_at" : "2020-03-03T21:08:05",
     "push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
   }, {
     "name" : "Experiment 2",
     "description" : "The second experiment",
     "audience" : "all",
     "device_types": [ "ios", "android" ],
     "variants" : [{
       "push" : {
         "notification" : {
           "alert" : "message 1"
         }
       },
       "id" : 0,
     },
     {
       "push" : {
           "notification" : {
             "alert" : "message 2"
           }
       },
       "id" : 1,
     }],
     "id" : "e464aa7e-be40-4994-a290-1bbada7187d8",
     "created_at" : "2020-03-03T21:08:05",
     "push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
   }]
}
This operation is not currently supported.
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
ab_test = ua.ABTest(airship)
response = ab_test.list_experiments()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

ab_test = UA::AbTest.new(client: airship)
ab_test.limit = 5
ab_test.list_ab_test

GET /api/experiments

List experiments, sorted by created_at date-time from newest to oldest. Responses are paginated. Use optional limit and offset parameters to navigate results.

Security:

query PARAMETERS

  • limit : Integer

    Positive maximum number of elements to return per page. The default limit is 10 entries with a maximum of 100 entries.

    Max: 100 Min: 1

  • offset : Integer

    A zero-based integer offset into the result set. If you do not use an offset, results will begin with the most recently sent experiment. If offset is greater than the number of queryable experiments, an empty result will be returned.

Responses

  • 200

    Returned on success, with the JSON representation of the experiments in the body of the response.

    RESPONSE BODY

    • Content-Type: application/json

      OBJECT PROPERTIES

      • count : Integer

        The number of items returned in this page of results.

      • experiments : Array [Experiment object]

        Experiment objects sorted by either created_at from newest to oldest. The number of objects will never exceed the limit specified in the request.

      • next_page : String

        A relative URL leading to the next page of results. If there are no more results, next_page is absent.

      • ok : BooleanREQUIRED

        If true, the call was successful.

      • total_count : Integer

        The total number of results.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create experiment (A/B Test)

Example

POST /api/experiments HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name": "Experiment 1",
    "audience": {"tag": "earlyBirds"},
    "device_types": [ "ios", "android" ],
    "variants": [
        {
            "push": {
                "notification": {
                    "alert": "message 1"
                }
            }
        },
        {
            "push": {
                "notification": {
                    "alert": "message 2"
                }
            }
        }
    ]
}
HTTP/1.1 201 Created
Content-Length: 123
Location: https://go.urbanairship.com/api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a
Content-Type: application/vnd.urbanairship+json; version=3

  {
    "ok" : "true",
    "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4",
    "experiment_id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
    "push_id" : "7e13f060-594c-11e4-8ed6-0800200c9a66"
  }
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Schedule schedule = Schedule.newBuilder()
        .setScheduledTimestamp(DateTime.now().plusMinutes(5))
        .build();

Variant variantOne = Variant.newBuilder()
        .setPushPayload(VariantPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("message 1")
                .build()
        )
        .build())
        .setSchedule(schedule)
        .build();

Variant variantTwo = Variant.newBuilder()
        .setPushPayload(VariantPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("message 2")
                .build()
        )
        .build())
        .setSchedule(schedule)
        .build();

Experiment experiment = Experiment.newBuilder()
        .setName("Experiment 1")
        .setDescription("Testing description")
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
        .setAudience(Selectors.tag("earlyBirds"))
        .addVariant(variantOne)
        .addVariant(variantTwo)
        .build();

ExperimentRequest request = ExperimentRequest.newRequest(experiment);
Response<ExperimentResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
push_1 = airship.create_push()
push_1.notification = ua.notification(alert='message 1')
push_2 = airship.create_push()
push_2.notification = ua.notification(alert='message 2')
variants = [
    ua.Variant(push=push_1),
    ua.Variant(push=push_2)
]
experiment = ua.Experiment(
    audience=ua.tag('earlyBirds'),
    name='Experiment 1',
    device_types=ua.device_types('ios', 'android'),
    variants=variants
)
ab_test = ua.ABTest(airship=airship)
response = ab_test.create(experiment=experiment)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

variant_one = UA::Variant.new(client: airship)
variant_one.push = {
    "notification": {
        "alert": "message 1"
    }
}
variant_two = UA::Variant.new(client: airship)
variant_two.push = {
    "notification": {
        "alert": "message 2"
    }
}
experiment = UA::Experiment.new(client: airship)
experiment.name = 'Experiment 1'
experiment.description = 'Example experiment'
experiment.audience = UA.tag('earlyBirds')
experiment.device_types = ['ios','android']
experiment.variants << variant_one.payload
experiment.variants << variant_two.payload
ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_object = experiment.payload
ab_test.create_ab_test

POST /api/experiments

Create an experiment. The body of the request should consist of a single experiment object. The experiment is processed and sent immediately unless a schedule is present.

Security:

Request Body

  • Content-Type: application/json

    Experiment object

    An experiment object describes an A/B test, including the audience and variant portions.

Responses

  • 201

    The experiment was created.

    RESPONSE HEADERS

    • Location : String

      The newly created experiment.

      Format: uri

    RESPONSE BODY

    • Content-Type: application/json

      The response body for an experiment request.

      OBJECT PROPERTIES

      • experiment_id : String

        Unique identifier for an experiment. Format: uuid

      • ok : BooleanREQUIRED

        If true, the experiment was successfully created. If false, the experiment was not created.

      • operation_id : String

        A unique string that represents a single API call, used to identify the operation or side effects in reporting and troubleshooting logs. Format: uuid

      • push_id : String

        Unique identifier for a push. Format: uuid

  • 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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Scheduled experiment listing

Example

GET /api/experiments/scheduled HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiments
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": "true",
    "count": 2,
    "total_count": 2,
    "experiments": [
        {
            "id": "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
            "name": "Experiment 1",
            "audience": "all",
            "device_types": [ "ios", "android" ],
            "variants": [
                {
                    "id": 0,
                    "schedule": {
                        "scheduled_time": "2020-11-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 1"
                        }
                    }
                },
                {
                    "id": 1,
                    "schedule": {
                        "scheduled_time": "2020-11-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 2"
                        }
                    }
                }
            ]
        },
        {
            "id": "29705c10-5951-11e4-8ed6-0800200c9a66",
            "name": "Experiment 2",
            "audience": "all",
            "device_types": [ "ios", "android" ],
            "variants": [
                {
                    "id": 0,
                    "schedule": {
                        "scheduled_time": "2020-12-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 1"
                        }
                    }
                },
                {
                    "id": 1,
                    "schedule": {
                        "scheduled_time": "2020-12-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 2"
                        }
                    }
                }
            ]
        }
    ]
}
This operation is not currently supported.
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
ab_test = ua.ABTest(airship)
response = ab_test.list_scheduled_experiment()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

ab_test = UA::AbTest.new(client: airship)
ab_test.list_scheduled_ab_test

GET /api/experiments/scheduled

List scheduled experiments in order, from closest to the current date-time to farthest (i.e., the experiments scheduled to occur soonest will appear at the top of the list). Responses are paginated, using optional limit and offset parameters.

Security:

query PARAMETERS

  • limit : Integer

    Positive maximum number of elements to return per page. The default limit is 10 entries with a maximum of 100 entries.

    Max: 100 Min: 1

  • offset : Integer

    A zero-based integer offset into the result set. If you do not use an offset, results will begin with experiment scheduled to begin at the soonest date-time. If the offset is greater than the number of queryable experiments, the result set will be empty.

Responses

  • 200

    Returned on success, with the JSON representation of the experiments in the body of the response.

    RESPONSE BODY

    • Content-Type: application/json

      OBJECT PROPERTIES

      • count : Integer

        The number of items in this page of results.

      • experiments : Array [Experiment object]

        Experiments listed by scheduled_time in ascending time order. The number of objects will never exceed the limit specified in the request.

      • next_page : String

        A relative URL leading to the next page of results. If there are no more results, next_page is absent.

      • ok : BooleanREQUIRED

        If true, the operation completed successfully and returns an expected result set.

      • total_count : Integer

        The total number of results.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete experiment

Example

DELETE /api/experiments/scheduled/0f7704e9-5dc0-4f7d-9964-e89055701b0a HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : "true",
  "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ExperimentDeleteRequest request = ExperimentDeleteRequest.newRequest("0f7704e9-5dc0-4f7d-9964-e89055701b0a");
Response<ExperimentResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

ab_test = ua.ABTest(airship)
ab_test.experiment_id = "0f7704e9-5dc0-4f7d-9964-e89055701b0a"

response = ab_test.delete()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_id = '0f7704e9-5dc0-4f7d-9964-e89055701b0a'
ab_test.delete_ab_test

DELETE /api/experiments/scheduled/{experiment_id}

Delete a scheduled experiment. You can only delete experiments before they start; attempting to delete an experiment that has already started or completed will return an HTTP 405 response (“Method not allowed”).

Security:

path PARAMETERS

  • experiment_id : StringREQUIRED

    The unique identifier of the experiment.

    Format: uuid

Responses

  • 200

    Returned if the experiment has been successfully deleted.

    RESPONSE BODY

    • Content-Type: application/json

      The response body for a pipeline’s deletion request.

      OBJECT PROPERTIES

      • ok : BooleanREQUIRED

        Success.

      • operation_id : String

        A unique string that represents a single API call, used to identify the operation or side effects in reporting and troubleshooting logs. Format: uuid

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 405

    Experiments can only be deleted before they start; afterwards, a HTTP 405 is returned.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate experiment

Example

POST /api/experiments/validate HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name": "Experiment 1",
    "audience": {"tag": "earlyBirds"},
    "device_types": [ "ios", "android" ],
    "variants": [
        {
            "push": {
                "notification": {
                    "alert": "message 1"
                }
            }
        },
        {
            "push": {
                "notification": {
                    "alert": "message 2"
                }
            }
        }
    ]
}
HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3

{
  "ok" : "true",
  "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Schedule schedule = Schedule.newBuilder()
        .setScheduledTimestamp(DateTime.now().plusMinutes(5))
        .build();

Variant variantOne = Variant.newBuilder()
        .setPushPayload(VariantPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("message 1")
                .build()
        )
        .build())
        .setSchedule(schedule)
        .build();

Variant variantTwo = Variant.newBuilder()
        .setPushPayload(VariantPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("message 2")
                .build()
        )
        .build())
        .setSchedule(schedule)
        .build();

Experiment experiment = Experiment.newBuilder()
        .setName("Experiment 1")
        .setDescription("Testing description")
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
        .setAudience(Selectors.tag("earlyBirds"))
        .addVariant(variantOne)
        .addVariant(variantTwo)
        .build();

ExperimentRequest request = ExperimentRequest.newRequest(experiment).setValidateOnly(true);
Response<ExperimentResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
push_1 = airship.create_push()
push_1.notification = ua.notification(alert='message 1')
push_2 = airship.create_push()
push_2.notification = ua.notification(alert='message 2')
variants = [
  ua.Variant(push=push_1),
  ua.Variant(push=push_2)
]
experiment = ua.Experiment(
  audience=ua.tag('earlyBirds'),
  name='Experiment 1',
  device_types=ua.device_types('ios', 'android'),
  variants=variants
)
ab_test = ua.ABTest(airship=airship)
response = ab_test.validate(experiment=experiment)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

variant_one = UA::Variant.new(client: airship)
variant_one.push = {
    "notification": {
        "alert": "message 1"
    }
}
variant_two = UA::Variant.new(client: airship)
variant_two.push = {
    "notification": {
        "alert": "message 2"
    }
}
experiment = UA::Experiment.new(client: airship)
experiment.name = 'Experiment 1'
experiment.description = 'Example experiment'
experiment.audience = UA.tag('earlyBirds')
experiment.device_types = ['ios','android']
experiment.variants << variant_one.payload
experiment.variants << variant_two.payload
ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_object = experiment.payload
ab_test.validate_ab_test

POST /api/experiments/validate

Accepts the same range of payloads as /api/experiments, but only parses and validates the payload without creating the experiment. This does the same amount of validation as the creation endpoint, including platform-specific validation, e.g., APNs byte limit checks. While this operation ensures the experiment is technically valid, it does not guarantee that a resulting push will succeed. An experiment may validate and still fail to be delivered. For example, you may have a valid experiment with no devices in your audience.

Security:

Request Body

A single experiment object.

  • Content-Type: application/json

    Experiment object

    An experiment object describes an A/B test, including the audience and variant portions.

Responses

  • 200

    The experiment is valid.

    RESPONSE BODY

    • Content-Type: application/json

      OBJECT PROPERTIES

      • ok : BooleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id : String

        A unique string that represents a single API call, used to identify the operation or side effects in reporting and troubleshooting logs. Format: uuid

  • 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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Experiment lookup

Example

GET /api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiment
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok" : "true",
   "experiment" : {
      "id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
      "push_id": "d00f07b0-594c-11e4-8ed6-0800200c9a66",
      "name" : "Experiment 1",
      "audience" : "all",
      "device_types": [ "ios", "android" ],
      "variants" : [{
            "push" : {
               "notification" : {
                  "alert" : "message 1"
               }
            },
            "id" : 0,
         },
         {
            "push" : {
               "notification" : {
               "alert" : "message 2"
            }
         },
         "id" : 1,
     }]
   }
}
This operation is not currently supported.
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
ab_test = ua.ABTest(airship)
response = ab_test.lookup(experiment_id='0f7704e9-5dc0-4f7d-9964-e89055701b0a')
require 'urbanairship'
UA = Urbanairship

airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
ab_test = UA::AbTest.new(client: airship)

ab_test.experiment_id = '0f7704e9-5dc0-4f7d-9964-e89055701b0a'
ab_test.lookup_ab_test

GET /api/experiments/{experiment_id}

Look up an experiment (A/B Test).

Security:

path PARAMETERS

  • experiment_id : StringREQUIRED

    The ID of the experiment you want to look up.

    Format: uuid

Responses

  • 200

    Returned on success, with the JSON representation of the experiment in the body of the response.

    RESPONSE BODY

    • Content-Type: application/json

      OBJECT PROPERTIES

      • experiment : Experiment object

        An experiment object describes an A/B test, including the audience and variant portions.

      • ok : BooleanREQUIRED

        If true, the operation completed successfully and returns a result set.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Personalization

Use the /templates API to create templates and push templatized notifications.

 Note

Consider the /templates API deprecated. You should instead create templates in the Airship dashboard and send using the /create-and-send or /pipelines APIs.

List templates

Example

GET /api/templates HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Data-Attribute: templates
Count: 1
Total-Count: 1
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "count": 1,
    "total_count": 1,
    "templates": [
        {
            "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "created_at": "2020-08-17T11:10:01Z",
            "modified_at": "2020-08-17T11:10:01Z",
            "last_used": null,
            "name": "Welcome Message",
            "description": "Our welcome message",
            "variables": [
                {
                    "key": "TITLE",
                    "name": "Title",
                    "description": "e.g., Mr, Ms, Dr, etc.",
                    "default_value": ""
                },
                {
                    "key": "FIRST_NAME",
                    "name": "First Name",
                    "description": "Given name",
                    "default_value": null
                },
                {
                    "key": "LAST_NAME",
                    "name": "Last Name",
                    "description": "Family name",
                    "default_value": null
                }
            ],
            "push": {
                "notification": {
                    "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
                }
            }
        }
    ],
    "next_page": null,
    "prev_page": null
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateListingRequest request = TemplateListingRequest.newRequest();
Response<TemplateListingRequest> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

for template in ua.TemplateList(airship):
  print (
      template.template_id, template.created_at, template.modified_at,
      template.last_used, template.name, template.description,
      template.variables, template.push
  )
This operation is not currently supported.

GET /api/templates

List all existing templates. Returns an array of template objects in the templates attribute.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

query PARAMETERS

  • page : Integer

    Specifies the desired page number. Defaults to 1.

  • page_size : Integer

    Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.

  • sort : String

    Specifies the name of the field you want to sort results by. Defaults to created_at.

    Possible values: created_at, modified_at, last_used

  • order : String

    Specifies the sort order as ascending (asc) or descending (desc). Defaults to asc.

    Possible values: asc, desc

Responses

  • 200

    Returned on success, with the JSON representation of the templates in the body of the response.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • count : Integer

        The number of templates in the current response; this is effectively the page size.

      • next_page : String

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results. Format: url

      • ok : BooleanREQUIRED

        Success.

      • prev_page : String

        Link to the previous page, if available. Format: url

      • templates : Array [Template object]

        An array of template objects.

      • total_count : Integer

        The total number of templates.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create template

Example

POST /api/templates HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "variables": [
        {
            "key": "TITLE",
            "name": "Title",
            "description": "e.g., Mr, Ms, Dr, etc.",
            "default_value": ""
        },
        {
            "key": "FIRST_NAME",
            "name": "First Name",
            "description": "Given name",
            "default_value": null
        },
        {
            "key": "LAST_NAME",
            "name": "Last Name",
            "description": "Family name",
            "default_value": null
        }
    ],
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
        }
    }
}
HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "operation_id" : "9ce808c8-7176-45dc-b79e-44aa74249a5a",
    "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161"
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateVariable titleVariable = TemplateVariable.newBuilder()
        .setKey("TITLE")
        .setName("Title")
        .setDescription("e.g., Mr, Ms, Dr, etc.")
        .setDefaultValue("")
        .build();

TemplateVariable firstNameVariable = TemplateVariable.newBuilder()
        .setKey("FIRST_NAME")
        .setName("First Name")
        .setDescription("Given name")
        .setDefaultValue(null)
        .build();

TemplateVariable lastNameVariable = TemplateVariable.newBuilder()
        .setKey("LAST_NAME")
        .setName("Last Name")
        .setDescription("Family name")
        .setDefaultValue("")
        .build();

PartialPushPayload partialPushPayload = PartialPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("Hello {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!")
                .build()
        )
        .build();

TemplateRequest request = TemplateRequest.newRequest()
        .setName("Welcome Message")
        .setDescription("Our welcome message")
        .addVariable(titleVariable)
        .addVariable(firstNameVariable)
        .addVariable(lastNameVariable)
        .setPush(partialPushPayload);

Response<TemplateResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
new_template = ua.Template(airship)
new_template.name = 'Welcome Message'
new_template.description = 'Our welcome message'
new_template.variables = [
    {
        'key': 'TITLE',
        'name': 'Title',
        'description': 'e.g., Mr., Ms., Dr., etc.',
        'default_value': ''
    },
    {
        'key': 'FIRST_NAME',
        'name': 'First Name',
        'description': 'Given name',
        'default_value': None
    },
    {
        'key': 'LAST_NAME',
        'name': 'Last Name',
        'description': 'Family name',
        'default_value': None
    }
]
new_template.push = {
    'notification': {
        'alert': 'Hello {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!'
    }
}
new_template.create()
print (new_template.template_id)  # To get the template ID for future use
This operation is not currently supported.

POST /api/templates

Create a new template.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

Request Body

A single template object.

  • Content-Type: application/json

    Template object

    A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.

Responses

  • 201

    The template was created.

    RESPONSE HEADERS

    • Location : String

      The uri for the template, used for later updates or sends.

      Format: uri

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : BooleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id : String

        A unique string identifying the operation, useful for reporting and troubleshooting. Format: uuid

      • template_id : String

        A unique string identifying the template, used to call the template for pushing and other operations. Format: uuid

  • 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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Push to template

Example

POST /api/templates/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "device_types": [ "ios" ],
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob",
            "LAST_NAME": "Smith",
            "TITLE": ""
        }
    }
}
HTTP/1.1 202 Accepted
Content-Length: 123
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "operation_id" : "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6"
    ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplatePushPayload payload = TemplatePushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .setMergeData(TemplateSelector.newBuilder()
                .setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
                .addSubstitution("FIRST_NAME", "Bob")
                .addSubstitution("LAST_NAME", "Smith")
                .addSubstitution("TITLE", "Mr.")
                .build())
        .build();

TemplatePushRequest request = TemplatePushRequest.newRequest()
        .addTemplatePushPayload(payload);

Response<TemplateResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
push = airship.create_template_push()
push.audience = ua.ios_channel('b8f9b663-0a3b-cf45-587a-be880946e881')
push.device_types = ua.device_types('ios')
push.merge_data = ua.merge_data(
    template_id='ef34a8d9-0ad7-491c-86b0-aea74da15161',
    substitutions={
        'FIRST_NAME': 'Bob',
        'LAST_NAME': 'Smith',
        'TITLE': ''
    }
)
response = push.send()
This operation is not currently supported.

POST /api/templates/push

Send a push notification based on a template to a list of devices. The body of the request must be a single push template payload or an array of one or more push template payloads.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

Request Body

A single push template payload or an array of push template payloads. Provide an override with any variable that has a null default value. For example, if you created a template with the variable FIRST_NAME, and that variable has null as a default value, you must provide a substitution for FIRST_NAME when pushing to that template.

  • Content-Type: application/json

    One of

    • Push template payload

      A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

    • Array of push templates : Array [Push template payload]

Responses

  • 202

    The push notification has been accepted for processing.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : BooleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id : String

        A unique string identifying the operation, useful for reporting and troubleshooting. Format: uuid

      • push_ids : Array [String]

        An array of the push IDs for this operation. Max items: 100 Min items: 1

  • 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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate a template

Example

POST /api/templates/push/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "device_types": [ "ios" ],
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob",
            "LAST_NAME": "Smith",
            "TITLE": ""
        }
    }
}
HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplatePushPayload payload = TemplatePushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .setMergeData(TemplateSelector.newBuilder()
                .setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
                .addSubstitution("FIRST_NAME", "Bob")
                .addSubstitution("LAST_NAME", "Smith")
                .addSubstitution("TITLE", "Mr.")
                .build())
        .build();

TemplatePushRequest request = TemplatePushRequest.newRequest()
        .addTemplatePushPayload(payload)
        .setValidateOnly(true);

Response<TemplateResponse> response = client.execute(request);
This operation is not currently supported.
This operation is not currently supported.

POST /api/templates/push/validate

This endpoint accepts the same range of payloads as /api/template/push, but only parses and validates the payload. It does not actually send a push.

Security:

Request Body

A single push template payload or an array of push template payloads.

  • Content-Type: application/json

    One of

    • Push template payload

      A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

    • Array [Push template payload]

Responses

  • 200

    The payload was valid.

    RESPONSE BODY

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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule a templated push

Example

POST /api/templates/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
    {
        "name": "Hello Bob",
        "schedule": {
           "scheduled_time": "2020-05-02T22:00:00Z"
        },
        "device_types": [ "ios" ],
        "audience": {
           "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
        },
        "merge_data": {
            "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "substitutions": {
                "FIRST_NAME": "Bob",
                "LAST_NAME": "Takahashi",
                "TITLE": null
            }
        }
    },
    {
        "name": "Hello Joe",
        "schedule": {
           "scheduled_time": "2020-05-05T18:00:00Z"
        },
        "device_types": [ "android" ],
        "audience": {
           "android_channel": "df6a6b50-9843-0304-d5a5-743f246a4946"
        },
        "merge_data": {
            "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "substitutions": {
                "FIRST_NAME": "Joe",
                "LAST_NAME": "Smith",
                "TITLE": "Sir"
            }
        }
    }
]
HTTP/1.1 202 Accepted
Content-Length: 123
Data-Attribute: schedule_urls
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "operation_id" : "efb18e92-9a60-6689-45c2-82fedab36399",
    "schedule_urls" : [
        "http://go.urbanairship/api/schedules/a0cef4f9-1fcd-47ef-b459-01f432b64043",
        "http://go.urbanairship/api/schedules/fe2dab5e-f837-4707-8d0c-0e8c589ef4cf"
    ],
    "schedule_ids" : [
        "a0cef4f9-1fcd-47ef-b459-01f432b64043",
        "fe2dab5e-f837-4707-8d0c-0e8c589ef4cf"
    ],
    "schedules" : [
        {
            "url" : "http://go.urbanairship/api/schedules/a0cef4f9-1fcd-47ef-b459-01f432b64043",
            "name": "Hello Joe",
            "schedule" : { "..." },
            "push" : { "..." },
            "push_ids": [ "6a5ecb9c-46ee-4af4-9ced-9308121afaf9" ]
        },
        {
            "url" : "http://go.urbanairship/api/schedules/fe2dab5e-f837-4707-8d0c-0e8c589ef4cf",
            "name": "Hello Bob",
            "schedule" : { "..." },
            "push" : { "..." },
            "push_ids": [ "5162bbf8-7de7-4040-a64d-e018b71f02f6" ]
        }
    ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateScheduledPushPayload payload = TemplateScheduledPushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .setMergeData(TemplateSelector.newBuilder()
                .setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
                .addSubstitution("FIRST_NAME", "Bob")
                .addSubstitution("LAST_NAME", "Takahashi")
                .addSubstitution("TITLE", "Dr.")
                .build())
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-05-05T18:00:00Z"))
                .build())
        .build();

TemplateScheduledPushRequest request = TemplateScheduledPushRequest.newRequest()
                                          .addTemplateScheduledPushPayload(payload);
Response<ScheduleResponse> response = client.execute(request);
This operation is not currently supported.
This operation is not currently supported.

POST /api/templates/schedules

Schedule a push notification based on a template to a list of devices. Like a standard template-based push, the body of the request includes one or more push template payloads along with a schedule object determining when the template-based push should be sent.

Security:

Request Body

An array of scheduled pushes.

  • Content-Type: application/json

    Array [Object]

    ARRAY ITEM

    • A scheduled push template object defines a push by overriding the variables defined in a specific template object and the schedule determining when the push should be sent. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.

      OBJECT PROPERTIES

      • audience : Audience selector (max 1000)REQUIRED

        The audience for the template.

      • campaigns : Campaigns object

        An object specifying custom campaign categories related to the notification.

      • device_types : Array [String]REQUIRED

        An array containing one or more strings identifying targeted platforms. Min items: 1

        ARRAY ITEM

        • Possible values: android, amazon, ios, web, sms, mms, email, open::open_platform_name

      • merge_data : ObjectREQUIRED

        A template selector describing the template ID and variable substitutions to use with it.

        OBJECT PROPERTIES

        • substitutions : Object

          An object containing overrides for your template’s variables. The key-value pairs in this object are the value of the key items defined in your template, and the values you want to substitute for the default_value of those keys.

        • template_id : StringREQUIRED

          Specifies the template to override. Format: uuid

      • name : String

        An optional name for the scheduled push operation.

      • schedule : Schedule specificationREQUIRED

        Determines when the push is sent.

Responses

  • 202

    The scheduled push has been accepted for processing.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : BooleanREQUIRED

        Success.

      • operation_id : String

        A unique string which identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs. Format: uuid

      • schedule_ids : Array [String]

        An array of schedule IDs. Max items: 100 Min items: 1

      • schedule_urls : Array [String]

        An array of schedule URLs. The URL for each schedule is the schedules endpoint, appended with the schedule_id of the schedule. Max items: 100

      • schedules : Array [Schedule object]

        An array of schedule objects.

  • 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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Look up a template

Example

GET /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Data-Attribute: template
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok" : true,
    "template": {
        "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "created_at": "2020-08-17T11:10:02Z",
        "modified_at": "2020-08-17T11:10:02Z",
        "last_used": null,
        "name": "Welcome Message",
        "description": "Our welcome message",
        "variables": [
            {
                "key": "TITLE",
                "name": "Title",
                "description": "e.g., Mr, Ms, Dr, etc.",
                "default_value": ""
            },
            {
                "key": "FIRST_NAME",
                "name": "First Name",
                "description": "Given name",
                "default_value": null
            },
            {
                "key": "LAST_NAME",
                "name": "Last Name",
                "description": "Family name",
                "default_value": null
            }
        ],
        "push": {
            "notification": {
                "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
            }
        }
    }
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateListingRequest request = TemplateListingRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161");
Response<TemplateListingResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
template = ua.Template(airship).lookup(template_id)
print (
    template.template_id, template.created_at, template.modified_at,
    template.last_used, template.name, template.description,
    template.variables, template.push
)
This operation is not currently supported.

GET /api/templates/{template_id}

Fetch the current definition of a single template.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

path PARAMETERS

  • template_id : StringREQUIRED

    A required string ID of the template.

    Format: uuid

Responses

  • 200

    Returned on success, with the JSON representation of the template in the body of the response.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : BooleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • template : Template object

        A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update template

Example

POST /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!"
        }
    }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PartialPushPayload partialPushPayload = PartialPushPayload.newBuilder()
        .setNotification(Notification.newBuilder()
                .setAlert("Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!")
                .build()
        )
        .build();

TemplateRequest request = TemplateRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161")
        .setName("Welcome Message")
        .setDescription("Our welcome message")
        .setPush(partialPushPayload);

Response<TemplateResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
updated_template = ua.Template(airship)
updated_template.push = {
    'notification': {
        'alert': 'Hi {{FIRST_NAME}} {{LAST_NAME}}!'
    }
}
response = updated_template.update(template_id)
This operation is not currently supported.

Alternatively, call the lookup function on your updated template:

import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
updated_template = ua.Template(airship).lookup(template_id)
updated_template.push = {
    'notification': {
        'alert': 'Greetings {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}!'
    }
}
response = updated_template.update()

POST /api/templates/{template_id}

Update a template. The request body is a partially-defined template object, containing the field(s) you want to change and their updated values.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

path PARAMETERS

  • template_id : StringREQUIRED

    A required string ID of the template.

    Format: uuid

Request Body

  • Content-Type: application/json

    Object

    A partially-defined template object. Provide only variables and push items that you want to update.

    OBJECT PROPERTIES

    • description : String

      The description of the template.

    • name : StringREQUIRED

      The name of the template.

    • push : Template push object

      A partial push object describing everything about a push notification, except for the audience and device_types keys (which are defined in the Push template payload) and the message key (which is incompatible with templates).

    • variables : Array [Template variables]

      An array of variable specifications.

Responses

  • 200

    Returned if the template has been successfully updated.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : BooleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id : String

        A unique string identifying the operation, useful for reporting and troubleshooting. Format: uuid

  • 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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete template

Example

DELETE /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "a6394ff8-8a65-4494-ad06-677eb8b7ad6a"
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

TemplateDeleteRequest request = TemplateDeleteRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161");
Response<TemplateResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'

# Delete via template lookup
response = ua.Template(airship).lookup(template_id).delete()

# OR, if you want to delete a template without fetching it from the API
response = ua.Template(airship).delete(template_id)
This operation is not currently supported.

DELETE /api/templates/{template_id}

Delete a template. If the template is successfully deleted, the response does not include a body.

 Note

This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.

Security:

path PARAMETERS

  • template_id : StringREQUIRED

    A required string ID of the template.

    Format: uuid

Responses

  • 200

    The template with given ID has been successfully deleted.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : BooleanREQUIRED

        If true, the operation completed successfully and returns an expected response.

      • operation_id : String

        A unique string identifying the operation, useful for reporting and troubleshooting. Format: uuid

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Regions

The Region API endpoints provide a listing and detail for all of your defined entry/exit regions, including custom shapes (polygons) and circles (point/radius).

Region listing

Example

GET /api/regions/?limit=100&start=100 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Data-Attribute: regions
Link: <https://go.urbanairship.com/api/regions?limit=100&start=100>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "next_page": "https://go.urbanairship.com/api/regions?limit=100&start=100",
   "count": 100,
   "regions": [
       {
           "region_id": "abe5deb3-01d0-436e-8c5d-94b6421a01e0",
           "name": "My Favorite Place",
           "created_at": "2020-06-09T12:34:56",
           "updated_at": "2020-06-09T12:34:56",
           "geofence": {
               "type": "POLYGON",
               "points": [
                   {
                       "latitude": 90.0,
                       "longitude": 120.0
                   },
                   {
                       "latitude": 45.0,
                       "longitude": 120.0
                   },
                   {
                       "latitude": 0.0,
                       "longitude": 0.0
                   }
               ]
           },
           "beacons": [
               {
                   "name": "entryway",
                   "id": "VLSHZAOEXOFCMLDVTKFQ"
               },
               {
                   "name": "Exhibit A",
                   "id": "ZAQYMNOZKRFCRPYEUCZI"
               }
           ],
           "attributes": {
               "store_name": "Tonali's Donuts"
           },
           "source_info": {
               "source": "GIMBAL",
               "region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
               "vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
           }
       }
   ]
}
This operation is not currently supported.
This operation is not currently supported.
This operation is not currently supported.

GET /api/regions

Get a paginated list regions. The result is an array of Region objects under the "regions" key.

Security:

query PARAMETERS

  • limit : Integer

    Determines the number of results per page. Defaults to 100, with a maximum of 1,000 regions per page. Setting a limit greater than 1,000 returns a 400 response.

    Max: 1000

  • start : Integer

    A zero-based integer offset into the ordered list of regions, useful for addressing pages directly.

Responses

  • 200

    Returns OK for success.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • count : Integer

        The total number of regions returned.

      • next_page : String

        There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results. Format: url

      • ok : Boolean

        Success.

      • regions : Array [Region object]

        An array of region objects.

  • 400

    Returned when limit is greater than 1,000.

    RESPONSE BODY

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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Region lookup

Example

GET /api/regions/7d4d9a5c-eff5-40f2-b648-4352c166e878 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Data-Attribute: region
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "region": {
        "region_id": "7dbd9a5c-eff5-40f2-b648-4352c1668878",
        "created_at": "2020-08-24T23:15:22.900",
        "updated_at": "2020-08-24T23:15:22.900",
        "name": "Alberta Park",
        "source_info": {
            "source": "GIMBAL",
            "region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
            "vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
        },
        "geofence": {
            "type": "CIRCLE",
            "center": {
                "latitude": 45.56447530000002,
                "longitude": -122.64461097354126
            },
            "radius": 200
        },
        "attributes": {
             "park_name": "alberta",
             "type": "park"
        }
    }
}
This operation is not currently supported.
This operation is not currently supported.
This operation is not currently supported.

GET /api/regions/{region_id}

Get details for a specific region.

Security:

path PARAMETERS

  • region_id : StringREQUIRED

    The region you want to lookup.

Responses

  • 200

    Returns OK for success.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : Boolean

        If true, indicates success.

      • region : Region object

        A Region object describes a geographical boundary or set of hardware identifiers and associated attributes that correspond to a physical location of relevance to the application or application owner.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Custom Events

User events that occur outside of your app can be submitted to Airship for inclusion in analytics reporting, as triggers for Automation, or for export via Connect. These events can take place on the web, e.g., your website, social media, or in your back office systems such as CRM or POS software. Any event that can be associated with a mobile app user can be submitted as an Airship Custom Event. The events that you submit are associated with channels and are available to use as Custom Event triggers.

Add Custom Events

Example

POST /api/custom-events HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <application key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
   {
      "occurred": "2020-05-02T02:31:22",
      "user": {
         "named_user_id": "hugh.manbeing"
      },
      "body": {
         "name": "purchased",
         "value": 239.85,
         "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a",
         "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
         "interaction_type": "url",
         "properties": {
            "description": "Sneaker purchase",
            "brand": "Victory Sneakers",
            "colors": [
             "red",
             "blue"
            ],
            "items": [
               {
                  "text": "New Line Sneakers",
                  "price": "$ 79.95"
               },
               {
                  "text": "Old Line Sneakers",
                  "price": "$ 79.95"
               },
               {
                  "text": "Blue Line Sneakers",
                  "price": "$ 79.95"
               }
            ],
            "name": "Hugh Manbeing",
            "userLocation": {
               "state": "CO",
               "zip": "80202"
            }
         },
         "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
      }
   }
]
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "operation_id": "8c61c0c4-95b0-45a6-bc38-733f7fcb8979"
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .setBearerToken("<bearer token>")
        .build();

CustomEventUser customEventUser = CustomEventUser.newBuilder()
        .setNamedUserId("hugh.manbeing")
        .build();

CustomEventPropertyValue customEventProperty = CustomEventPropertyValue.of("Victory Sneakers");

List<CustomEventPropertyValue> items = new ArrayList<>();
items.add(CustomEventPropertyValue.of("New Line Sneakers"));
items.add(CustomEventPropertyValue.of("Old Line Sneakers"));

DateTime occurred = new DateTime(2020, 05, 02, 02, 31, 22, DateTimeZone.UTC);

CustomEventBody customEventBody = CustomEventBody.newBuilder()
        .setName("purchased")
        .addPropertiesEntry("brand", customEventProperty)
        .addPropertiesEntry("items", CustomEventPropertyValue.of(items))
        .build();

CustomEventPayload customEventPayload = CustomEventPayload.newBuilder()
        .setCustomEventBody(customEventBody)
        .setCustomEventUser(customEventUser)
        .setOccurred(occurred)
        .build();

CustomEventRequest customEventRequest = CustomEventRequest.newRequest(customEventPayload);
Response<CustomEventResponse> response = client.execute(customEventRequest);
import datetime
import urbanairship as ua

airship = ua.Airship(key=<app_key>, token=<bearer_token>)

event = ua.CustomEvent(
   airship=airship,
   name='purchased', 
   user=ua.named_user("hugh.manbeing")
)

event.session_id = "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
event.occurred = datetime(2020, 5, 2, 2, 31, 22)
event.interaction_id = "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234"
event.interaction_type = "url"
event.value = 239.84
event.transaction = "886f53d4-3e0f-46d7-930e-c2792dac6e0a"
event.session_id = "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
event.properties = {"key":"value", "another": {"this":"nested"}}

response = event.send()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', token: '<token>')

example_events = [
  UA.custom_events(
    body: UA.custom_events_body(
      interaction_id: "https://docs.airship.com/api/ua/#schemas-customeventobject",
      interaction_type: "url",
      name: "example",
      properties: {
        "who" => "Alf",
        "where" => "In the garage!",
        "from" => "Melmac"
      },
      session_id: "8d168d40-bc9b-4359-800c-a546918354ac",
      transaction: "d768f61f-73ba-495f-9e16-b3b9c3b598b7",
      value: 1
    ),
    occurred: "2021-10-01T00:00:00",
    user: UA.custom_events_user(named_user_id: "Gordon Shumway")
  )
]
event = Urbanairship::CustomEvents::CustomEvent.new(client: airship)
event.events = example_events
event.create

POST /api/custom-events

Submit an externally-generated Custom Event, associated with a Channel ID or Named User, to Airship. You can use these events as Custom Event triggers for Automation or Sequences and can use handlebars to personalize messages using Custom Event properties (information in the body.properties object).

 Note

  • Requests complete validation before returning a response.
  • Requests are authenticated with a bearer token which can provide access to this resource alone, or to this resource and others.
  • The name value inside body must not contain any uppercase characters, or the event will be rejected with a 400 status code.

Security:

header PARAMETERS

  • X-UA-Appkey : StringREQUIRED

    The application key.

Request Body

An array of Custom Event objects.

Responses

  • 200

    Returned on success.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : Boolean

        Success.

      • operation_id : String

        A unique string identifying the API interaction. You can use the operation_id in support requests if something goes wrong. Format: uuid

  • 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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Channels

Channels are Airship’s unique identifiers for addressing applications on iOS, Android, Fire OS, and web devices.

Channel listing

Example

GET /api/channels HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channels
Link: <https://go.urbanairship.com/api/channels/?start=1234&limit=100>; rel=next

{
   "ok": true,
   "next_page": "https://go.urbanairship.com/api/channels?start=07AAFE44CD82C2F4E3FBAB8962A95B95F90A54857FB8532A155DE3510B481C13&limit=2",
   "channels": [
      {
         "channel_id": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
         "device_type": "android",
         "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
         "opt_in": true,
         "installed": true,
         "background": true,
         "created": "2020-03-06T18:52:59",
         "last_registration": "2020-10-07T21:28:35",
         "named_user_id": "some_id_that_maps_to_your_systems",
         "alias": "null",
         "tags": [
            "tag1",
            "tag2"
         ],
         "tag_groups": {
            "tag_group_1": ["tag1", "tag2"],
            "tag_group_2": ["tag1", "tag2"]
         },
         "device_attributes": {
             "ua_device_os": "10",
             "ua_country": "US",
             "ua_device_model": "SM-G973U",
             "ua_local_tz": "America/Los_Angeles",
             "ua_app_version": "2020-02-01T002322-goat",
             "ua_location_settings": "true",
             "ua_language": "en",
             "ua_sdk_version": "12.2.0",
             "ua_carrier": "Verizon "
          },
          "attributes": {
             "first_name": "Cool",
             "last_name": "Person",
             "birthdate": "1983-03-15T00:00:00",
          }
      },
      {
         "channel_id": "bd36e8c7-5a73-47c0-9716-99fd3d4197d5",
         "device_type": "ios",
         "push_address": null,
         "opt_in": false,
         "installed": true,
         "background": true,
         "created": "2020-03-06T18:52:59",
         "last_registration": "2020-10-07T21:28:35",
         "named_user_id": "some_id_that_maps_to_your_systems",
         "alias": "null",
         "tags": [
            "tag1",
            "tag2"
         ],
         "tag_groups": {
            "tag_group_1": ["tag1", "tag2"],
            "tag_group_2": ["tag1", "tag2"]
         },
         "ios": {
            "badge": 0,
            "quiettime": {
               "start": null,
               "end": null
            },
            "tz": null
         }
      }
   ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelRequest request = ChannelRequest.newRequest();
Response<ChannelResponse> response = client.execute(request);
ChannelView channels = response.getBody().get().getChannelView().get();
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
channel_id = None

for channel in ua.ChannelList(airship):
   channel_id = channel.channel_id
   print (channel.channel_id, channel.device_type, channel.tags,
         channel.push_address, channel.named_user_id, channel.opt_in)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_list = UA::ChannelList.new(client: airship)
channel_list.each do |channel|
    puts(channel)
end
puts(channel_list.count)

GET /api/channels

List all channels registered to this app key, along with associated data and metadata.

 Note

Tags added to a channel via the Named Users tag endpoint will not appear with a request to this endpoint. To view those tags, you must look up the Named User associated with the channel.

Security:

query PARAMETERS

  • limit : Integer

    The default limit is 1,000 channel objects returned per request. Set the limit to 1,000 or fewer in your API calls.

    Max: 1000

Responses

  • 200

    Returns OK for success with the JSON response. Tags added to a channel using /named_users/tags are not returned from this endpoint. To view those tags, you must look up the Named User associated with the channel.

    RESPONSE HEADERS

    • Provides the URL to the current page of results. The query within the URL contains the limit (the number of results on the page) and start (the first channel_id in the result set) parameters.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • channels : Array [Channel listing object]

        An array of channel objects.

      • next_page : String

        If there is more than one page of results, use this link to get the next page of results. Format: url

      • ok : Boolean

        Success.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Set or remove attributes on channels

Example

POST /api/channels/attributes HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
       "android_channel": ["13863b3c-f860-4bbf-a9f1-4d785379b8a2"]
    },
    "attributes": [
       {
             "action": "set",
             "key": "major_league",
             "value": "sf_giants"
       },
       {
             "action": "remove",
             "key": "minor_league"
       },
       {
             "action": "set",
             "key": "position",
             "value": "LF"
       },
       {
             "action": "set",
             "key": "specialData",
             "value": {
                  "timestamp": "1983-03-15 10:00:00",
                  "specialties": [
                    {
                        "specialty": {
                            "name": "golden",
                            "property": "small"
                        }
                    },
                    {
                        "specialty": {
                            "name": "silver",
                            "property": "medium"
                        }
                    }
                ]
            }
       }
    ]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Attribute setMajorLeague = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("major_league")
        .setValue("sf_giants")
        .build();

Attribute removeMinorLeague = Attribute.newBuilder()
        .setAction(AttributeAction.REMOVE)
        .setKey("minor_league")
        .build();

Attribute setPosition = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("position")
        .setValue("LF")
        .build();

String specialtiesStr = "{" +
                        "    \"timestamp\": \"1983-03-15 10:00:00\"," +
                        "    \"specialties\": [{" +
                        "            \"specialty\": {" +
                        "                \"name\": \"golden\"," +
                        "                \"property\": \"small\"" +
                        "            }" +
                        "        }," +
                        "        {" +
                        "            \"specialty\": {" +
                        "                \"name\": \"silver\"," +
                        "                \"property\": \"medium\"" +
                        "            }" +
                        "        }" +
                        "    ]" +
                        "}";
JSONObject specialtiesJson = new JSONObject(specialtiesStr);
Attribute setSpecialties = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("specialties")
        .setValue(specialtiesJson)
        .build();

ChannelAttributesPayload payload = ChannelAttributesPayload.newBuilder()
        .addAttribute(setMajorLeague)
        .addAttribute(removeMinorLeague)
        .addAttribute(setPosition)
        .setAudience(AttributeAudience.newBuilder()
                .addDeviceId(AttributeAudienceType.ANDROID_CHANNEL, "13863b3c-f860-4bbf-a9f1-4d785379b8a2")
                .build())
        .build();

ChannelAttributesRequest request = ChannelAttributesRequest.newRequest(payload);
Response<ChannelAttributesResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

set_major_league = ua.Attribute(
                      action="set",
                      key="major_league",
                      value="sf_giants")

remove_minor_league = ua.Attribute(
                         action="remove",
                         key="minor_league")

set_position = ua.Attribute(
                  action="set",
                  key="position",
                  value="LF")

specialties_string = "{" +
                     "    \"timestamp\": \"1983-03-15 10:00:00\"," +
                     "    \"specialties\": [{" +
                     "            \"specialty\": {" +
                     "                \"name\": \"golden\"," +
                     "                \"property\": \"small\"" +
                     "            }" +
                     "        }," +
                     "        {" +
                     "            \"specialty\": {" +
                     "                \"name\": \"silver\"," +
                     "                \"property\": \"medium\"" +
                     "            }" +
                     "        }" +
                     "    ]" +
                     "}"
specialties_json = json.loads(specialties_string)
specialties = ua.Attribute(
                  action="set",
                  key="specialties",
                  value=specialties_json)

modifications = ua.ModifyAttributes(
                   airship=airship,
                   attributes=[set_major_league,
                               remove_minor_league,
                               set_position],
                   channel="13863b3c-f860-4bbf-a9f1-4d785379b8a2"
                )

modifications.send()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_info = UA::ChannelInfo.new(client: airship)
channel_info.audience = {"android_channel": '13863b3c-f860-4bbf-a9f1-4d785379b8a2'}
channel_info.attributes =  {
    "action": "set",
    "key": "major_league",
    "value": "sf_giants"
}
channel_info.set_attributes

Example request with dates and numbers

POST /api/channels/attributes HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
       "android_channel": ["13863b3c-f860-4bbf-a9f1-4d785379b8a2"]
    },
    "attributes": [
       {
             "action": "set",
             "key": "birthday",
             "value": "1983-03-15 10:00:00"
       },
       {
             "action": "set",
             "key": "fav_number",
             "value": 42
       },
       {
             "action": "remove",
             "key": "another_attribute"
       }
    ]
}

POST /api/channels/attributes

Set or remove attributes on a channel. Aside from Airship’s default attributes, you must define attributes in the Airship dashboard before you can set them on channels.

 Important

Use the Named Users endpoint to set or remove attributes on Named Users.

Security:

Request Body

  • Content-Type: application/json

    Object

    Include an audience object and an array of attributes objects in your request.

    OBJECT PROPERTIES

    • attributes : Attribute assignmentREQUIRED

    • audience : ObjectREQUIRED

      The channel(s) you want to set or remove attributes for.

      OBJECT PROPERTIES

      • amazon_channel : Object

        The unique channel identifier used to target a Fire OS device.

        OBJECT PROPERTIES

        • amazon_channel : AnyREQUIRED

          One of

          • String

            Format: uuid

          • Array [String]

            Max items: 100 Min items: 1

            ARRAY ITEM

            • Format: uuid

      • android_channel : Object

        The unique channel identifier used to target an Android device.

        OBJECT PROPERTIES

        • android_channel : AnyREQUIRED

          One of

          • String

            Format: uuid

          • Array [String]

            Max items: 100 Min items: 1

            ARRAY ITEM

            • Format: uuid

      • channel : Object

        The unique channel identifier used to target an open channel device or web device, i.e., web browser.

        OBJECT PROPERTIES

        • channel : AnyREQUIRED

          One of

          • String

            Format: uuid

          • Array [String]

            Max items: 100 Min items: 1

            ARRAY ITEM

            • Format: uuid

      • email_address : Array [String]

        The unique channel identifier used to target an email address. Max items: 100 Min items: 1

      • ios_channel : Object

        The unique channel identifier used to target an iOS device.

        OBJECT PROPERTIES

        • ios_channel : AnyREQUIRED

          One of

          • String

            Format: uuid

          • Array [String]

            Max items: 100 Min items: 1

            ARRAY ITEM

            • Format: uuid

      • sms_id : Object

        Selects a single SMS device. The msisdn must be opted_in to receive notifications.

        OBJECT PROPERTIES

        • msisdn : StringREQUIRED

          The recipient phone number. Max length: 128 Min length: 1

        • sender : StringREQUIRED

          The sender that the app is configured to send SMS messages from. Max length: 128 Min length: 1

      • web_channel : Array [String]

        The unique channel identifier used to target a web device. Max items: 100 Min items: 1

Responses

  • 200

    The operation was successful.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : Boolean

        If true, your request was successful.

      • warning : String

        Alerts you if your request could not be processed. You may receive a 200 with a warning if you provide a value that does not match your attribute type. For example, an attribute that expects a numeric value will allow a value of “25” but fail if you input “twenty-five”.

  • 400

    Parsing or validating the request failed.

    RESPONSE BODY

    • Content-Type: application/json

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Subscribe or unsubscribe channels to/from subscription lists

Example

POST /api/channels/subscription_lists HTTP/1.1
Authorization: Basic <App Auth>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "subscription_lists": [
      {
         "action":"subscribe",
         "list_id":"intriguing_ideas"
      },
      {
         "action":"unsubscribe",
         "list_id":"animal_facts"
      }
   ],
   "audience": {
      "ios_channel": [
         "b8f9b663-0a3b-cf45-587a-be880946e881"
      ],
      "email_address": [
         "homer@example.com",
         "nick@example.com"
      ]
   }
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

 SubscriptionList subscriptionList = SubscriptionList.newBuilder()
       .setListId("big_deals")
       .setAction(SubscriptionListAction.SUBSCRIBE)
       .build();

 SubscriptionListPayload payload = SubscriptionListPayload.newBuilder()
       .addSubscriptionList(subscriptionList)
       .setAudience(ChannelAudience.newBuilder()
                .addDeviceId(ChannelAudienceType.ANDROID_CHANNEL, "002b4104-c94f-418d-be86-ead3214b3244").build())
       .build();

 SubscriptionListRequest request  = SubscriptionListRequest.newRequest(payload);
 Response<SubscriptionListResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

subscription_list = ua.SubscriptionList(airship)

subscription_list.subscribe(list_id="intriguing_ideas",
                            audience=ua.email("nick@example.com")
                           )

subscription_list.unsubscribe(list_id="animal_facts", 
                              audience=ua.ios_channel(
                                 "b8f9b663-0a3b-cf45-587a-be880946e881"
                                 )
                              )
This operation is not currently supported.

POST /api/channels/subscription_lists

Subscribe or unsubscribe channels to/from Subscription Lists.

 Note

If you are using a single-channel Preference Center created before October 10, 2022, that has not been migrated to user-level, use the /api/channels/subscription_lists endpoint to add or remove individual channels to/from your subscription list. Otherwise, use the Scoped Named User batch operations endpoint to do so.

 Important

You must first create a subscription list in the dashboard, then you can refer to its ID when subscribing users. When subscribing users, if the list has not already been created in the dashboard, then the list will be created at the same time but will not be accessible from the dashboard; the list will available for API use only.

Security:

Request Body

  • Content-Type: application/json

    The request payload must be a JSON object with the following fields.

    All of

Responses

  • 202

    Returns OK for success.

    RESPONSE BODY

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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Channel tags

Example

POST /api/channels/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
      "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "android_channel": "13863b3c-f860-4bbf-a9f1-4d785379b8a2"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
   }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "warnings": ["The following tag groups do not exist: my_fav_tag_group2", "The following tag groups are deactivated: my_fav_tag_group3"]
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelTagRequest request = ChannelTagRequest.newRequest()
        .addIOSChannel("b8f9b663-0a3b-cf45-587a-be880946e881")
        .addAndroidChannel("13863b3c-f860-4bbf-a9f1-4d785379b8a2")
        .addTags("my_fav_tag_group1", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group2", ImmutableSet.of("tag1", "tag2", "tag3"))
        .addTags("my_fav_tag_group3", ImmutableSet.of("tag1", "tag2", "tag3"));

Response<GenericResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
channel_tags = ua.devices.ChannelTags(airship)
ios_audience = ['b8f9b663-0a3b-cf45-587a-be880946e881']
android_audience = ['13863b3c-f860-4bbf-a9f1-4d785379b8a2']
channel_tags.set_audience(ios_audience, android_audience
)
channel_tags.add('my_fav_tag_group1', ['tag1', 'tag2', 'tag3'])
channel_tags.remove('my_fav_tag_group2', 'tag4')
channel_tags.send()
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_tags = UA::ChannelTags.new(client: airship)
ios_audience = 'b8f9b663-0a3b-cf45-587a-be880946e881'
android_audience = '13863b3c-f860-4bbf-a9f1-4d785379b8a2'
channel_tags.set_audience(
    ios: ios_audience,
    android: android_audience
)
channel_tags.add(group_name: 'my_fav_tag_group1', tags: ['tag1', 'tag2', 'tag3'])
channel_tags.remove(group_name: 'my_fav_tag_group2', tags: 'tag4')
channel_tags.send_request

POST /api/channels/tags

Add, remove, or set tags on a channel.

 Important

A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response. We support up to 1,000 tags per channel. Adding more than 1,000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support  if you believe your use case requires more than 1,000 tags per channel, and they will help you find an alternative.

Security:

Request Body

  • Content-Type: application/json

    Object

    A single request body may contain add and/or remove objects or a single set object. At least one of the add, remove, or set objects must be present in a request.

    OBJECT PROPERTIES

    • add : Tag Group object

      Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.

    • audience : ObjectREQUIRED

      Specifies one or more channels that you want to apply tag operations to.

      OBJECT PROPERTIES

      • amazon_channel : Array [String]

        The unique channel identifier for a Fire OS device. Max items: 1000 Min items: 1

      • android_channel : Array [String]

        The unique channel identifier for an Android device. Max items: 1000 Min items: 1

      • channel : Array [String]

        The unique channel identifier for email, sms, open, or web device types. Max items: 1000 Min items: 1

      • ios_channel : Array [String]

        The unique channel identifier for an iOS device. Max items: 1000 Min items: 1

    • remove : Tag Group object

      Removes the specified tags from the channel.

    • set : Tag Group object

      Assigns a list of tags exactly. Any previously set tags that are not in this current list will be removed.

Responses

  • 200

    Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 is returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • ok : Boolean

        If true, your request was processed normally.

      • warnings : Array [String]

        Returned when some tag groups could not be updated. Contains a string indicating each tag group that could not be updated and the reason the update failed.

  • 400

    Bad Request. Parsing or validating the request failed. You will get this error if a tag is present in both the add and remove fields.

    RESPONSE BODY

    • Content-Type: application/json

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 403

    Returned in cases when the app does not permit associations from the device. Secure tag groups require master secret to modify tags.

    RESPONSE BODY

    • Content-Type: application/json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Uninstall channels

Example

POST /api/channels/uninstall HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
   {
      "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "device_type": "ios"
   },
   {
      "channel_id": "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
      "device_type": "android"
   }
]
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

 Set<ChannelUninstallDevice> channels = ImmutableSet.of(
       new ChannelUninstallDevice("00f74677-4616-4958-bd91-30e949814d2c", ChannelUninstallDeviceType.IOS),
       new ChannelUninstallDevice("007f7156-9b82-4cb6-a2f9-e2c8e7fce13d", ChannelUninstallDeviceType.ANDROID)
 );

 ChannelUninstallPayload payload = ChannelUninstallPayload.newBuilder()
       .setChannels(channels)
       .build();

 ChannelUninstallRequest request = ChannelUninstallRequest.newRequest(payload);
 Response<ChannelUninstallResponse> response = client.execute(request);
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
channel_uninstall = ua.ChannelUninstall(airship)
channel = {
   "channel_id": 'b8f9b663-0a3b-cf45-587a-be880946e881',
   "device_type": "ios"
   }

channel_uninstall.uninstall(channel)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

cu = UA::ChannelUninstall.new(client: airship)

chans = [{"channel_id" => "b8f9b663-0a3b-cf45-587a-be880946e881",
          "device_type" => "ios"},
         {"channel_id" => "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
          "device_type" => "android"}]

cu.uninstall(channels: chans)

POST /api/channels/uninstall

Uninstalls a channel, removing it and all accompanying analytic data (including Performance Analytics) from Airship systems in accordance with data privacy law compliance.

Uninstallation is handled automatically by the Airship SDK and push systems. If a user decides to opt in to communications again (either by using your app or other user preferences), they will create a new channel and a new set of analytic data. The value of a Channel ID may be the same as before however none of the associated metadata will persist when a user opts in again. A new Channel ID will be created if the user clears their browser’s cookies and data, deletes and reinstalls the app, etc.

See Individual Data Privacy Rights Under Data Privacy Laws for more information about data privacy law compliance.

 Note

Channel uninstallation, like channel creation, is an asynchronous operation, and may take some time to complete.

Security:

Request Body

  • Content-Type: application/json

    Array [Object]

    Max items: 1000 Min items: 1

    ARRAY ITEM

    • Specifies the Channel ID and device type you want to uninstall.

      OBJECT PROPERTIES

      • channel_id : StringREQUIRED

        The Channel ID.

      • device_type : StringREQUIRED

        The device type of the channel.

        Possible values: ios, android, amazon, web, open

Responses

  • 202

    Returns OK for success.

    RESPONSE BODY

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

      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

      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

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Channel lookup

Example

GET /api/channels/9c36e8c7-5a73-47c0-9716-99fd3d4197d5 HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channel

{
   "ok": true,
   "channel": {
      "channel_id": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
      "device_type": "ios",
      "installed": true,
      "opt_in": false,
      "background": true,
      "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
      "created": "2020-08-08T20:41:06",
      "last_registration": "2020-05-01T18:00:27",
      "named_user_id": "some_id_that_maps_to_your_systems",
      "alias": null,
      "tags": [
         "tag1",
         "tag2"
      ],
      "tag_groups": {
         "tag_group_1": ["tag1", "tag2"],
         "tag_group_2": ["tag1", "tag2"]
      },
      "ios": {
         "badge": 0,
         "quiettime": {
            "start": null,
            "end": null
         },
         "tz": "America/Los_Angeles"
      },
      "open_tracking_opted_in": "2022-11-26T00:00:00",
      "open_tracking_opted_out": "2022-12-11T00:00:00",
      "click_tracking_opted_in": "2022-11-26T00:00:00",
      "click_tracking_opted_out": "2022-12-11T00:00:00"
   }
}
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelRequest request = ChannelRequest.newRequest("9c36e8c7-5a73-47c0-9716-99fd3d4197d5");
Response<ChannelResponse> response = client.execute(request);
ChannelView channel = response.getBody().get().getChannelView().get();
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
channel = ua.ChannelInfo(airship).lookup('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
print (channel.channel_id, channel.device_type, channel.tags,
      channel.push_address, channel.named_user_id, channel.opt_in)
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

channel_client = UA::ChannelInfo.new(client: airship)
channel_info = channel_client.lookup(uuid: '9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
puts(channel_info)

Example open channel lookup response with all optional keys

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channel

{
   "ok": true,
   "channel": {
      "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "type": "open",
      "opt_in": true,
      "address": "example@example.com",

      "created": "2013-08-08T20:41:06",
      "last_registration": "2014-05-01T18:00:27",

      "named_user_id": "john_doe_123",
      "tags": ["asdf"],

      "tag_groups": {
         "timezone" : ["America/Los_Angeles"],
         "locale_country" : ["US"],
         "locale_language" : ["en"],
         "tag_group_1" : ["tag1", "tag2"],
         "tag_group_2" : ["tag1", "tag2"]
      },

      "open" {
         "open_platform_name": "email",
         "identifiers": {
            "com.example.external_id": "df6a6b50-9843-7894-1235-12aed4489489"
         }
      }
   }
}

Example open channel lookup response with only required keys

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
Data-Attribute: channel

{
   "ok": true,
   "channel": {
      "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",

      "type": "open",
      "opt_in": false,
      "address": "example@example.com",

      "created": "2013-08-08T20:41:06",
      "last_modified": "2014-05-01T18:00:27",

      "tags": [],
      "tag_groups" {},

      "open": {
         "open_platform_name": "email"
      }
   }
}

GET /api/channels/{channel_id}

Fetch an individual channel registered to the app key, along with associated data and metadata.

 Note

Tags added to a channel via the Named Users tag endpoint will not appear with a request to this endpoint. To view those tags, you must look up the Named User associated with the channel.

Security:

path PARAMETERS

  • channel_id : StringREQUIRED

    The unique channel identifier.

Responses

  • 200

    Tags added to a channel using /named_users/tags are not returned from this endpoint. To view those tags, you must look up the Named User associated with the channel.

    RESPONSE BODY

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

      OBJECT PROPERTIES

      • channel : Any

        A channel object.

        One of

        • Channel listing object

          Describes a channel listing object.

        • Open channel object : Object

          Describes an open channel.

          OBJECT PROPERTIES

          • address : String

            The address to send push notifications to when device_type is email or open.

          • channel_id : String

            The unique channel identifier for a device. Format: uuid

          • created : String

            The creation date-time of this channel. Format: date-time

          • last_registration : String

            The last registration date-time of this channel, if known. Format: date-time

          • locale_country : String

            The two-letter country locale short code. Will set the ua_locale_country tag group to the specified value.

          • locale_language : String

            The two-letter language locale short code. Will set the ua_locale_language tag group to the specified value.

          • named_user_id : String

            A customer-chosen ID that represents the device user, e.g., CRM ID. This ID cannot have leading or trailing whitespace. Pattern: ^[^\s].{1,125}\S$ Max length: 128 Min length: 1

          • open : Object

            Contains options that apply when the device_type is set to open.

            OBJECT PROPERTIES

            • identifiers : Object

              A set of up to 100 key:value pairs representing identifiers for this channel in your own delivery systems and delivered as a part of webhook payloads.

            • old_address : String

              If a channel exists for the value of old_address, replaces that channel’s address with the value of address. Use infrequently, such as when an end user’s phone number or email address permanently changes.

            • open_platform_name : String

              The name of the open channel that this channel_id is registered on.

          • opt_in : Boolean

            If true, the channel is opted in to push notifications. If false, it is not.

          • set_tags : Boolean

            When true, replaces all device tags on the channel with the set provided in "tags". When false or absent, the "tags" set is unioned with existing device tags.

          • tag_groups : Tag Group object

            One or more tag group objects (including Device Property Tags) associated with this channel.

          • tags : Array [String]

            An array of tags associated with this channel. Max items: 1000

          • timezone : String

            An IANA tzdata identifier for the time zone as a string, e.g., "America/Los_Angeles". Will set the timezone tag group tag with the specified value.

          • type : String

            Specifies the device platform for a channel.

            Possible values: open

      • ok : Boolean

        Success.

  • 401

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

    RESPONSE BODY

    • Content-Type: text/plain

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

  • 404

    The requested resource doesn’t exist.

    RESPONSE BODY

    • Content-Type: application/vnd.urbanairship+json

      Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Open Channels

Open Channels are custom communication channels that you can configure for messaging, using the same segmentation and scheduling tools available on natively-supported platforms (iOS, Android, etc.). With Open Channels, you define a new open platform, e.g., SMS, Slack, Acme™ Smart Toasters, and register the new platform with Airship.

If you are sending through the Push API, platform overrides for open platforms are covered in Open Channel Overrides. For open channel lookup, use the Channel Lookup endpoint.

Register new / update channel

Example

POST /api/channels/open HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "channel": {
      "type": "open",
      "opt_in": true,
      "address": "Number Four",
      "tags": [
         "toaster",