Urban Airship API Reference

Introduction

Urban Airship provides a number of REST API endpoints collectively known as the Urban Airship API Version 3, in support of our Engage and Web Notify product lines. Version 3 is the current and only supported version of the Urban Airship API.

Base URL

All URLs referenced in the documentation have the following base:

https://go.urbanairship.com

API Request Format

Example Request:

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

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.

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 Not Acceptable is returned.

The content type used is a vendor-specific media type (see RFC 4288), and must be specified as follows:

application/vnd.urbanairship+json; version=3;

Authentication

API requests are identified using HTTP basic authentication. The username portion is the application key. The password portion is either the application secret or master secret. The application secret is restricted to certain low-security APIs, as it is intended to be included in the distributed application. The master secret is needed for sending messages and other high-value requests, and as such must be guarded carefully.

Important

Never embed the master secret in an application you distribute.

Date/Time Format

All date/time values are represented according to ISO 8601 in UTC. A T separator is preferred but not required; it will be included in all date/time values generated by the API.

API Response Format

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
Data-Attribute: push_ids
{
    "ok" : true,
    "operation_id" : "5c5c6a11-3e63-4c52-9a75-4677702f2c18",
    "push_ids" : [
        "2f2fb168-710e-1596-f678-d7dd6c19adea",
        "88438e81-bb31-82a9-5feb-e7fd5b21ca7e",
        "10665229-e8bc-4606-7c98-d4b7fb82a97b"
    ],
    "message_ids": [],
    "content_urls": []
}

All API responses are HTTP responses, making use of appropriate HTTP response codes. When a body is present, it will usually be in JSON format.

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.

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, and codes in the 500 range indicate system errors.

In the event of an error, the response body will contain an error object.

Response Codes

200 OK
Nice work!
201 Created
An API request to create a new entity or entities was successful, the entities were created.
202 Accepted
An API request has been successfully accepted into a processing queue to be acted on later.
204 No Content
An API request was successful, but there is no response body to return. Often seen on successful DELETE calls.
400 Bad Request
Parsing or validating the request failed.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
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.
404 Not Found
Returned when a request is made for a nonexistent entity.
405 Method Not Allowed
Returned when a request is made using an HTTP method not supported by the endpoint. For example, sending a DELETE to /api/schedules.
406 Unacceptable
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
410 Gone
The requested resource is no longer available on this server and there is no forwarding address.

Error Object

Example:

{
    "ok" : false,
    "error" : "Could not parse request body.",
    "error_code" : 40000,
    "details" : {
        "error" : "The key 'alert1' is not allowed in this context",
        "path" : "notification.alert1",
        "location" : {
            "line" : 5,
            "column" : 18
        }
    },
    "operation_id" : "da714684-cd89-fd14-7b51-6f623efa07c0",
}

Error objects are used in the API response to indicate something went wrong. An error object is a JSON dictionary with the following attributes:

  • "ok" - false

  • "error" - A simple human-readable string

  • "error_code" - A numeric code indicating the specific error condition

  • "details" - A JSON dictionary indicating where the error occurred in the JSON parsing, if available, and further information about the nature of the error

  • "operation_id" - An opaque 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.

Note

When writing your application, it's a good idea to log whenever you receive a non-2XX response. For best results, log the request and response headers as well as the request and response body. This will give you the most information to fix the problem or to contact Support.

Endpoints

Push

Use the /api/push endpoint to send or validate push notifications or any type of rich messaging, including Message Center, In-app Messages, or Landing Pages.

Send Push

Example Request:

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": "all"
}

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
Data-Attribute: push_ids

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078"
    ]
}
POST /api/push

Send a push notification to a specified device or list of devices. The body of the request must be one of:

JSON Parameters

audience
An audience selector identifying the devices to push to.
notification
A notification payload defining contents to be delivered to devices.
device_types
A device type specifying the platform to push to.

Response Codes

202 Accepted
The push notification has been accepted for processing.

Validate

Example: Missing Payload

A push which specifies delivery to a platform, but does not supply a payload for that platform, is invalid. This push is invalid because it specifies Android as a delivery platform, but does not provide any > payload for android:

{
   "audience" : "all",
   "device_types" : [ "ios", "android" ],
   "notification" : {
      "ios" : {
         "alert" : "Boo"
      }
   }
}

Example: Device Identifier/Restriction Mis-Match

A push which includes a device identifier in the audience selection, but does not include the corresponding platform (or "all") in the "device_types"" specifier, is invalid. This push is invalid because it includes an iOS device token in the audience selection, but has not specified "ios" as a delivery platform:

{
   "audience": {
      "or": [
         { "android_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d0" },
         { "device_token": "645A5C6C06AFB2AE095B079135168A04A5F974FBF27163F3EC6FE1F2D5AFE008" }
      ]
   },
   "device_types": [ "android" ],
   "notification": {
      "alert": "WAT"
   }
}
POST /api/push/validate

Accept the same range of payloads as /api/push, but parse and validate only, without sending any pushes.

To the right are some specific validation cases which will cause pushes to be rejected with an HTTP 400 error. The response body will provide explicit detail regarding the error.

Response Codes

200 OK
The payload was valid.

Throttling

Urban Airship is designed for extremely high throughput to ensure your message will go out to your entire audience as fast as possible. This can result in a very large audience opening your app simultaneously. In certain cases this can put more load on unrelated APIs or systems or APIs integrated with your app than they are capable of handling. Urban Airship offers app-level push throttling to allow you to tune delivery to a level that doesn't put strain on those systems.

If you are interested in enabling push throttling for your app, please contact support@urbanairship.com.

Schedules

Important

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

Schedule a Notification

Example Request:

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": "2018-06-03T09:15:00"
    },
    "push": {
        "audience": { "tag": "earlyBirds" },
        "notification": { "alert": "Good Day Sunshine" },
        "device_types": "all"
    }
  },
  {
    "name": "Everybody Else",
    "schedule": {
        "best_time": {
          "send_date": "2018-06-03"
        }
    },
    "push": {
        "audience": { "tag": "normalPeople" },
        "notification": { "alert": "Stay Up Late" },
        "device_types": "all"
    }
  }
]

Example Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3;
Data-Attribute: schedule_urls

{
   "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": "2016-06-03T09:15:00"
         },
         "name": "Morning People",
         "push": {
            "audience": { "tag": "earlyBirds" },
            "notification": { "alert": "Good Day Sunshine" },
            "device_types": "all"
         },
         "push_ids": [ "83046227-9b06-4114-9f23-0df349792bbd" ]
      }
      {
          "url": "https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e",
          "schedule": {
            "best_time": {
              "send_date": "2018-06-03"
            }
          }
          "name": "Everybody Else",
          "push": {
            "audience": { "tag": "normalPeople" },
            "notification": { "alert": "Stay Up Late" },
            "device_types": "all"
         },
         "push_ids": [ "8438e81-bb31-82a9-5feb-e7fd5b21ca7e" ]
      }
   ]
}
POST /api/schedules

Scheduled notifications are created by POSTing to the schedule URI. The body of the request must be one of:

Note

best_time is represented as Optimal Time in the dashboard and is one of our Predictive features. Please contact your Urban Airship Account Manager to purchase.

JSON Parameters

schedule
A schedule object defining the schedule.
scheduled_time
The send time for a notification, in UTC.
local_scheduled_time
Alternative to scheduled_time. The scheduled device local time to send the notification.
best_time
Alternative to scheduled_time. Uses predictive analytics to send the notification at the best time to engage recipients.
send_date
The date on which to send a best_time push, localized to the time zone for the channel.
name
An optional string.
push
A push object defining the notification payload.

Response Codes

201 Created
The response body will contain an array of response objects with the created resource URIs.
403 Forbidden
The application does not have the proper entitlement to access scheduling.
404 Not Found
Returned if the scheduled push has been deleted or has already been delivered.

List Schedules

Example Request:

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

Example Response:

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

{
    "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": { }
        }
    ]
}
GET /api/schedules

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

Query Parameters

start
string (optional) - ID of the starting element for paginating results
limit
integer (optional) - maximum number of elements to return

Response Codes

200 OK
Returned on success, with the JSON representation of the scheduled pushes in the body of the response.
403 Forbidden
The application does not have the proper entitlement to access scheduling.

List a Specific Schedule

Example Request:

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

Example Response:

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

{
    "name": "Booyah Sports",
    "schedule": {
        "scheduled_time": "2013-04-01T18:45:30"
    },
    "push": {
        "audience": { "tag": [ "spoaaaarts", "Beyonce", "Nickelback" ] },
        "notification": { "alert": "Booyah!" },
        "device_types": "all"
    }
}
GET /api/schedules/(id)

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

Query Parameters

id
string (required) - ID of the schedule to retrieve

Response Codes

200 OK
Returned on success, with the JSON representation of the scheduled push in the body of the response.
403 Forbidden
The application does not have the proper entitlement to access scheduling.
404 Not Found
Returned if the scheduled push has been deleted or has already been delivered.

Update Schedule

Example Request:

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": "Booyah Sports",
    "schedule": {
        "scheduled_time": "2013-04-01T18:45:30"
    },
    "push": {
        "audience": { "tag": [ "spoaaaarts", "Beyonce", "Nickelback" ] },
        "notification": { "alert": "Booyah!" },
        "device_types": "all"
    }
}

Example Response:

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

{
    "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": "2013-04-01T18:45:30"
            },
            "name": "Booyah Sports",
            "push": {
                "audience": { "tag": [ "spoaaaarts", "Beyonce", "Nickelback" ] },
                "notification": { "alert": "Booyah!" },
                "device_types": "all"
            },
            "push_ids": [ "48fb8e8a-ee51-4e2a-9a47-9fab9b13d846" ]
        }
    ]
}
PUT /api/schedules/(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.

Query Parameters

id
string (required) - ID of the schedule to update

Response Codes

200 OK
Returned if the scheduled push has been succesfully updated.
403 Forbidden
The application does not have the proper entitlement to access scheduling.
404 Not Found
Returned if the scheduled push does not exist, has been deleted or has already been delivered.

Delete Schedule

Example Request:

DELETE /api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 204 No Content
DELETE /api/schedules/(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.

Query Parameters

id
The ID of the schedule to delete.

Response Codes

204 No Content
Returned if the scheduled push has been succesfully deleted.
403 Forbidden
The application does not have the proper entitlement to access scheduling.
404 Not Found
Returned if the scheduled push has been deleted or has already been delivered.

Automation

An Automated Message is unlike a notification or a message in that the creation of an Automated Message involves setting the conditions under which a notification or notifications will be delivered.

Due to the complexity of the logic and triggering events that will fulfill the delivery of the messages, we have a separate endpoint for interacting with these kinds of messages at /api/pipelines/. See below for examples.

Note

"Pipelines" is the naming convention for generating Automated Messages through our API but Automated Message is the proper product/feature name that you will see in the user dashboard.

Create Pipeline (Automated Message)

Example Request:

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"
                  }
               ]
            }
         ]
      }
   }
}

In the event of success, the response will contain an array of pipeline URIs, in the "pipeline_urls" attribute. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.

Example Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3;
Content-Length: 123
Data-Attribute: pipeline_urls

{
   "ok": true,
   "operation_id": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
   "pipeline_urls": [
      "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
   ]
}
POST /api/pipelines

Pipelines are created by POSTing to the pipeline URI. The body of the request must be one of:

These are the 5 top-level objects in a Pipeline object, which is what makes up your request:

JSON Parameters

name
A descriptive name for the pipeline
enabled
A boolean value indicating whether or not the pipeline is enabled
immediate_trigger
outcome
A single outcome object or an array of outcome objects
timing
A single timing object

Response Codes

201 Created
The response body will contain an array of response objects with the created resource URIs.
403 Forbidden
The application does not have the proper entitlement to access pipelines.
409 Conflict
The application has exceeded the maximum number of active or total pipelines. In order to increase pipeline maximum, contact support@urbanairship.com.

Validate Pipeline

Example Request:

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"
                  }
               ]
            }
         ]
      }
   }
}

Example Response:

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

{
   "ok": true
}
POST /api/pipelines/validate

Accept the same range of payloads as POSTing to /api/pipelines, but parse and validate only, without creating a pipeline.

Response Codes

200 OK
The payload was valid.
406 Not Acceptable
The request could not be satisfied because the requested API version is not available.

List Existing Pipelines

Example Request:

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

Example Response:

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

{
   "ok": true,
   "pipelines": [
      {
         "creation_time": "2015-03-20T18:37:23",
         "enabled": true,
         "immediate_trigger": {
            "tag_added": { "tag": "bought_shoes" }
         },
         "last_modified_time": "2015-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"
      },
      {
         "..."
      }
   ]
}
GET /api/pipelines/?limit=(integer)&enabled=(enabled_flag)

List all existing pipelines. Returns an array of pipeline objects in the "pipelines" attribute.

Query Parameters

limit
integer (optional) - Positive maximum number of elements to return.
enabled
boolean (optional) - Limit the listing to only pipelines which match the specified enabled flag. If enabled is omitted, all pipelines will be returned, regardless of status.

Response Body

pipelines

An array of pipeline objects.

Response Codes

200 OK
Returned on success, with the JSON representation of the pipelines in the body of the response.
403 Forbidden
The application does not have the proper entitlement to access pipelines.

List Deleted Pipelines

Example Request:

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

Example Response:

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

{
   "ok": true,
   "pipelines": [
      {
         "deletion_time": "2014-03-31T20:54:45",
         "pipeline_id": "0sdicj23-fasc-4b2f-zxcv-0baf934f0d69"
      },
      {
         "..."
      }
   ]
}
GET /api/pipelines/deleted/?start=(date)

List all deleted pipelines. Returns an array of deleted pipeline objects in the "pipelines" attribute.

Query Parameters

start
string (optional) - Timestamp of the starting element for paginating results

Response Body

pipelines

Response Codes

200 OK
Returned on success, an array of deleted pipeline objects in the pipelines attribute in the response.
403 Forbidden
The application does not have the proper entitlement to access pipelines.

Individual Pipeline Lookup

Example Request:

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

Example Response:

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

{
   "ok": true,
   "pipeline": {
      "creation_time": "2015-02-14T19:19:19",
      "enabled": true,
      "immediate_trigger": { "tag_added": "new_customer" },
      "last_modified_time": "2015-03-01T12:12:54",
      "name": "New customer",
      "outcome": {
         "push": {
            "audience": "triggered",
            "device_types": "all",
            "notification": { "alert": "Hello new customer!" }
         }
      },
      "status": "live",
      "uid": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
      "url": "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
   }
}
GET /api/pipelines/(id)

Fetch the current definition of a single pipeline resource. Returns an array containing a single pipeline object in the "pipelines" attribute.

Query Parameters

id
The ID of the pipeline to update

Response Body

pipeline

Response Codes

200 OK
Returned on success, with the JSON representation of the pipeline in the body of the response.
403 Forbidden
The application does not have the proper entitlement to access pipelines.
404 Not Found
If the pipeline does not exist (perhaps because it has already been deleted).

Update Pipeline

Example Request:

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!"
         }
      }
   }
}

Example Response:

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

{
   "ok": true
}
PUT /api/pipelines/(id)

Update the state of a single pipeline resource. Partial updates are not permitted.

Query Parameters

id
The ID of the pipeline to update.

Response Codes

200 OK
Returned if the pipeline has been succesfully updated.
403 Forbidden
The application does not have the proper entitlement to access pipelines.
409 Conflict
The application has exceeded the maximum number of active or total pipelines. In order to increase pipeline maximum, contact support@urbanairship.com.

Delete Pipeline

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

Example Request:

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

Example Response:

HTTP/1.1 204 No Content
DELETE /api/pipelines/(id)

Query Parameters

id
The ID of the pipeline to delete

Response Codes

204 No Content
Returned if the pipeline has been succesfully deleted.
403 Forbidden
The application does not have the proper entitlement to access pipelines.
404 Not Found
Returned if the pipeline does not exist.

A/B Tests

Our A/B Tests API endpoint is located at /api/experiments and can be used to create, list, and delete Experiments or A/B tests.

People often use the following terms interchangeably: A/B Test, A/E Test, Multivariate Test. Since our API supports up to 26 variants, we support all these notions of randomized experiments with two or more variants. Please keep in mind that in Urban Airship's documentation, experiments should refer to the endpoint and its usage whereas A/B Test is the product naming convention.

Overview

We define an experiment as a set of distinct push notifications sent to disjoint subsets of an audience. You may choose the number of subsets which will receive different messages — anywhere from 2 to 26 subsets for a given experiment.

In order to create an experiment, you'll need to know the following:

  • How many variants do I want to test?

  • What are the different messages I want to test?

  • What proportion of the given audience do I want to set aside as a control group?

Once you know those things, you're ready to conduct an experiment, using the variants array and the control.

Variants Array
The variants array specifies the distinct push sent to each subset, the number of subsets to create, and the relative size of each subset. See: Variant Specification.
Control
The control may optionally be defined in your experiment. If present, the control "sets aside" a subset of the selected audience, and does not send a notification to them. Including this value has the practical effect of reducing the total audience for the experiment by that proportion. The rest of the audience will be divided (either evenly, or according to your specifications) among the defined variants.


Urban Airship will construct these pushes by creating a set of partial Push Objects, one for each defined variant. The push object is partial because certain attributes, e.g., audience and device_types are defined in the experiment, not at the level of the push notifications sent to each variant.

Experiment Examples

This experiment results in two pushes, where each has a different alert.

{
  "name" : "Experiment 1",
  "audience" : "all",
  "device_types" : "all",
  "variants" : [{
    "push" : {
      "notification" : {
        "alert" : "message 1"
      }
    }
  },
  {
    "push" : {
        "notification" : {
          "alert" : "message 2"
        }
      }
  }]
}

This experiment varies the sound used for the notification, and targets iOS only:

{
  "name" : "Experiment 1",
  "audience" : "all",
  "device_types" : ["ios"],
  "variants" : [{
    "push" : {
      "notification" : {
        "alert" : "foo",
        "ios" : {
          "sound" : "beep"
        }
      }
    }
  },
  {
    "push" : {
      "notification" : {
        "alert" : "foo",
        "ios" : {
          "sound" : "boop"
        }
      }
    }
  }]
}

This experiment opens two different landing pages and also adds a tag.

{
  "name" : "Experiment 1",
  "audience" : "all",
  "device_types" : ["ios", "android"],
  "variants" : [{
    "push" : {
      "notification" : {
        "alert" : "foo",
        "actions" : {
          "add_tag" : "bar",
          "open" : {
            "type" : "deep_link",
            "content" : "app://deeplink1"
          }
        }
      }
    }
  },
  {
    "push" : {
      "notification" : {
      "alert" : "foo",
        "actions" : {
          "add_tag" : "bar",
          "open" : {
            "type" : "deep_link",
            "content" : "app://deeplink2"
          }
        }
      }
    }
  }]
}

This experiment demonstrates splitting the audience into subsets for 25%, 25% and 50%. 25% of the audience will receive "message 1," another 25% will receive "message 2," and 50% will receive "message 3":

{
  "name" : "Experiment 1",
  "audience" : "all",
  "device_types" : "all",
  "variants" : [{
    "push" : {
      "notification" : {
        "alert" : "message 1"
      }
    },
    "weight" : 25
  },
  {
    "push" : {
      "notification" : {
        "alert" : "message 2"
      }
    },
    "weight" : 25
  },
  {
    "push" : {
      "notification" : {
        "alert" : "message 3"
      }
    },
    "weight" : 50
  }]
}

This experiment sends the same messages as the previous, but defines a control group of 10% of the audience:

{
  "name" : "Experiment 1",
  "control" : 0.1,
  "audience" : "all",
  "device_types" : "all",
  "variants" : [{
    "push" : {
      "notification" : {
        "alert" : "message 1"
      }
    },
    "weight" : 20
  },
  {
    "push" : {
      "notification" : {
        "alert" : "message 2"
      }
    },
    "weight" : 20
  },
  {
    "push" : {
      "notification" : {
        "alert" : "message 3"
      }
    },
    "weight" : 50
  }]
}

Create Experiment

Example Request:

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": "all",
    "device_types": "all",
    "variants": [
        {
            "push": {
                "notification": {
                    "alert": "message 1"
                }
            }
        },
        {
            "push": {
                "notification": {
                    "alert": "message 2"
                }
            }
        }
    ]
}

Example Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3;
Content-Length: 123
Location: https://go.urbanairship.com/api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a

{
  "ok" : "true",
  "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4",
  "experiment_id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
  "push_id" : "7e13f060-594c-11e4-8ed6-0800200c9a66"
}
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.

JSON Parameters

name
(string) Optional. A name for the experiment.
description
(string) Optional. A description of the experiment.
control
Optional. A float between 0 and 1, e.g., 0.4, representing the proportion of the audience that will not receive a push. The remaining audience will be split betweeen the variants. See: Splitting the Audience
audience
Required. The audience for the experiment. See: Audience Selection
device_types
Required. Device types for the experiment. See: Device Type Selection
campaigns
(string) Optional. Campaigns object that will be applied to resulting pushes. See: Campaigns
variants
(array) Required. An array of Variant Specifications. The array must have at least one element. It cannot have more than 26 elements. The following attributes cannot be specified when the experiment is created ? they will only be present when experiment objects are provided by the experiment retrieval and experiment listing endpoints:
id
(string) The unique ID assigned to this experiment.
created_at
(string) The time when this experiment's definition was created. The timestamp will be an ISO formatted timestamp given in UTC.
push_id
(string) The push ID associated with this experiment. For examples, please see the Experiment Examples section.

Response Headers

Location
URI of the newly created experiment.

Response Codes

201 Created
The response body will contain the newly created experiment ID.

Validate Experiment

Example Request:

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": "all",
    "device_types": "all",
    "variants": [
        {
            "push": {
                "notification": {
                    "alert": "message 1"
                }
            }
        },
        {
            "push": {
                "notification": {
                    "alert": "message 2"
                }
            }
        }
    ]
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Content-Length: 123
{
  "ok" : "true",
  "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}
POST /api/experiments/validate

Accept the same range of payloads as /api/experiments, but parse and validate only, without creating any experiments. The body of the request should consist of a single experiment object.

This endpoint is meant to be used as a smoke test and not a guarantee that the push will succeed. This does the same amount of validation as the creation endpoint, including platform-specific validation, e.g., APNS byte limit checks. However, do not rely on this as a way to determine if the push will succeed. An experiment may pass all of the validation at this level and still fail to be delivered. For example, there might not be any devices in your audience.

Response Codes

200 OK
The experiment was validated.

Experiment Lookup

Example Request:

GET /api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Content-Length: 123
Data-Attribute: experiment
{
   "ok" : "true",
   "experiment" : {
      "id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
      "push_id": "d00f07b0-594c-11e4-8ed6-0800200c9a66",
      "name" : "Experiment 1",
      "audience" : "all",
      "device_types" : "all",
      "variants" : [{
            "push" : {
               "notification" : {
                  "alert" : "message 1"
               }
            },
            "id" : 0,
         },
         {
            "push" : {
               "notification" : {
               "alert" : "message 2"
            }
         },
         "id" : 1,
     }]
   }
}
GET /api/experiments/(experiment_id)

Retrieve the definition of a given experiment. If the experiment is found, the JSON representation of the experiment is returned in the body of the response.

Query Parameters

experiment_id
The ID of the experiment to look up.

Response Body

experiment

Response Codes

200 OK
Returned on success, with the JSON representation of the experiment in the body of the response.
404 Not Found
The experiment does not exist.

Experiment Listing

Example Request:

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

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Content-Length: 123
Data-Attribute: experiments
Count: 2
Total-Count: 2
 {
   "ok" : "true",
   "count" : 2,
   "total_count" : 2,
   "experiments" : [{
     "name" : "Experiment 1",
     "control" : 0.33,
     "audience" : "all",
     "device_types" : "all",
     "variants" : [{
       "push" : {
         "notification" : {
           "alert" : "message 1"
         }
       },
       "id" : 0,
     },
     {
       "push" : {
           "notification" : {
             "alert" : "message 2"
           }
       },
       "id" : 1,
     }],
     "id" : "b5bc3dd1-9ea4-4208-b5f1-9e7ac3fe0502",
     "created_at" : "2016-03-03T21:08:05",
     "push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
   }, {
     "name" : "Experiment 2",
     "description" : "The second experiment",
     "audience" : "all",
     "device_types" : "all",
     "variants" : [{
       "push" : {
         "notification" : {
           "alert" : "message 1"
         }
       },
       "id" : 0,
     },
     {
       "push" : {
           "notification" : {
             "alert" : "message 2"
           }
       },
       "id" : 1,
     }],
     "id" : "e464aa7e-be40-4994-a290-1bbada7187d8",
     "created_at" : "2016-03-03T21:08:05",
     "push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
   }]
}
GET /api/experiments?limit=(limit)&offset=(offset)

List all past experiments, sorted by when they were created (with most recent first).

Query Parameters

limit
integer (optional) - Positive maximum number of elements to return.
offset

integer (optional) - Represents a zero-based integer offset into the ordered list of records, useful for addressing pages directly.

Response Body

ok
Boolean. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.
count
Integer. Always present when ok is true. The number of items returned in this page of results.
total_count
Integer. Always present when ok is true. The total number of items available for listing.
experiments

An array of experiment objects. Always present when ok is true, and always an array of zero or more . The objects will be sorted by either create_date from newest to oldest or scheduled_time in ascending time order. The number of objects will never exceed the limit specified in the request.

next_page
String. An optional relative URL which can be used to retrieve the next page of results. If no more results are available, next_page will be absent. Never null.

Response Codes

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

Responses will be paginated, using optional limit and offset parameters. If no limit is provided, a default page size will be used. A maximum page size will also be enforced; the number of results will always be limited to that size, regardless of the value of limit.

offset, when present, represents zero-based integer offset into the ordered list of records, useful for addressing pages directly. If offset is not present, the listing will begin with the most recently sent experiment.

If offset is greater than the number of queryable experiments, an empty result will be returned.

Scheduled Experiment Listing

Example Request:

GET /api/experiments/scheduled HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

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

{
    "ok": "true",
    "count": 2,
    "total_count": 2,
    "experiments": [
        {
            "id": "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
            "name": "Experiment 1",
            "audience": "all",
            "device_types": "all",
            "variants": [
                {
                    "id": 0,
                    "schedule": {
                        "scheduled_time": "2015-11-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 1"
                        }
                    }
                },
                {
                    "id": 1,
                    "schedule": {
                        "scheduled_time": "2015-11-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 2"
                        }
                    }
                }
            ]
        },
        {
            "id": "29705c10-5951-11e4-8ed6-0800200c9a66",
            "name": "Experiment 2",
            "audience": "all",
            "device_types": "all",
            "variants": [
                {
                    "id": 0,
                    "schedule": {
                        "scheduled_time": "2015-12-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 1"
                        }
                    }
                },
                {
                    "id": 1,
                    "schedule": {
                        "scheduled_time": "2015-12-17T20:58:00Z"
                    },
                    "push": {
                        "notification": {
                            "alert": "message 2"
                        }
                    }
                }
            ]
        }
    ]
}
GET /api/experiments/scheduled?limit=(limit)&offset=(offset)

List all the scheduled experiments sorted by when they are scheduled to go out (in ascending scheduled time order).

Query Parameters

limit
integer (optional) - Positive maximum number of elements to return.
offset

integer (optional) - Represents a zero-based integer offset into the ordered list of records, useful for addressing pages directly.

Response Body

ok
Boolean. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.
count
Integer. Always present when ok is true. The number of items returned in this page of results.
total_count
Integer. Always present when ok is true. The total number of items available for listing.
experiments

An array of experiment objects. Always present when ok is true, and always an array of zero or more . The objects will be sorted by either create_date from newest to oldest or scheduled_time in ascending time order. The number of objects will never exceed the limit specified in the request.

next_page
String. An optional relative URL which can be used to retrieve the next page of results. If no more results are available, next_page will be absent. Never null.

Response Codes

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

Responses will be paginated, using optional limit and offset parameters. If no limit is provided, a default page size will be used. A maximum page size will also be enforced; the number of results will always be limited to that size, regardless of the value of limit.

offset, when present, represents a zero-based integer offset into the ordered list of records, useful for addressing pages directly. If offset is not present, the listing will begin with the experiment scheduled to go out soonest.

If offset is greater than the number of queryable experiments, an empty result will be returned.

Delete Experiment

Example Request:

DELETE /api/experiments/scheduled/(experiment_id) HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Content-Length: 123
{
  "ok" : "true",
  "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}
DELETE /api/experiments/scheduled/(experiment_id)

Delete a scheduled experiment. Note that experiments can only be deleted before they start; afterwards, an HTTP 405 ("Method not allowed") will be returned. This example shows a successful deletion.

Query Parameters

experiment_id
The ID of the experiment to delete.

Response Codes

200 OK
Returned if the experiment has been succesfully deleted.
404 Not Found
The experiment does not exist.
405 Method Not Allowed
Experiments can only be deleted before they start; afterwards, an HTTP 405 is returned.

Personalization

Template Creation and Push Example

Example Request:

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 {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!"
        }
    }
}

To build intuition with the template API, we'll go through the process of creating and pushing to a template, in detail. If you are interested in reference material rather than a walkthrough, please skip to the endpoint descriptions or the template API object reference.

First, we will create a template for a welcome message.

We use the /api/templates endpoint:

Note that the push object does not contain audience or device_types keys. These fields must be defined in the pushes generated from this template.

 

 

 

 

 

 

 

 

 

Example Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3
Location: https://go.urbanairship.com/api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161

{
    "ok" : true,
    "operation_id" : "9ce808c8-7176-45dc-b79e-44aa74249a5a",
    "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
}

The response will contain an ID that can be used to generate pushes:

 

 

 

 

Example Request:

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": "all",
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "TITLE": "Ms.",
            "FIRST_NAME": "Alice",
            "LAST_NAME": "Jones"
        }
    }
}

To create a template-based push, we use the /api/templates/push endpoint. In our case, we are going to use the template with ID "ef34a8d9-0ad7-491c-86b0-aea74da15161" and fill in the {{TITLE}}, {{FIRST_NAME}}, and {{LAST_NAME}} variables. The merge_data object contains the variable values and template id.

Note that you must provide overrides for all variables with null default values.

The push generated from this payload will be sent to the supplied iOS channel, and will contain the message:

Hello Ms. Alice Jones, this is your welcome message!

Create Template

Example Request:

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!"
        }
    }
}

Example Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3
Location: https://go.urbanairship.com/api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161

{
    "ok" : true,
    "operation_id" : "9ce808c8-7176-45dc-b79e-44aa74249a5a",
    "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161"
}
POST /api/templates

Create a new template. The body of the request will contain a template object.

 

 

 

 

 

Response Headers

Location
URI of the template, used for later updates or sends.

Response Body

template_id
Unique template ID, used for pushing and other operations.

Response Codes

201
The template was created.

Push to Template

Example Request:

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": "all",
    "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": ""
        }
    }
}

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
Content-Length: 123
Data-Attribute: push_ids

{
    "ok" : true,
    "operation_id" : "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6"
    ]
}
POST /api/templates/push

Send a push notification to a specified device or list of devices using a template. The body of the request must be one of:

JSON Parameters

audience
Required. An audience object.
device_types
Required. An array of device types.
merge_data
Required, a Template Selector.

Response Codes

202 Accepted
The push notification has been accepted for processing
406 Not Acceptable
The request could not be satisfied because the requested API version is not available.
Note

You must ensure that any variable with a null default value receives an override. 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.

 

Schedule a Template Push

Example Request:

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

[
    {
        "name": "Hello Bob",
        "schedule": {
           "scheduled_time": "2018-05-02T22:00:00Z"
        },
        "device_types": "all",
        "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": "2018-05-05T18:00:00Z"
        },
        "device_types": "all",
        "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"
            }
        }
    }
]

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
Content-Length: 123
Data-Attribute: schedule_urls

{
    "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" ]
        }
    ]
}
POST /api/templates/schedules

Schedule a push notification to be sent to a specified device or list of devices using a template. The body of the request must be one of:

JSON Parameters

name
An optional string name given to the scheduled push..
schedule
A schedule specification describing when to send the push.
audience
Required. An audience object identifying the target audience.
device_types
Required string or array of strings, a device types selector.
merge_data
Required, a Template Selector.

Response Codes

202 Accepted
The push notification has been accepted for processing
406 Not Acceptable
The request could not be satisfied because the requested API version is not available.

Validate

Example Request:

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": "all",
    "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": ""
        }
    }
}

Example Response:

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

{
    "ok" : true
}
POST /api/templates/push/validate

Accept the same range of payloads as /api/templates/push, but parse and validate only, without sending any pushes.

Response Codes

200 OK
The payload was valid.
406 Not Acceptable
The request could not be satisfied because the requested API version is not available.

Update Template

Example Request:

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!"
        }
    }
}

Example Response:

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

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}
POST /api/templates/(template_id)

Update a template to reflect any changes. Request body will contain a partially-defined template object.

Response Codes

200 OK
The template has been successfully updated.

Lookup Template

Example Request:

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

Example Response:

The body of the response will contain a template object.

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

{
    "ok" : true,
    "template": {
        "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "created_at": "2015-08-17T11:10:02Z",
        "modified_at": "2015-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!"
            }
        }
    }
}
GET /api/templates/(template_id)

Retrieve a template.

Response Body

template

Response Codes

200 OK
A template was found.
404 Not Found
A template with the given ID was not found.

List Templates

Example Request:

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

Example Response:

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

{
    "ok" : true,
    "count": 1,
    "total_count": 1,
    "templates": [
        {
            "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "created_at": "2015-08-17T11:10:01Z",
            "modified_at": "2015-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
}
GET /api/templates

List an application's templates.

Query Parameters

page
integer (optional) Specifies the desired page number. Defaults to 1.
page_size
integer (optional) Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.
sort
string (optional) Species the name of the field to sort results by. Defaults to created_at and may be one of created_at, modified_at, or last_used
order
string (optional) The direction of the sort. Specify asc for ascending, and desc for descending. Defaults to asc.

Response Body

count
The number of templates returned.
total_count
The total number of templates.
templates
An array of template objects.
next_page
A link to the next page of results, if available.
prev_page
A link to the previous page of results, if available.

Response Codes

200 OK
The request was successful.

Delete Template

Example Request:

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

Example Response:

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

{
    "ok": true,
    "operation_id": "a6394ff8-8a65-4494-ad06-677eb8b7ad6a"
}
DELETE /api/templates/(template_id)

Delete a template. A request body should not be included.

Response Codes

200 OK
The template with the given ID was deleted.
404 Not Found
No template with the given ID was found.

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 Request:

GET /api/regions/?limit=100&start=100 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

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

{
   "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": "2016-06-09T12:34:56",
           "updated_at": "2016-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"
           }
       }
   ]
}
GET /api/regions/?limit=(limit)&start=(start)

Get a paginated list of all regions. The result will be an array of Region Objects under the "regions" key.

Query Parameters

limit
Optional. If no limit is provided, a default page size of 100 will be used. A maximum page size of 1000 regions is enforced. Limits larger than that will return a 400 response.
start
Optional. When present, represents a zero-based integer offset into the ordered list of regions, useful for addressing pages directly.

Response Body

count
The number of regions returned.
regions
An array of region objects.
next_page
A link to the next page of results, if available.

Response Codes

200 OK
The request was successful.
400 Bad Request
A limit specified larger than the maximum page size of 1000 regions will return a 400 response.

See Region Data Formats for JSON parameters.

Region Lookup

Example Request:

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

Example Response:

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

{
    "ok": true,
    "region": {
        "region_id": "7dbd9a5c-eff5-40f2-b648-4352c1668878",
        "created_at": "2016-08-24T23:15:22.900",
        "updated_at": "2016-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"
        }
    }
}
GET /api/regions/(region_id)

Get the detail for a specific region, as described by a Region Object.

Response Body

region

Response Codes

200 OK
The request was successful.

Custom Events

User events that occur outside of your app can be submitted to Urban Airship:

When we talk about events that occur outside of your app, the scope is vast. 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 may be submitted as an Urban Airship custom event.

Retail example: You have identifed a user who browsed an item in your app while on her commute home, but waited until the evening to purchase the item on her laptop. You would like to tie these actions together so that you have a complete picture of the actions leading to this purchase:

  • Browsed item (in-app)

  • Added to cart (authenticated on website)

  • Purchased item (via website)

In this example, you can use an event template in the SDK to record the browsed action. The added-to-cart and purchase actions are submitted to Urban Airship along with the channel ID via the server-side custom events API endpoint. If the purchase event didn't occur, you could have used the added-to-cart event to trigger a reminder notification, either canceling it or changing it to a thank you message in when the purchase event occurs.

Add Custom Events

Example Single Event Request:

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

{
   "occurred": "2016-05-02T02:31:22",
   "user": {
      "android_channel": "e393d28e-23b2-4a22-9ace-dc539a5b07a8"
   },
   "body": {
      "name": "purchased",
      "value": 120.49,
      "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a",
      "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
      "interaction_type": "url",
      "properties": {
         "category": "mens shoes",
         "id": "pid-11046546",
         "description": "sky high",
         "brand": "victory"
      },
      "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
   }
}

Example Response:

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

{
   "ok": true,
   "operation_id": "8c61c0c4-95b0-45a6-bc38-733f7fcb8979"
}

Example Batch Request:

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

[
   {
      "occurred": "2016-05-02T02:31:22",
      "user": {
         "android_channel": "e393d28e-23b2-4a22-9ace-dc539a5b07a8"
      },
      "body": {
         "name": "purchased",
         "value": 120.49,
         "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a",
         "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
         "interaction_type": "url",
         "properties": {
            "category": "mens shoes",
            "id": "pid-11046546",
            "description": "sky high",
            "brand": "victory"
         },
         "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
      }
   },
   {
      "occurred": "2016-06-09T05:20:12",
      "user": {
         "android_channel": "e393d28e-23b2-4a22-9ace-dc539a5b07a8"
      },
      "body": {
         "name": "purchased",
         "value": 100.00,
         "transaction": "12536473-3e0f-46d7-930e-abc345261722",
         "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
         "interaction_type": "url",
         "properties": {
            "category": "mens shoes",
            "id": "pid-11312678",
            "description": "low top",
            "brand": "street"
         },
         "session_id": "22404b07-3f8f-4e42-a4ff-123231233122"
      }
   }
]

Example Response:

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

{
   "ok": true,
   "operation_id": "8c61c0c4-95b0-45a6-bc38-733f7fcb8979"
}
POST /api/custom-events

Submit an externally-generated custom event, associated with a channel ID, to Urban Airship. Events are associated with the given channel and available to use as Custom Event Triggers.

Note

Notes:

  • The request does complete validation before returning a response.
  • It is authenticated with a bearer token which can provide access to this resource alone, or to this resource and others.
  • It is rate limited to 500 events per second per app.
  • The name value inside body must not contain any uppercase characters, or the event will be rejected with a 400 status code.

The body of the request must be one of:

Request Headers

Authorization
Server-side custom events use bearer HTTP authentication. The token is distributed by Urban Airship and may be revoked at will. Go to Settings » APIs & Integrations » Custom Event Tokens to generate your token.
X-UA-Appkey
Required. The UA application key with which we should associate this event
Accept
The Accept header MUST be application/vnd.urbanairship+json; version=3

Response Body

ok
ok is a boolean indicating whether or not the request was successful.
operation_id
Denotes the API interaction concluded by this response. It can be used in support requests if something goes wrong.

Channels

Channels are Urban Airship's unique identifiers for addressing applications on iOS, Android, Amazon, and web devices. To learn more about Channels, see: Channels Primer.

Channel Lookup

Example Request:

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

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "ok": true,
   "channel": {
      "channel_id": "01234567-890a-bcde-f012-3456789abc0",
      "device_type": "ios",
      "installed": true,
      "opt_in": false,
      "background": true,
      "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
      "created": "2013-08-08T20:41:06",
      "last_registration": "2014-05-01T18:00:27",
      "named_user_id": "some_id_that_maps_to_your_sytems",
      "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"
      }
   }
}

Get information on an individual channel.

GET /api/channels/(channel_id)

Query Parameters

channel_id
The ID of the channel to look up.

Response Body

channel

Response Codes

200 OK
Returned on success, with the JSON representation of the channel in the body of the response.
404 Not Found
The channel does not exist.
Note

For more information on Channels, see Channels Primer.

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 lookup the Named User associated with the channel.

Channel Listing

Example Request:

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

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "next_page": "https://go.urbanairship.com/api/channels?start=07AAFE44CD82C2F4E3FBAB8962A95B95F90A54857FB8532A155DE3510B481C13&limit=2",
   "channels": [
      {
         "channel_id": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
         "device_type": "ios",
         "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
         "opt_in": true,
         "installed": true,
         "background": true,
         "created": "2014-03-06T18:52:59",
         "last_registration": "2014-10-07T21:28:35",
         "named_user_id": "some_id_that_maps_to_your_sytems",
         "alias": "your_user_id",
         "tags": [
            "tag1",
            "tag2"
         ],
         "tag_groups": {
            "tag_group_1": ["tag1", "tag2"],
            "tag_group_2": ["tag1", "tag2"]
         },
         "ios": {
            "badge": 2,
            "quiettime": {
               "start": "22:00",
               "end": "8:00"
            },
            "tz": "America/Los_Angeles"
         }
      },
      {
         "channel_id": "bd36e8c7-5a73-47c0-9716-99fd3d4197d5",
         "device_type": "ios",
         "push_address": null,
         "opt_in": false,
         "installed": true,
         "background": true,
         "created": "2014-03-06T18:52:59",
         "last_registration": "2014-10-07T21:28:35",
         "named_user_id": "some_id_that_maps_to_your_sytems",
         "alias": "your_user_id",
         "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
         }
      }
   ]
}
GET /api/channels

Fetch channels registered to this application, along with associated data and metadata

Response Body

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.
channels
(Array of objects) An array of Channel Objects.

Response Codes

200 OK
Returned on success, with the JSON representation of the channels in the body of the response.
404 Not Found
The channels do not exist.
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 do a Named User listing.

Uninstall Channels

Example Request:

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": "00000000-0000-0000-0000-000000000000",
      "device_type": "ios"
   },
   {
      "channel_id": "00000000-0000-0000-0000-000000000001",
      "device_type": "ios"
   }
]

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "ok": true
}
POST /api/channels/uninstall

Mark the given Channels as uninstalled; uninstalled channels do not receive push or rich messages.

JSON Parameters

channel_id
The channel ID.
device_type
Valid values are "ios", "amazon", "android", "web", "open".

Response Codes

202 Accepted
The request has been accepted for processing.
Note

Uninstallation is handled automatically by our SDK and push systems. If an end user opens their app after this API marks the device as "uninstalled", it will automatically be set as "active" and "installed" again. This API is only useful for very specific scenarios. Before using this API endpoint, it is recommended that you first contact Urban Airship Support or your Account Manager to discuss your plans and intended use of this API endpoint.

Open Channels

Open Channels are custom communication channels that you can configure for messaging via the Engage platform, using the same segmentation and scheduling tools available on other supported platforms.

With Open Channels, you define a new open platform, e.g., SMS, Slack, Acme™ Smart Toasters, and register the new platform with Urban Airship. To set up an Open Channel, please see our Open Channels platform setup guide.

Below we will describe the endpoints for registering and updating users for your open platform, open channel lookup, and the specification for the Open Channel Object, delivery, and payload parameters.

If you are sending through the push API, platform overrides for open platforms are covered in the Open Channels Platform Overrides section.

Register New / Update Channel

Example Request:

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",
         "caprica"
      ],
      "timezone": "America/Los_Angeles",
      "locale_country": "US",
      "locale_language": "en",
      "open": {
         "open_platform_name": "cylon",
         "identifiers": {
            "model": "4"
         }
      }
   }
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Location: https://go.urbanairship.com/api/channels/df6a6b50-9843-0304-d5a5-743f246a4946

{
    "ok": true,
    "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}
POST /api/channels/open

Create a new open channel, or update a channel to reflect any changes. The body of the request will contain an Open Channel Object.

Use the /api/channels/open endpoint to register new channel identifiers for your audience or update an exsiting channel. The registration step is handled automatically in our mobile and web SDKs, but you are responsible for populating the Urban Airship system with users on open platforms.

Note

A 200 status will be returned if an existing channel was found for the specified open_platform_name and address. Otherwise a new channel will be created, also returning a 200 status.

Note

The master secret is required to update an open channel, otherwise a 401 Unauthorized response is returned.

JSON Parameters

Response Headers

Location
URI of the channel, used for later API calls.

Response Body

channel_id
Unique channel ID, used for pushing and other operations.

Response Codes

200 OK
An existing channel was found for the specified open_platform_name and address. Otherwise a new channel will be created.
429 Too Many Requests
If we are not ready to create a channel for this payload; e.g., if it is rate limited, then we will return a 429 Too Many Requests, which instructs the caller to wait before retrying the channel creation.

Open Channel Lookup

Example Request:

GET /api/channels/<channel_id> HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

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",
      "device_type": "open",
      "installed": true,
      "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"]
      },
      "created": "2017-08-08T20:41:06",
      "address": "example@example.com",
      "opt_in": true,
      "open": {
         "open_platform_name": "email",
         "identifiers": {
            "com.example.external_id": "df6a6b50-9843-7894-1235-12aed4489489"
         }
      },
      "last_registration": "2017-09-01T18:00:27"
   }
}
GET /api/channels/<channel_id>

Retrieve information about this channel.

Query Parameters

channel_id
The ID of the channel to look up.

Response Body

channel

Response Codes

200 OK
Returned on success, with the JSON representation of the channel in the body of the response.
404 Not Found
The channel does not exist.

Uninstall Open Channels

Example Request:

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

{
  "address": "Number Four",
  "open_platform_name": "cylon"
}

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;

{
  "ok": true
}
POST /api/channels/open/uninstall

Mark a single open channel uninstalled, without needing to know its channel ID. A 202 status will be returned on success.

Update a channel to set it to an uninstalled (non-addressable) state. Request body will contain a single open channel identifier, consisting of an address and open platform name.

JSON Parameters

address
Required String. Open channel delivery address.
open_platform_name
Required. Must be of a predefined open platform.

Response Codes

202 Accepted
The request has been accepted for processing.

Email

Register email channels, set opt-in status, and manipulate tags on email channels.

Register Email Channel

Example Request:

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

{
   "channel" : {
      "type": "email",
      "email_opt_in_level": "commercial",
      "address": "name@example.com",
      "timezone" : "America/Los_Angeles",
      "locale_country" : "US",
      "locale_language" : "en"
   }
}

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://go.urbanairship.com/api/channels/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd

{
    "ok": true,
    "channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd"
}
POST /api/channels/email

Create a new email channel or unsubscribe an existing email channel from receiving commercial emails. To unsubscribe an existing channel, set opt_in to false.

JSON Parameters

email_opt_in_level

String, required. Determines the types of emails a user has agreed to receive, corresponding to the message_type field in the email platform override object. Set to commercial, transactional, or none.

  • commercial: The user has agreed to receive promotional emails and transactional emails. This is an inclusive opt-in: channels with with this email_opt_in_level will receive emails with message_type set to either commercial or transactional.
  • transactional: The user has agreed to receive emails in response to interactions with your app or website, i.e. receipts, legal notices, and password resets. This user will only receive emails with message_type set to transactional.
  • none: The user has opted out of email communications entirely.
channel_id
String; response only. Unique channel ID, used for emailing and other operations.

Response Headers

Location
URI of the channel, used for later registrations.

Uninstall Email Channel

Example Request:

POST /api/channels/email/uninstall HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json

{
    "email_address": "name@example.com"
}

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;

{
    "ok": true
}
POST /api/channels/email/uninstall

The body of the request will contain an email address object.

Email Tags

Example Request:

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

{
   "audience": {
      "email_address": "name@example.com",
      "email_address": "another@example.com"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"],
   }
}
POST /api/channels/email/tags

Update an email channel and manipulate its tags. Operation is identical to the Channel Tags endpoint except that the audience object must contain at least one email_address.

SMS

Register SMS Channel

Example Request:

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

{
    "msisdn" : "15035556789",
    "sender": "12345",
    "opted_in": "2018-02-13T11:58:59"
}

Example Response (With opted_in):

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://go.urbanairship.com/api/channels/7c5d7328-9bb4-4ff7-86b0-96a5f1da5868

{
    "ok": true,
    "channel_id": "7c5d7328-9bb4-4ff7-86b0-96a5f1da5868"
}

Example Response (Without opted_in):

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "ok": true,
    "status": "pending"
}

Example Response (Project not configured with sender):

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "ok": false,
    "errors": "Unable to retrieve details for sender 12345 with app_key <application key>"
}
POST /api/channels/sms

Begin opt-in process of a new SMS channel. The body of the request must contain an msisdn (mobile phone number) and a sender (number to send messages to the channel from) key populated.

The sender must be a number the app is already configured to send from.

The opted_in key, when present, is a UTC datetime in ISO 8601 format. If provided this represents the time explicit permission was received from the user to receive messages, and a channel may be created immediately. The time provided must represent a time in the past. If this field is not present, no channel will be created and a message will be sent to the msisdn with instructions on how to opt in to receiving messages.

Note

Note: Avoid repeat registration attempts. Repeated registrations of the same msisdn and sender without an opted_in value will result in multiple opt-in instruction messages being sent to the msisdn.

Repeated registrations of the same msisdn and sender with an opted_in value will result in the same channel_id.

JSON Parameters

msisdn
Required string representing the user's phone number. Must be numeric characters only, without leading zeros. 15 digits maximum.
sender
Required string. The SMS sender ID provided by Urban Airship. Must be numeric characters only.
opted_in
Optional datetime in ISO 8601 format, representing the time explicit permission was received from the user to receive messages.
channel_id
Unique Channel ID for the SMS channel. Included when the request contains a valid opted_in value.
status
A response with a status key indicates that the channel has not been created. If the value is pending, the opted_in field was not provided in the request, and the channel will be created pending the user's affirmative response. If the value is invalid_sender, the Urban Airship project is not configured for the provided sender.

Response Headers

Location
URI of the channel, used for later registrations. Only included when opted_in is set.

Opt Out

Example Request:

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

{
    "sender": "12345",
    "msisdn": "15035556789"
}

Example Response:

HTTP/1.1 202 Accepted
Content-type: application/vnd.urbanairship+json; version=3;

{
    "ok": true
}
POST /api/channels/sms/opt-out

This will mark an SMS channel as opted-out (inactive) and it will not receive alerts even when they are addressed in the future. To opt the user back in, call the registration function above.

The body of the request must contain an SMS address object.

Uninstall SMS Channel

Example Request:

POST /api/channels/sms/uninstall HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json

{
    "sender": "12345",
    "msisdn": "15035551212"
}

Example Response:

HTTP/1.1 202 Accepted
Content-type: application/vnd.urbanairship+json; version=3;

{
   "ok": true
}
POST /api/channels/sms/uninstall

The body of the request must contain an SMS address object.

Used for GDPR compliance, intended for removing a phone number from Urban Airship. Use with caution. Uninstalling an SMS channel will prevent you from retrieving opt-in and opt-out history for the corresponding msisdn. If the uninstalled msisdn opts-in again, it will generate a new channel_id. The new channel_id cannot be reassociated with any opt-in information, tags, named users, insight reports, or other information from the uninstalled SMS channel.

SMS Channel Lookup

Example Request:

GET /api/channels/sms/15035551212/55555 HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3

Example Response:

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

{
   "ok": true,
   "channel": {
      "channel_id": "84e36d69-873b-4ffe-81cd-e74c9f002057",
      "device_type": "sms",
      "installed": true,
      "push_address": null,
      "named_user_id": null,
      "alias": null,
      "tags": [],
      "tag_groups": {
         "ua_channel_type": [
            "sms"
         ],
         "ua_sender_id": [
            "12345"
         ],
         "ua_opt_in": [
            "true"
         ]
      },
      "created": "2018-04-27T22:06:21",
      "opt_in": true,
      "last_registration": "2018-05-14T19:51:38"
   }
}
GET /api/channels/sms/<msisdn>/<sender>

Query Parameters

msisdn
Required string, the MSISDN (phone number) for the user.
sender
Required string, your Urban Airship-provided sender ID.

Named Users

A Named User is a proprietary identifier that maps customer-chosen IDs, e.g., CRM data, to Channels.

It is useful to think of a Named User as an individual consumer who might have more than one mobile device registered with your app. For example, Named User "john_doe_123" might have a personal Android phone and an iPad, on both of which he has opted in for push notifications. If you want to reach John on both devices, associate the Channel (device) identifiers for each device to the Named User "john_doe_123," and push to the Named User. Notifications will then fan out to each associated device.

You can use Named Users to:

  • Send messages

  • Manage tags

  • Query status

without needing to store the mapping of users to channels in a separate database. Urban Airship maintains the mapping as soon as the Named User record is created.

A Named User may be associated with multiple Channels, but a channel may only be associated to one Named User.

Association

Example Request: Associate an iOS channel with Named User

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

{
   "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
   "device_type": "ios",
   "named_user_id": "user-id-1234"
}

Example Response:

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

{
   "ok": true
}

Example Request:

Associate a Web channel with Named User (Do not declare device type)

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

{
   "channel_id": "wf6a6b50-9843-0304-d5a5-743f246a4946",
   "named_user_id": "user-id-1234"
}

Example Response:

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

{
   "ok": true
}
POST /api/named_users/associate

Associate a channel to a named user ID. Generally you will call this endpoint after a succesful login in the client application.

Warning

If a channel has an assigned named user and you make an additional call to associate that same channel with a new named user, the original named user association will be removed and the new named user and associated data will take its place. Additionally, all tags associated to the original named user cannot be used to address this channel unless they are also associated with the new named user.

JSON Parameters

channel_id
(Required) The channel_id you would like to associate to a named user.
device_type
(Optional) The device type of the channel, e.g., ios, android, amazon. Do not specify device_type for web channels. The system is aware of web devices and it is not necessary to explicitly state them.
named_user_id
(Required) The id a user would like to give to the named_user.
Warning

You may only associate up to 50 Channels to a Named User. This limit is in place to prevent Urban Airship customers from using Named Users to function like Tags. It is highly unlikely that any one individual would have more than 50 devices registered with your app for notifications, so you should never encounter this limit. Please contact Support with questions.

Disassociation

Example Request:

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

{
   "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
   "device_type": "ios",
   "named_user_id": "user-id-1234"
}

Example Response:

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

{
   "ok": true
}
POST /api/named_users/disassociate

Disassociate a channel from a named user ID, if an association exists. Called after an explicit logout inside a mobile application.

JSON Parameters

channel_id
(Required) The channel_id you would like to disassociate from a named user.
device_type
(Optional) The device type of the channel, e.g., ios, android, amazon. Do not specify device_type for web channels. The system is aware of web devices and it is not necessary to explicitly state them.
named_user_id
(Optional) The existing named user ID association. Because channels can only have one named user association, this parameter is optional.

Lookup

Example Request:

GET /api/named_users/?id=(named_user_id) HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Data-Attribute: named_users
Link: <https://go.urbanairship.com/api/named_users?start=user-1234>; rel=next

{
   "ok": true,
   "named_user": {
      "named_user_id": "user-id-1234",
      "tags": {
         "crm": ["tag1", "tag2"]
      },
      "channels": [
         {
            "channel_id": "ABCD",
            "device_type": "ios",
            "installed": true,
            "opt_in": true,
            "push_address": "FFFF",
            "created": "2013-08-08T20:41:06",
            "last_registration": "2014-05-01T18:00:27",
            "alias": "xxxx",
            "ios": {
               "badge": 0,
               "quiettime": {
                  "start": "22:00",
                  "end": "06:00"
               },
               "tz": "America/Los_Angeles"
            }
         }
      ]
   }
}
GET /api/named_users/?id=(named_user_id)

Look up a single named user.

Query Parameters

id
(Required) The named user id.

Response Body

named_user

Response Codes

200 OK
Returned on success, with the JSON representation of the named user in the body of the response.
404 Not Found
The named user does not exist.

Listing

Example Request:

GET /api/named_users HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Data-Attribute: named_users
Link: <https://go.urbanairship.com/api/named_users?start=user-1234>; rel=next

{
   "next_page": "https://go.urbanairship.com/api/named_users?start=user-1234",
   "named_users": [
      {
         "named_user_id": "user-id-1234",
         "tags": {
            "crm": ["tag1", "tag2"]
         },
         "channels": [
            {
               "channel_id": "ABCD",
               "device_type": "ios",
               "installed": true,
               "opt_in": true,
               "push_address": "FFFF",
               "created": "2013-08-08T20:41:06",
               "last_registration": "2014-05-01T18:00:27",
               "alias": "xxxx",
               "tags": ["asdf"],
               "ios": {
                  "badge": 0,
                  "quiettime": {
                     "start": "22:00",
                     "end": "06:00"
                  },
                  "tz": "America/Los_Angeles"
               }
            }
         ]
      }
   ]
}
GET /api/named_users

Get a paginated list of all named users.

Response Body

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.
named_users
(Array of objects) An array of Named User Objects.

Response Codes

200 OK
Returned on success, with the JSON representation of the named users in the body of the response.
404 Not Found
The named users do not exist.

Tags

See: Tags: Named Users

Tags

Prior to the Urban Airship product release in Spring 2015, tag manipulation (addition, removal, setting of tags) was handled either on the client- or server-side, but not both. Tags set by the device would be overwritten by tags set from your server and vice versa.

With the release of Named Users and Tag Groups and in conjunction with Urban Airship's multi-platform device identifier, Channel IDs , tag manipulation is now fundamentally simpler and supports significantly more complex use-cases and integrations.

This reference covers API tag operations for Channels and Named Users, the two recommended approaches today. Reference is also provided below for the /api/tags/ endpoint, which must now be considered legacy.

Tags: Channels

Example Request:

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"]
   }
}

Example Response:

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"]
}
POST /api/channels/tags

Add or remove tags from channels, specified by the audience field. Tags set using the API must belong to a tag group. Before you can apply tags using the API, you must create tag groups to contain your tags via the dashboard. See the Tag Groups API Tutorial to learn about creating and using tag groups.

A single request must include an add or remove field, or both, or a single set field. If the same tag group and tag are present in both the add and remove fields, however, a HTTP 400 response will be returned.

When you add, remove, or set tags for a channel, you will specify the tag_group your tags belong to. Tags added to channels from this endpoint are grouped in arrays by tag group name within the channel's tag_groups object.

Note

Tags set client-side (through the SDK) appear in the channel's tags array.

JSON Parameters

audience
Required. The audience specifier should contain one or more channels to apply the tag operations to.
add
Optional. Add the list of tags to the given tag groups to the channel(s), but do not remove any. If the tags are already present, do not remove them.
remove
Optional. Remove the list of tags from the given tag groups from the channel(s), but do not remove any others. If the tags are not currently present, do nothing else.
set
Optional. Set the current list of tags on the given tag gropus to this list exactly; any previously set tags that are not in this current list should be removed.

Response Codes

200 OK
Returns OK for success. If a tag request is partially valid, i.e. at least one tag group exists and is active, a 200 will be 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 format.
403 Forbidden
Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the app does not permit associations from the device. Secure tag groups require master secret to modify tags, otherwise a 403 Forbidden response is returned.
Warning

The length of a tag must be < 128 characters. Tags greater than 128 will result in an HTTP 400 response.

Tag operations done by application secret can only be made to a single channel.

Tag set operations only update tag groups that are present in the request. Tags for a given Tag Group can be cleared by sending a set field with an empty list.

Secure Tag Groups require the master secret to modify tags, otherwise a 403 Forbidden response is returned.

If a tag update request contains tags in multiple Tag Groups, the request will be accepted if at least one of the Tag Groups is active. If inactive or missing Tag Groups are specified, a warning will be included in the response.

Note

tag_groups must be provisioned in the Urban Airship web application. See Settings: Tag Groups for details on setting up Tag Groups.

Audience selectors are all of the following forms:

{ "<type>" : "<id>" } or { "<type>" : ["<id1>", "<id2>",...] }

where <type> is one of:

  • amazon_channel

  • android_channel

  • ios_channel

  • channel (web channels and open channels)


Warning

Our system is designed to support up to 1000 tags per channel. Any number of tags beyond 1000 can cause latency and interruptions to service. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate.


Please contact Support if your use case requires more than 1000 tags per channel.

Previously, adding tags to a device using both the client and the server, via the legacy /api/tags/ endpoint, resulted in overwriting errors. (See Caution: Setting Tags From Different Sources.) The /api/channels/tags/ endpoint supports writing tags from the client- and server-side via Tag Groups.

Tags: Named Users

Example Request:

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

{
   "audience": {
      "named_user_id": ["user-1", "user-2", "user-3"]
   },
   "add": {
      "crm": ["tag1", "tag2", "tag3"],
      "loyalty": ["tag1", "tag4", "tag5"]
   },
   "remove": {
      "loyalty": ["tag6", "tag7"]
   }
}

Example Response:

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

{
   "ok": true
}
POST /api/named_users/tags

This endpoint allows the addition, removal, and setting of tags on a named user. A single request must include an add or remove field, or both, or a single set field. If a tag is present in both the add and remove fields, however, a HTTP 400 response will be returned.

Important

To prevent channels from getting into an unknown state, users should update named user tags using the named user tag endpoint only. Please do not update the same tag group using both /api/channels/tags/ and /api/named_users/tags.

JSON Parameters

audience
Required. The audience specifier should contain one or more channels to apply the tag operations to.
add
Optional. Add the list of tags to the given tag groups to the channel(s), but do not remove any. If the tags are already present, do not remove them.
remove
Optional. Remove the list of tags from the given tag groups from the channel(s), but do not remove any others. If the tags are not currently present, do nothing else.
set
Optional. Set the current list of tags on the given tag gropus to this list exactly; any previously set tags that are not in this current list should be removed.

Response Codes

200 OK
Returns OK for success. If a tag request is partially valid, i.e. at least one tag group exists and is active, a 200 will be 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 format.
403 Forbidden
Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the app does not permit associations from the device. Secure tag groups require master secret to modify tags, otherwise a 403 Forbidden response is returned.

Tag set operations only update tag groups that are present in the request. Tags for a given tag group can be cleared by sending a set field with an empty list.

Tags: Open Identifiers

Example Request:

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

 {
  "audience": {
      "address": "Number Six",
      "open_platform_name": "cylon"
  },
  "add": {
    "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
    "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
    "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
  }
 }

Example Response:

HTTP/1.1 200 Accepted
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
  "ok":true
}
POST /api/channels/open/tags

Manipulate a single open channel's tags, without needing to know its channel ID. A single request must include an add or remove field, or both, or a single set field. If a tag is present in both the add and remove fields, however, a HTTP 400 response will be returned.

JSON Parameters

address
Required String. Open channel delivery address.
open_platform_name
Required. Must be of a predefined open platform.
add
Add the list of tags to the channel(s), but do not remove any. If the tags are already present, do not remove them.
remove
Remove the list of tags from the channel(s), but do not remove any others. If the tags are not currently present, do nothing else.
set
Set the current list of tags to this list exactly; any previously set tags that are not in this current list will be removed.

Response Codes

200 OK
Returns OK for success. If a tag request is partially valid, i.e. at least one tag group exists and is active, a 200 will be 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 format.
403 Forbidden
Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the app does not permit associations from the device. Secure tag groups require master secret to modify tags, otherwise a 403 Forbidden response is returned.
Note

A 200 status will be returned on success.

Update a channel and manipulate its tags. Operation is identical to the /api/channels/tags/ endpoint except that the audience section must contain an open channel identifier, consisting of an address and open platform name.

Tags: Legacy

This reference is provided for customers using the /api/tags endpoint. If you are using this endpoint, we highly recommend transitioning to using tags on either Channels or Named Users (or both) in your implementation.

Tag Listing

Example Request:

GET /api/tags HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "tags": [
      "tag1",
      "some_tag",
      "portland_or"
   ]
}
GET /api/tags

List tags that exist for this application.

Note

Tag Listing will return up to the first 100 tags per application.

Tag Creation

Example Request:

PUT /api/tags/new_tag HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
PUT /api/tags/(tag)

Explicitly create a tag with no devices associated with it.

This call is optional; tags are created implicitly when devices are added to them. You might use this to pre-create the list for your dashboard users, however.

Response Codes

200
The tag already exists.
201
The tag was created.
400
The tag is invalid.
Warning

The only justification for using this endpoint is setting server tags on device identifiers other than channels. If you wish to use this endpoint with channels only, we strongly recommend that you use the new channels tag endpoint instead. The /api/channels/tags endpoint allows the specification of tag groups, circumventing the issue detailed in the previous warning.

Adding and Removing Devices from a Tag

Example Request:

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

{
   "ios_channels": {
      "add": [
         "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
         "9c36e8c7-5a73-47c0-9716-99fd3d4197d6"
      ]
   },
   "android_channels": {
      "remove": [
         "channel_1_to_remove"
      ]
   }
}

Full capability:

Any number of Channels, device tokens, or APIDs can be added or removed.

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

{
   "ios_channels": {
      "add": [
         "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
         "9c36e8c7-5a73-47c0-9716-99fd3d4197d6"
      ]
   },
   "device_tokens": {
      "add": [
         "device_token_1_to_add",
         "device_token_2_to_add"
      ],
      "remove": [
         "device_token_to_remove"
      ]
   },
   "apids": {
      "add": [
         "apid_1_to_add",
         "apid_2_to_add"
      ],
      "remove": [
         "apid_to_remove"
      ]
   }
}
POST /api/tags/(tag)

Add or remove one or more iOS, Android or Amazon channels (or device tokens, APIDs ) to a particular tag.

Response Codes

200
The devices are being added or removed from this tag.
401
The authorization credentials are incorrect
200
The devices are being added or removed from this tag.
401
The authorization credentials are incorrect

Caution: Setting Tags From Different Sources

Disable device-side tags Prior to Android 5.0 SDK:

PushManager.shared().setDeviceTagsEnabled(false);

Disable device-side tags Android SDK 5.0 or later:

UAirship.shared().getPushManager()
        .setDeviceTagsEnabled(false);


Android

For Android/Amazon devices, metadata set from the server will be overwritten or cleared by registrations from the SDK unless you turn off device-side tag setting:

iOS

In the iOS SDK, registration is handled for you automatically, which gives us any tags that are set on the device. Calling this API from a server might interfere with metadata if set differently. Specifically, if you set a tag from the API but are using the SDK, the SDK will clear the tag upon registration.

It is possible to disable tags being set by the SDK by setting deviceTagsEnabled to NO on iOS.

Deleting a Tag

Example Request:

DELETE /api/tags/some_tag HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 204 No Content
DELETE /api/tags/(tag)

Delete a tag and remove it from devices.

Response Codes

204
The tag has been removed.
401
The authorization credentials are incorrect
404
The tag was not found or has already been removed.

A tag can be removed from our system by issuing a delete. This will remove the master record of the tag. Additionally it will remove the tag from all devices with the exception of devices that are inactive due to uninstall. Devices that were uninstalled will retain their tags.

If at some point you want a tag that has been deleted with this API to show up in tag listings again, you will need to add it back with a PUT (see the tag creation API).

Note

The removal process can take a long time if many devices use this tag.

Batch modification of tags

Example Request:

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

{
  [
     {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
        "tags": [
           "tag_to_apply_1",
           "tag_to_apply_2"
        ]
     },
     {
        "device_token": "device_token_to_tag_1",
        "tags": [
           "tag_to_apply_1",
           "tag_to_apply_2",
           "tag_to_apply_3"
        ]
     },
     {
        "device_token": "device_token_to_tag_2",
        "tags": [
           "tag_to_apply_1",
           "tag_to_apply_4",
           "tag_to_apply_5"
        ]
     },
     {
        "apid": "apid_to_tag_2",
        "tags": [
           "tag_to_apply_1",
           "tag_to_apply_4",
           "tag_to_apply_5"
        ]
     }
  ]
POST /api/tags/batch

Modify the tags for a number of device tokens, channels, or apids.

Response Codes

200
The tags are being applied.
400
The batch tag request was invalid.
401
The authorization credentials are incorrect

You must include an object containing either an ios_channel, android_channel, amazon_channel, channel, device_token or apid section and also containing a tags section to apply the tags.

Each row of data will be validated to confirm that the device token, channel or APID is valid, and that a list of tags is present. For any row that does not match these validation requirements, an error response will be returned. The error response is an object, the errors member of which is an array of two-member arrays. The two-member arrays will contain the row that did not pass validation and the error response produced by our system. Note: the error messages are not normalized or machine-readable; they are currently just short strings meant to give the API caller enough information to debug the issue with the failed row. Note: we do not validate the existence of the APID, if one or more of the APIDs do not exist in our system the application of tags to those APIDs will silently fail.

Segments

Segments are portions of your audience that have arbitrary metadata (e.g. tags, location data, etc) attached. You can create, delete, update, or request information on a segment via the /api/segments/ endpoint. Pushing to a segment is done through the /api/push/ endpoint (see the Audience Selection section for more information).

Segment Listing

Example Request:

GET /api/segments/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Link: <https://go.urbanairship.com/api/segments?limit=1&sort=id&order=asc&start=3832cf72-cb44-4132-a11f-eafb41b82f64>;rel=next
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "next_page": "https://go.urbanairship.com/api/segments?limit=1&sort=id&order=asc&start=3832cf72-cb44-4132-a11f-eafb41b82f64",
   "segments": [
      {
         "creation_date": 1346248822221,
         "display_name": "A segment",
         "id": "00c0d899-a595-4c66-9071-bc59374bbe6b",
         "modification_date": 1346248822221
      }
   ]
}
GET /api/segments

List all of the segments for the application.

Response Headers

link
A link to the next page of results. If present, follow this URL to the next page of segments. Also available in the next_page value in the response body.

Response Body

next_page
A link to the next page of results. If present, follow this URL to the next page of segments. Also available in the Link header.

Individual Segment Lookup

Example Request:

GET /api/segments/00c0d899-a595-4c66-9071-bc59374bbe6b HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "criteria": {
      "and": [
         {
            "tag": "ipad"
         },
         {
            "not": {
               "tag": "foo"
            }
         }
      ]
   },
   "display_name": "A segment"
}
GET /api/segments/(segment_id)

Retrieve the definition of a single segment. If the segment is found, the JSON representation of the segment is returned in the body of the response. If the segment does not exist, an HTTP 404 response will be given.

Create Segment

Example Request:

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

{
   "display_name": "News but not sports",
   "criteria": {
      "and": [
         {"tag": "news"},
         {"not":
            {"tag": "sports"}
         }
      ]
   }
}

Example Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json;version=3
Location: https://go.urbanairship.com/api/segments/f35da41d-59c1-4106-a192-9594bd480cb6

{
   "ok": true,
   "segment_id": "f35da41d-59c1-4106-a192-9594bd480cb6",
   "operation_id": "1d154121-951f-45b9-896d-e70718b5865b"
}
POST /api/segments

Create a new segment.

JSON Parameters

display_name
Human readable name for this segment. This will be used in the dashboard.
criteria
Audience selection criteria. See audience selection for a detailed description.

Response Headers

Location
URI of the newly created segment.

Response Body

segment_id
ID for the new segment.
operation_id
Denotes the API interaction concluded by this response. It can be used in support requests if something goes wrong.

Response Codes

201
The segment was created.
Tip

If you are interested in creating segments using both mobile and non-mobile data, see: Tags and Named Users.

Update Segment

Example Request:

PUT /api/segments/00c0d899-a595-4c66-9071-bc59374bbe6b HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
   "display_name": "Entertainment but not sports",
   "criteria": {
      "and": [
         {"tag": "news"},
         {"not":
            {"tag": "entertainment"}
         }
      ]
   }
}

Example Response:

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


{
   "ok": true,
   "operation_id": "1f93ca85-b8fd-4833-8d1a-6e2b7f4ceea9"
}
PUT /api/segments/(segment_id)

Change the definition of the segment.

JSON Parameters

display_name
Human readable name for this segment. This will be used in the dashboard.
criteria
Audience selection criteria. See audience selection for a detailed description.

Response Body

operation_id
Denotes the API interaction concluded by this response. It can be used in support requests if something goes wrong.

Response Codes

200 OK
The segment was updated.
Warning

When editing a segment, be mindful of any scheduled pushes that target that segment. If you have a scheduled push that targets a segment, and you edit that segment some time after the push's creation, the push audience will not be updated to match the new segment. The scheduled push will be sent to the version of the segment that existed when the push was created, rather than the updated version.

For information on addressing this issue, please see the User Guide documentation.

Delete Segment

Example Request:

DELETE /api/segments/00c0d899-a595-4c66-9071-bc59374bbe6b HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 204 No Content
DELETE /api/segments/(segment_id)

Remove the segment.

Response Codes

204
The segment has been deleted.

Static Lists

With the Static List API endpoint, you can easily target and manage lists of devices that are defined in your systems outside of Urban Airship. Any list or grouping of devices for which the canonical source of data about the members is elsewhere is a good candidate for Static Lists, e.g., members of a customer loyalty program.

Getting started with Static Lists is easy. Simply:

  1. Create your list in the Urban Airship system

  2. Populate, update, view, delete lists

  3. Push to lists using Audience Selection

Read below for the Static List API reference and see our Static List API guide for further use-cases and examples.

Create List

Example Request:

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

{
   "name" : "platinum_members",
   "description" : "loyalty program platinum members",
   "extra" : {
      "key" : "value"
   }
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Location: https://go.urbanairship.com/api/lists/platinum_members

{
   "ok" : true
}
POST /api/lists

Create a static list. The body of the request will contain several of the list object parameters, but the actual list content will be provided by a second call to the upload endpoint.

JSON Parameters

name
(Required) User-provided name of the list, consists of up to 64 URL-safe characters.
description
(Optional) User-provided description of the list.
extra
(Optional) A dictionary of string keys to arbitrary JSON values.

Response Codes

201 Created
List created successfully.
409 Conflict
The app has reached the maximum number of allowed lists (error_code 40906). A list with that name already exists (error_code 40907). List is already processing recently uploaded CSV (error_code 40910).

Upload List

Example Request:

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

alias,stevenh
alias,marianb
ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634
named_user,SDo09sczvJkoiu
named_user,"gates,bill"

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;

{
   "ok" : true
}
PUT /api/lists/(name)/csv

Upload the actual list content.

Query Parameters

name
string (required). The name of the list.

Response Codes

202 Accepted
The list was uploaded successfully, and is now being processed.
400 Bad Request

This could mean one of several things, depending on the error code: contains too many identifiers.

400 Bad Request (error_code 40002)
CSV contains too many identifiers.
400 Bad Request (error_code 40003)
CSV contains an entry with a column count other than 2.
400 Bad Request (error_code 40004)
CSV contains an invalid identifier_type.
400 Bad Request (error_code 40005)
CSV contains a channel identifier that is not a valid UUID
404 Not Found
No list with the given name exists.
Warning

If an attempt to upload a list times out due to a poor connection, you must re-upload the list from scratch. Because we want to ensure that the entirety of a given list is successfully uploaded, we do not support partial list uploads.

List target identifiers are specified or replaced with an upload to this endpoint. Uploads must be newline delimited identifiers (text/CSV) as described in RFC 4180, with commas as the delimiter. The CSV format is two columns, identifier_type,identifier:

  • identifier_type: must be one of alias, named_user, ios_channel, android_channel, amazon_channel, web_channel, open_channel, sms_channel, or email_channel

  • identifier: the associated identifier you wish to send to

The maximum number of identifier_type,identifier pairs that may be uploaded to a list is 10 million.

Note

"Content-Encoding: gzip" is supported (and recommended) on this endpoint to reduce network traffic.

Update List

Example Request: The following example updates the platinum_members list's metadata:

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

{
   "name" : "platinum_members",
   "description" : "loyalty program platinum members",
   "extra" : {
      "key" : "value"
   }
}

Example Response:

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

{
   "ok" : true
}
PUT /api/lists/(name)

Update the metadata of a static list. The body of the request will contain a list object, though the name attribute could be omitted. If present, it must match the name provided in the URL.

Note

If you are trying to update the list contents, please see the list upload endpoint. The update endpoint is used to update a list's metadata rather than the actual list of device identifiers.

Query Parameters

name
string (required). The name of the list.

JSON Parameters

name
(Optional) User-provided name of the list, consists of up to 64 URL-safe characters.
description
(Optional) User-provided description of the list.
extra
(Optional) A dictionary of string keys to arbitrary JSON values.

Response Codes

200 Created
The list metadata was updated successfully.
400 Bad Request
Malformed JSON payload.
400 Bad Request (error_code 40001)
Attempted list rename. List renaming is not allowed.
404 Not Found
No list with the given name exists.

Single List

Example Request:

GET /api/lists/platinum_members/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Data-Attribute: static_list
Link: <https://go.urbanairship.com/api/platinum_members/list/?start=uuid101&limit=100>; rel=next

{
   "ok" : true,
   "name" : "platinum_members",
   "description" : "loyalty program platinum members",
   "extra" : { "key" : "value" },
   "created" : "2013-08-08T20:41:06",
   "last_updated" : "2014-05-01T18:00:27",
   "channel_count" : 1000,
   "status" : "ready"
}
GET /api/lists/(name)

Retrieve information about one static list, specified in the URL.

Query Parameters

name
string (required). The name of the list.

Response Body

Response Codes

200 OK
List retrieved successfully.
404 Not Found
No list with the given name exists.

When looking up lists, the returned information may actually be a combination of values from both the last uploaded list and the last successfully processed list. If you create a list successfully, and then you update it and the processing step fails, then the list status will read "failed", but the channel_count and last_modified fields will contain information on the last successfully processed list.

All Lists

Example Request:

GET /api/lists HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

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

{
   "ok" : true,
   "lists" : [
      {
         "name" : "platinum_members",
         "description" : "loyalty program platinum members",
         "extra" : { "key" : "value" },
         "created" : "2013-08-08T20:41:06",
         "last_modified" : "2014-05-01T18:00:27",
         "channel_count": 3145,
         "status": "ready"
      },
      {
         "name": "gold_members",
         "description": "loyalty program gold member",
         "extra": { "key": "value" },
         "created": "2013-08-08T20:41:06",
         "last_updated": "2014-05-01T18:00:27",
         "channel_count": 678,
         "status": "ready"
      }
   ]
}
GET /api/lists
GET /api/lists?type=(type)

Retrieve information about all static lists. This call returns a list of metadata that will not contain the actual lists of users. Optionally, provide the type of lists that you want to retrieve.

Query Parameters

type
string (optional). The type of lists to retrieve, defaults to "user" which is all user-generated lists. "all" specifies that all lists are returned. Other values will return specific types of generated lists. Valid types: "user", "all", "lifecycle".

Response Body

lists
(Array of objects) An array of List Objects.

Response Codes

200 OK
Lists retrieved successfully.

Delete a List

Example Request:

DELETE /api/lists/platinum_members HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 204 No Content
DELETE /api/lists/(name)

Delete a list.

Query Parameters

name
string (required). The name of the list.

Response Codes

204 No Content
List was deleted successfully.
404 Not Found
No list with the given name exists.
Warning

If you are attempting to update a current list by deleting it and then recreating it with new data, stop and go to the upload endpoint. There is no need to delete a list before uploading a new CSV file. Moreover, once you delete a list, you will be unable to create a list with the same name as the deleted list.

Feeds

The Feed API is used to add and remove RSS or Atom feeds used to trigger push notifications. For most users the API is unnecessary, and you should use the dashboard instead. For more information about feeds, see integrating feeds.

Creating a new feed

Example Request:

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

{
   "feed_url": "http://example.com/atom.xml",
   "template": {
      "audience": "all",
      "device_types": [ "ios", "android" ],
      "notification": {
         "alert": "Check this out! - {{ title }}",
         "ios": {
            "alert": "New item! - {{ title }}"
         }
      }
   }
}

Example Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
Location: https://go.urbanairship.com/api/feeds/SL_QBv8nT2yw5W9m_kDhQA/

{
   "feed_url": "http://example.com/atom.xml",
   "last_checked": null,
   "url": "https://go.urbanairship.com/api/feeds/SL_QBv8nT2yw5W9m_kDhQA/",
   "id": "SL_QBv8nT2yw5W9m_kDhQA",
   "api_version": "v3",
   "template": {
      "audience": "all",
      "device_types": [ "ios", "android" ],
      "notification": {
         "alert": "Check this out! - {{ title }}",
         "ios": {
            "alert": "New item! - {{ title }}"
         }
      }
   }
}

We only require two things be present in the data: the feed URL you wish to follow and your feed template.

We recommend checking the template with our feeds interface to see exactly how it performs.

POST /api/feeds/

JSON Parameters

feed_url
The full URL to the RSS or Atom feed.
template
A template for the API v3 push object.

Response Headers

Location
URI of the newly created feed.

Response Body

feed_url
The full URL to the RSS or Atom feed.
last_checked
The last time we saw a new entry for this feed.
url
The location of the feed entry. Can be used for altering or removing the feed later.
id
The newly created feed ID.
api_version
The API version.
template
A template for the API v3 push object.

Response Codes

201
The feed is now being monitored.

Feed details

Example Request:

GET /api/feeds/<feed_id>/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;charset=utf-8

{
   "feed_url": "<your_feed_url>",
   "last_checked": "2010-03-08 21:52:21",
   "url": "https://go.urbanairship.com/api/feeds/<feed_id>/",
   "id": "<feed_id>",
   "api_version": "v3",
   "template": {
      "audience": "all",
      "device_types": "all",
      "notification": {
         "alert": "New Item! - {{ title }}"
      }
   }
}
GET /api/feeds/(feed_id)/

Returns information about a particular feed.

Response Body

feed_url
The full URL to the RSS or Atom feed.
last_checked
The last time we saw a new entry for this feed.
url
The location of the feed entry. Can be used for altering or removing the feed later.
id
The newly created feed ID.
api_version
The API version.
template
A template for the API v3 push object.

Response Codes

200
The feed details is returned in the response body.

Updating a feed

Example Request:

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

{
   "template": {
      "audience": { "tag": "new_customer" },
      "device_types": [ "android" ],
      "notification": {
         "alert": "New item! - {{ title }}"
      }
   }
}

Example Response:

HTTP/1.1 200 OK
PUT /api/feeds/(feed_id)/

Updates a feed with a new template.

JSON Parameters

template
A template for the API v3 push object.

Response Codes

200
The feed update was successful.

Deleting a feed

Example Request:

DELETE /api/feeds/<feed_id>/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 204 No Content
DELETE /api/feeds/(feed_id)/

Removes a feed from the monitoring service, and stops new pushes from being sent.

Response Codes

204
The feed was deleted, and no content was returned.

Reports

Warning

The Statistics API at /api/push/stats is available to all customers.

The Urban Airship Reports APIs are available in only certain account plans. Please contact Support or your Account Manager if you are unable to use them for an app key that you believe is on an appropriate plan.

Experiment Overview Report

Example Response:

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

{
   "app_key": "some_app_key",
   "experiment_id": "a7806815-6483-4cb9-9d74-bc3b4f3dc1b8",
   "push_id": "cf8a3c64-568e-4ace-8d12-c494e14c3e73",
   "created": "2016-02-25 23:03:12",
   "sends": 532,
   "direct_responses": 50,
   "influenced_responses": 60,
   "variants": [
      {
         "id" : 0,
         "name": "call to action",
         "audience_pct": 45.0,
         "sends": 238,
         "direct_responses": 32,
         "direct_response_pct": 13.44,
         "indirect_responses": 0,
         "indirect_response_pct": 0.0
      },
      {
         "id" : 1,
         "name": "gentle reminder",
         "audience_pct": 45.0,
         "sends": 251,
         "direct_responses": 20,
         "direct_response_pct": 7.97,
         "indirect_responses": 4,
         "indirect_response_pct": 1.59
      }
   ],
   "control": {
     "audience_pct": 10.0,
     "sends": 50,
     "responses": 1,
     "response_rate_pct": 2.0
   }
}
GET /api/reports/experiment/overview/(push_id)

Returns statistics and metadata about an experiment (A/B Test). See: A/B Test.

Note

Use the push_id, not the experiment_id, to retrieve reporting data for experiments. Use the Experiment Lookup endpoint to retrieve the Push ID.

Response Body

experiment_id
ID for the requested experiment
variants
Single variant reporting object or array of variant reporting objects, including associated metadata, audience percentage and response statistics
control
JSON object describing the control group, i.e., those devices that receive no notification, for the experiment

Variant Detail Report

Example Response:

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

{
   "app_key": "some_app_key",
   "experiment_id": "a7806815-6483-4cb9-9d74-bc3b4f3dc1b8",
   "push_id": "cf8a3c64-568e-4ace-8d12-c494e14c3e73",
   "created": "2016-02-25 23:03:12",
   "variant": 1,
   "variant_name": "subjunctive mood",
   "sends": 58,
   "direct_responses": 15,
   "influenced_responses": 3,
   "platforms": {
      "android": {
         "direct_responses": 6,
         "influenced_responses": 2,
         "sends": 22
      },
      "ios": {
         "direct_responses": 9,
         "influenced_responses": 1,
         "sends": 36
      },
      "amazon": {
         "direct_responses": 0,
         "influenced_responses": 0,
         "sends": 0
      }
   }
}
GET /api/reports/experiments/detail/(push_id)/(variant_id)

Returns detailed stats and information about an individual variant from an experiment (A/B test).

Individual Push Response Statistics

Example Request:

GET /api/reports/responses/362b7e8d-af82-4a67-ac76-49e5ea2f7f59 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "push_uuid": "f133a7c8-d750-11e1-a6cf-e06995b6c872",
   "direct_responses": 45,
   "sends": 123,
   "push_type": "UNICAST_PUSH",
   "push_time": "2018-05-31 12:34:56",
   "open_channels_sends": {
      "platforms": [
         {
            "id": "PLATFORM_NAME_1",
            "sends": 13
         },
         {
            "id": "PLATFORM_NAME_2",
            "sends": 31
         },
         {
            "id": "PLATFORM_NAME_3",
            "sends": 26
         }
      ]
   }
}
GET /api/reports/responses/(push_id)

Returns detailed reports information about a specific push notification. Use the push_id, which is the identifier returned by the API that represents a specific push message delivery.

Query Parameters

push_id
The identifier that represents a specific push message delivery.

Response Body

push_uuid
The UUID for the requested push.
direct_responses
The number of native-platform direct responses to the notification measured by the SDK.
sends
The number of pushes sent to native mobile platforms, e.g., iOS. Exclusive of 'open_channel_sends', which are broken out under 'open_channel_sends'.
push_type
The string describes the push operation, which is often comparable to the audience selection. Possible values include: 'BROADCAST_PUSH', 'TAG_PUSH', 'SCHEDULED_PUSH', 'SEGMENTS_PUSH', 'UNICAST_PUSH'
push_time
The ISO 8601 timestamp in UTC indicating the time that the push was initially sent.
open_channels_sends
Returns an array of the number of send counts per open platform. If there were no open channels sends associated with the push ID, an empty result will be returned.
platforms
Array of objects indicating the total sends by open platform.
id
Key representing the canonical identifier in the Urban Airship system for the given open platform.
sends
The number of sends for the given push ID and the given open platform.

Response Codes

200 OK
Returned on success, with the JSON representation of the push statistics in the body of the response.

Devices Report API

Example Request:

GET /api/reports/devices/?date=2018-05-05%2010:00 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "total_unique_devices": 150,
   "date_computed": "2018-05-05 10:00:00",
   "date_closed": "2018-05-05 10:00:00",
   "counts": {
      "android": {
         "unique_devices": 50,
         "opted_in": 0,
         "opted_out": 0,
         "uninstalled": 10
      },
      "ios": {
         "unique_devices": 50,
         "opted_in": 0,
         "opted_out": 0,
         "uninstalled": 10
      }
   }
}
GET /api/reports/devices/?date=(Date)

Returns an app’s opted-in and installed device counts broken out by device type. This endpoint returns the same data that populates the Devices.

Query Parameters

date
All device events counted occurred before this ISO formatted timestamp.

Response Body

total_unique_devices
Sum of the unique devices for every device type.
date_computed
The date and time the device event data was tallied and stored.
date_closed
All device events counted occured before this date and time.
counts
The device counts broken out by device type.
unique_devices
Devices considered by Urban Airship Reports to have the app installed.
opted_in
Opted in to receiving push notifications.
opted_out
Opted out of receiving push notifications.
uninstalled
Devices for which Reports has seen an uninstall event.

Response Codes

200 OK
Returned on success, with the JSON representation of the device counts in the body of the response.

Push Report

Get the number of pushes you have sent within a specified time period.

Example Request:

GET /api/reports/sends/?start=2018-05-01%2010:00&end=2018-05-30%2020:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "sends": [
      {
         "android": 50,
         "date": "2018-05-01 00:00:00",
         "ios": 500
      }
   ],
   "next_page": "https://go.urbanairship.com/api/reports/..."
}
GET /api/reports/sends/?start=(date)&end=(date)&precision=(precision)

Query Parameters

start
Timestamp for start of report.
end
Timestamp for end of report.
precision
Granularity of results to return. Possible values: HOURLY, DAILY, MONTHLY.

Response Body

sends
An array of pushes sent to device types within the given datetime range and precision.
date
The date and time the pushes were sent.
next_page
There might be more than one page of results for this report. Follow this URL if it is present to the next batch of results.

Response Codes

200 OK
Returned on success, with the JSON representation of the sends in the body of the response.

Response Report

Example Request:

GET /api/reports/responses/?start=2018-05-01%2010:00&end=2018-05-30%2010:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "next_page": "https://go.urbanairship.com/api/reports/...",
   "responses": [
      {
         "android": {
            "direct": 25,
            "influenced": 118
         },
         "date": "2018-05-01 00:00:00",
         "ios": {
            "direct": 16,
            "influenced": 87
         }
      }
   ]
}
GET /api/reports/responses/?start=(date)&end=(date)&precision=(precision)

Get the number of direct and influenced opens of your app.

Query Parameters

start
Timestamp for start of report.
end
Timestamp for end of report.
precision
Granularity of results to return. Possible values: HOURLY, DAILY, MONTHLY

Response Body

responses
An array of direct and influenced opens within the given datetime range and precision.
date
The date and time the for direct and influenced opens.
next_page
There might be more than one page of results for this report. Follow this URL if it is present to the next batch of results.

Response Codes

200 OK
Returned on success, with the JSON representation of the responses in the body of the response.

Response Listing

Example Request:

GET /api/reports/responses/list?start=2018-05-01%2010:00&end=2018-05-10%2010:00&limit=20 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

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

{
   "next_page": ".../api/reports/responses/list?start=2017-08-01T00%3A00%3A00.000Z&end=2017-08-07T00%3A00%3A00.000Z&limit=25&push_id_start=3168bff6-7599-4e55-a599-2221f20d28c4&resume_at_time=20170804T230502.000Z",
   "pushes": [
      {
      "push_uuid": "f133a7c8-d750-11e1-a6cf-e06995b6c872",
      "push_time": "2018-05-06 23:43:28",
      "push_type": "UNICAST_PUSH",
      "direct_responses": 10,
      "sends": 123,
      "group_id": "04911800-f48d-11e2-acc5-90e2bf027020"
      }
   ]
}
GET /api/reports/responses/list?start=(date)&end=(date)&limit=(results_per_page)

Get a listing of all pushes, plus basic response information, in a given timeframe. Start and end date times are required parameters.

Query Parameters

start
Timestamp for start of report.
end
Timestamp for end of report.
limit
Number of results to return at one time (for pagination).
push_id_start
Begin with this id.

Response Body

next_page
There might be more than one page of results for this report. Follow this URL if it is present to the next batch of results.
pushes
An array of all pushes and its basic response information.
push_uuid
The UUID for the push.
push_time
The ISO 8601 timestamp in UTC indicating the time that the push was initially sent.
push_type
Describes the push operation, which is often comparable to the audience selection, e.g., BROADCAST_PUSH.
direct_responses
The number of native-platform direct responses to the notification measured by the SDK.
sends
The number of pushes sent to the native mobile platforms, e.g., iOS.
group_id
An identifier set by the server to logically group a set of related pushes, e.g., in a push to local time.

Response Codes

200 OK
Returned on success, with the JSON representation of the listing in the body of the response.

App Opens Report

Example Request:

GET /api/reports/opens/?start=2018-05-01%2010:00&end=2018-05-15%2020:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "opens": [
      {
         "android": 50,
         "date": "2018-05-01 00:00:00",
         "ios": 500
      }
   ],
   "next_page": "https://go.urbanairship.com/api/reports/..."
}
GET /api/reports/opens/?start=(date)&end=(date)&precision=(precision)

Get the number of users who have opened your app within the specified time period.

Query Parameters

start
Timestamp for start of report.
end
Timestamp for end of report.
precision
Granularity of results to return. Possible values: HOURLY, DAILY, MONTHLY.

Response Body

opens
An array of app opens within the given datetime range and precision.
date
The date and time of when the users opened the app.
next_page
There might be more than one page of results for this report. Follow this URL if it is present to the next batch of results.

Response Codes

200 OK
Returned on success, with the JSON representation of the app opens in the body of the response.

Time in App Report

Example Request:

GET /api/reports/timeinapp/?start=2018-05-01%2010:00&end=2018-05-15%2020:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "timeinapp": [
      {
         "android": 50,
         "date": "2018-05-01 00:00:00",
         "ios": 500
      }
   ],
   "next_page": "https://go.urbanairship.com/api/reports/..."
}
GET /api/reports/timeinapp/?start=(date)&end=(date)&precision=(precision)

Get the average amount of time users have spent in your app within the specified time period.

Query Parameters

start
Timestamp for start of report.
end
Timestamp for end of report.
precision
Granularity of results to return. Possible values: HOURLY, DAILY, MONTHLY.

Response Body

timeinapp
An array of average amount of time users have spent in the app within the given datetime range and precision.
date
The date and time of when the users have spent time in the app.
next_page
There might be more than one page of results for this report. Follow this URL if it is present to the next batch of results.

Response Codes

200 OK
Returned on success, with the JSON representation of the time in app in the body of the response.

Opt-in Report

Example Request:

GET /api/reports/optins/?start=2018-05-01%2010:00&end=2018-05-15%2020:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response

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

{
   "optins": [
      {
         "android": 50,
         "date": "2018-05-01 00:00:00",
         "ios": 500
      }
   ],
   "next_page": "https://go.urbanairship.com/api/reports/..."
}
GET /api/reports/optins/?start=(date)&end=(date)&precision=(precision)

Get the number of opted-in Push users who access the app within the specified time period.

Query Parameters

start
Timestamp for start of report.
end
Timestamp for end of report.
precision
Granularity of results to return. Possible values: HOURLY, DAILY, MONTHLY.

Response Body

optins
An array of opt-ins within the given datetime range and precision.
date
The date and time of when the users opt-in.
next_page
There might be more than one page of results for this report. Follow this URL if it is present to the next batch of results.

Response Codes

200 OK
Returned on success, with the JSON representation of the opt-ins in the body of the response.

Opt-out Report

Example Request:

GET /api/reports/optouts/?start=2018-05-01%2010:00&end=2018-05-15%2020:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "optouts": [
      {
         "android": 50,
         "date": "2018-05-01 00:00:00",
         "ios": 500
      }
   ],
   "next_page": "https://go.urbanairship.com/api/reports/..."
}
GET /api/reports/optouts/?start=(date)&end=(date)&precision=(precision)

Get the number of opted-out Push users who access the app within the specified time period.

Query Parameters

start
Timestamp for start of report.
end
Timestamp for end of report.
precision
Granularity of results to return. Possible values: HOURLY, DAILY, MONTHLY.

Response Body

optouts
An array of opt-outs within the given datetime range and precision.
date
The date and time of when the users opt-out.
next_page
There might be more than one page of results for this report. Follow this URL if it is present to the next batch of results.

Response Codes

200 OK
Returned on success, with the JSON representation of the opt-outs in the body of the response.

Custom Events Detail Listing

Example Request:

GET /api/reports/events?start=2018-05-01%2010:00&end=2018-05-15%2020:00&precision=MONTHLY&page=3&page_size=20 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
Link: https://go.urbanairship.com/api/reports/events...; rel="next"
Link: https://go.urbanairship.com/api/reports/events...; rel="prev"

{
   "events": [
      {
         "name": "custom_event_name",
         "location": "custom",
         "conversion": "direct",
         "count": 4,
         "value": 16.4
      },
      "..."
   ],
   "ok": true,
   "total_count": 12,
   "total_value": 321.2,
   "next_page": "https://go.urbanairship.com/api/reports/events...",
   "prev_page": "https://go.urbanairship.com/api/reports/events..."
}
GET /api/reports/events?start=(date)&end=(date)&precision=(precision)&page=(int)&page_size=(int)

Get a summary of custom event counts and values, by custom event, within the specified time period.

Query Parameters

start
Timestamp for start of report.
end
Timestamp for end of report.
precision
Granularity of results to return. Possible values: HOURLY, DAILY, MONTHLY.
page
(Optional) Identifies the desired page number. Defaults to 1. If page is given a negative or out of bounds value, the default value will be used.
page_size
(Optional) Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.

Response Body

name
The name of the custom event.
location
The source from which the event originates, e.g. Message Center, Landing Page, custom, etc.
conversion
Can be one of direct or indirect
count
Number of instances of this event.
value
The value generated by the event.
total_count
Sum of all the count fields in the above array.
total_value
Sum of all the value fields in the above array.

Response Codes

200 OK
Returned on success, with the JSON representation of the events in the body of the response.

Web Response Report

Example Request:

GET /api/reports/web/interaction/?app_key=ZGIwZTY3YjEtZTRiMi00ZG&start=2018-05-01%2010:00&end=2018-05-03%2020:00&precision=HOURLY HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

In this example, we would expect 48 total count objects given that the request calls for the counts over a two day period at hourly precision. Several have been left out for clarity.

{
   "app_key": "ZGIwZTY3YjEtZTRiMi00ZG",
   "end": "2018-05-03 00:00:00",
   "precision": "HOURLY",
   "start": "2018-05-01 00:00:00",
   "total_counts": [
      {"counts": {"clicks": 36, "sessions": 55 }, "date": "2018-05-01 10:00:00"},
      {"counts": {"clicks": 50, "sessions": 79 }, "date": "2018-05-01 11:00:00"},
      {"..."},
      {"..."},
      {"counts": {"clicks": 67, "sessions": 75 }, "date": "2018-05-03 20:00:00"}
  ]
}
GET /api/reports/web/interaction?app_key=(appKey)&start=(start_time)&end=(end_time)&precision=(precision)

Get the web interaction data for the given app key. Accepts a required start time and optional end time and precision parameters.

Note

Note: Currently the Web Response Report is the only endpoint available for retrieving Reports data for the web platform.

Query Parameters

app_key
Required, string, the app key for your web project.
start_time
Required, ISO UTC-formatted timestamp specifying the start of the count period.
end_time
Optional, ISO UTC-formatted timestamp specifying the end of the count period.
precision
Optional string, one of HOURLY, DAILY, or MONTHLY, specifying the desired precision for the counts. Default is HOURLY.

Response Body

total_counts
Array of total count objects, each representing counts within the given datetime range and precision.
date
ISO UTC formatted string for the count period.
counts
Object holding the number of counts for the given period.
clicks
Number of direct clicks on the web notification during the specified timeframe.
sessions
Number of sessions created during this timeframe. Sessions are created by site visits after 30 minutes of inactivity or by notification clicks that open the site.

Response Codes

200 OK
Returned on success, with the JSON representation of the web data in the body of the response.

Statistics

Example Request:

GET /api/push/stats/?start=2009-06-22&end=2009-06-22+06:00&format=csv" HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 OK
Content-Type: text/csv; charset=utf-8

2009-06-22 00:00:00,0,0,0,0,0,0,0
2009-06-22 01:00:00,0,0,4,0,0,0,0
2009-06-22 02:00:00,0,0,2,0,0,0,0
2009-06-22 03:00:00,0,0,1,0,0,0,0
2009-06-22 04:00:00,8,0,0,0,0,0,0
2009-06-22 05:00:00,1,0,0,0,0,0,0
GET /api/push/stats/?start=(start_time)&end=(end_time)

Return hourly counts for pushes sent for this application. Times are in UTC, and data is provided for each push platform.

Warning

Requests to /api/push/stats/ must be made without an Accept HTTP header that specifies an API version.

Note

The maximum time range that can be requested is 7 days. Requesting a larger range will result in a 400 status being returned, with an error message.

The statistics API is available for all applications.

In addition to JSON, the data is also available in CSV for easy importing into spreadsheets.

Mappings

Example Request:

GET /api/reports/mappings/send_ids/5ciT0WadEeOjtAAbIc5Dvb HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
  "send_id": "5ciT0WadEeOjtAAbIc5Dvb",
  "push_id": "17e6719c-af7f-41fe-bb50-06b33bc63a3e"
}
GET /api/reports/mappings/send_ids/(send_id)

The send_ids endpoint lets you look up the particular push ID associated with a given push received on a device.

Response Body

send_id
The send ID to use for lookup.

Response Codes

200
A push ID to send ID mapping.
400 Bad request
send_id malformed and could not be decoded.
404 Not Found
No push ID associated with the send ID.
Warning

send_id to push_id mappings are only available for sends that are less than 100 days old.

Example Request:

GET /api/reports/mappings/message_ids/5KzYeYGKwEeOHhgCQ9dZz4g HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
  "message_id": "KzYeYGKwEeOHhgCQ9dZz4g",
  "push_id": "2b361e60-62b0-11e3-8786-0090f5d673e2"
}
GET /api/reports/mappings/message_ids/(message_id)

The message_ids endpoint takes a message ID from a rich message and returns the equivalent push ID. The endpoint does not guarantee that a rich message corresponding to the message_id actually exists. For details on the rich message ID, see Message ID.

Response Body

message_id
The rich message ID to use for lookup.

Response Codes

code 200
A push ID to message ID mapping.
400 Bad request
message_id is malformed and could not be decoded.

Topics

Actions

Actions are specified by the actions attribute on a notification object

{
   "audience": "all",
   "notification": {
      "alert": "You got your emails!",
      "actions": {
         "add_tag": "MY_TAG"
      }
   },
   "device_types" : "all"
}

Example:

This actions object contains each of the possible action attributes.

{
   "actions": {
      "add_tag": "airship",
      "remove_tag": "boat",
      "share": "Check out Urban Airship!",
      "open": {
         "type": "url",
         "content": "http://www.urbanairship.com"
      },
      "app_defined": { "some_app_defined_action" : "some_value" }
   }
}

Actions are specified by the "actions" attribute on a notification object. See Push Object for more detail about the notification object.

Note

For information on how actions are handled within the client code within your app, see: iOS Actions and Android Actions.

The "actions" attribute MUST be an object as described in this section. The actions object can have the following five attributes:

Any combination of these attributes may be present. If any other attribute is present, an HTTP 400 response will be returned. Also, if no attributes are present, a 400 will be returned.

Add Tag

Examples:

Here we add a single tag:

{
   "actions": {
      "add_tag": "a_tag"
   }
}

Here we add several tags:

{
   "actions": {
      "add_tag": ["a_tag", "b_tag"]
   }
}

The "add_tag" attribute can be a single string or an array of strings. A null value, empty array, or any null values in the array will result in an HTTP 400 response. Duplicate tags in an array will not cause an error, but will have the same effect as if just a single instance of that tag was included.

Note

A single-element array will be passed to the client device (we do not turn it into a plain string).

Remove Tag

Example:

Here we remove a tag:

{
   "actions": {
      "remove_tag": "a_tag"
   }
}

Here we remove several tags:

{
   "actions": {
      "remove_tag": ["a_tag", "b_tag"]
   }
}

The "remove_tag" attribute can be a single string or an array of strings. A null value, empty array, or any null values in the array will result in an HTTP 400 response. Duplicate tags in an array will not cause an error, but will have the same effect as if just a single instance of that tag was included.

Note

A single-element array will be passed on to the client device (we do not turn it into a plain string).

Open

Example: "type": "url"

{
   "actions": {
      "open": {
         "type": "url",
         "content": "http://www.urbanairship.com"
      }
   }
}

Example: "type": "deep_link"

In the following example, note that the value for the "content" attribute, "prefs", is a string representing a common deep-linking use case: sending the user to the app's preferences page. This is not an out-of-the-box deep link; rather, it must be defined in your project. A fallback_url is provided for platforms that do not support deep linking.

{
   "actions": {
      "open": {
         "type": "deep_link",
         "content": "prefs",
         "fallback_url" : "https://www.urbanairship.com/settings"
      }
   }
}

Example: "type": "landing_page"

{
   "actions": {
      "open": {
         "type": "landing_page",
         "content": {
            "body": "<html>content</html>",
            "content_type": "text/html",
            "content_encoding": "utf-8",
         "fallback_url" : "https://www.urbanairship.com/settings"
         }
      }
   }
}

The "open" attribute is an object with two required attributes: type and content, and one optional attribute: fallback_url

  • "type" - string. MUST be one of: url, deep_link or landing_page:

    • When "type" is "url", "content" is a string, which must be a URL. null is not accepted. The URL must begin with either "http" or "https".

    • When "type" is "deep_link", "content" is a string, and must be non-blank. null is not accepted.

    • When "type" is "landing_page", "content" is a string, and must be a content object (see example).

  • "fallback_url" - The open object may have an optional "fallback_url" attribute, whose value can be used on platforms that don’t have full support for the otherwise defined action.


If the open object fails any of these conditions, an HTTP 400 will be returned. See the Deep Linking for iOS and Deep Linking for Android topic guides for information about defining these resources in your app.

Share

Example:

{
   "actions": {
      "share": "Check out Urban Airship!"
   }
}
Note

The share action is not currently supported for web notifications.

The "share" attribute must be a string if present. Anything else will return an HTTP 400 response.

In the following example, the text "Check out Urban Airship!" will populate the share feature for the user.

Action Mappings

Examples:

This is the short name equivalent of the top-level action add_tag:

{
   "actions": {
      "app_defined": {
         "^+t": "foo"
      }
   }
}

And here is the long name equivalent of the top-level "open" action for a "url":

{
   "actions": {
      "app_defined": {
         "open_external_url_action": "http://www.urbanairship.com"
      }
   }
}

This next example will result in an HTTP 400 because the app_defined action ^+t corresponds to the top-level action add_tag:

{
    "actions": {
        "add_tag": "foo",
        "app_defined": {
            "^+t": "bar"
        }
    }
}

This action will result in an HTTP 400 because the app_defined action ^p corresponds to the top-level open action for a landing page:

{
    "actions": {
        "open": {
            "type": "landing_page",
            "content": {
                "body": "foo",
                "content_type": "text/html"
            }
        },
        "app_defined": {
            "^p": "bar"
        }
    }
}

This action results in an error because the app_defined action add_tags_action maps to the top-level add_tag action:

{
    "actions": {
        "add_tag": "foo",
        "app_defined": {
            "add_tags_action": "bar"
        }
    }
}

This action will result in an HTTP 400 because the same key ("open") appears in both the app_defined and top-level action objects:

{
   "actions": {
      "open": {
         "type": "landing_page",
         "content": {
            "body": "foo",
            "content_type": "text/html"
         }
      },
      "app_defined": {
         "open": {
            "type": "deep_link",
            "content": "bar"
         }
      }
   }
}

Note: The preceding shows that even if a top-level open action seems to represent a different meaning than an app_defined open action, we still give an HTTP 400 due to duplicate key appearing on both objects.

This action will NOT result in an error. The top-level action opens a landing page ("open" : { "type" : "landing_page" }), but the app_defined action ^d corresponds to a deep-link open, not a landing page open:

{
   "actions": {
      "open": {
         "type": "landing_page",
         "content": {
            "body": "foo",
            "content_type": "text/html"
         }
      },
      "app_defined": {
         "^d": "bar"
      }
   }
}

Note: Even though you don't receive an error, since both of these are "open" actions, which one will actually be opened is unknown. One of them will most likely be dropped on the mobile device ( unless the app developer has overridden action handling in some way to deal with this).

This action will NOT result in an error, but is also problematic. The app_defined keys ^d and deep_link_action map to the same action on the device, but we do not translate any keys in the app_defined object, so no error occurs:

{
   "actions": {
      "app_defined": {
         "^d": "bar",
         "deep_link_action": "baz"
      }
   }
}

Only one of these will actually be included in the delivery to the mobile device and result in an action.

Most of the top-level actions described above also map to a short name and a long name on the mobile device. You can use these alternatives in your API requests if you include them under the app_defined object. If either the short name or the long name appears in the app_defined object, but the corresponding top-level key also appears, then an HTTP 400 error will be returned. However, no error occurs if the corresponding top-level key does not appear.

ActionShort NameLong Name
add_tag^+tadd_tags_action
remove_tag^-tremove_tags_action
open: { "type": "url", ... }^uopen_external_url_action
open: { "type": "deep_link", ... }^ddeep_link_action
open: { "type": "landing_page", ... }^planding_page_action

iOS, Extras and Actions

Examples:

This action will result in an HTTP 400 because the same key ("open") appears in the app_defined and extra objects:

{
   "notification": {
      "alert": "Boo",
      "ios": {
         "extra": {
            "open": "hello"
         }
      },
      "actions": {
         "app_defined": {
            "open": "goodbye"
         }
      }
   }
}

This action will give an HTTP 400 because the extra object carries a key that conflicts with the long name ("add_tags_action") for the add_tags action.

{
   "notification": {
      "alert": "Boo",
      "ios": {
         "extra": {
            "add_tags_action": "hello"
         }
      },
      "actions": {
         "add_tags": "hello"
      }
   }
}

The following example would also give an HTTP 400 because the "^+t" key on the extra object conflicts with short name for the add_tags action:

{
   "notification": {
      "alert": "Boo",
      "ios": {
         "extra": {
            "^+t": "hello"
         }
      },
      "actions": {
         "add_tags": "hello"
      }
   }
}

This action will NOT give an error, even though the extra object has a key ("add_tags_action") matching the long name for add_tags, because "add_tags" is not included as a top-level action:

{
   "notification": {
      "alert": "Boo",
      "ios": {
         "extra": {
            "add_tags_action": "hello"
         }
      },
      "actions": {
         "remove_tags": "hello"
      }
   }
}

This action will NOT give an error, even though the extra object has a ^+t key, because the "add_tags_action" key is included in the app_defined section, and therefore won't be translated to a short name:

{
   "notification": {
      "alert": "Boo",
      "ios": {
         "extra": {
            "^+t": "hello"
         }
      },
      "actions": {
         "app_defined": {
            "add_tags_action": "hello"
         }
      }
   }
}

On iOS, the extra object can conflict with top-level action names. If an extra key is the same as one of the long or short names specified in the Action Mappings section, and the corresponding top-level action is present, then an HTTP 400 will be returned.

Additionally, if an extras key is the same as a key on the app_defined object, an HTTP 400 will be returned.

Note

In the above case, the client device will most likely drop one of the actions, and the results will be indeterminate.

Actions payload for GCM and iOS



Examples:

Here is a push payload that adds a tag and alerts the user:

{
   "audience": "all",
   "notification": {
      "alert": "You got your emails!",
      "actions": {
         "add_tag": "MY_TAG"
      }
   },
   "device_types": ["ios", "android"]
}

The APNS payload sent to an iOS device will look like:

{
   "aps": {
      "alert": "You got your emails."
   },
   "^+t": "MY_TAG"
}

And the GCM payload sent to an Android device will look like (notice that the value of the actions key is a serialized JSON object):

Example:

{
   "registration_ids": [ "..."],
   "data": {
      "alert": "You got your emails!",
      "com.urbanairship.actions": "{\"^+t\" : \"MY_TAG\"}"
   }
}

Actions specify a payload that will be sent to the mobile device. Predefined actions use the mapping as specified in the action mappings section. This section details the specific payload sent to iOS and Android devices.

On iOS, action names map to keys at the top level of the payload, and arguments are any valid JSON fragment (as long as the targeted action supports those arguments).

On Android we can only send extras in the form of string-to-string key/value pairs. Therefore, we will send the "com.urbanairship.actions" key, whose value will be serialized JSON object mapping action names to argument values.

Web: Fallback URL

Example:

{
   "open" : {
       "type" : "deep_link",
       "content" : "prefs",
       "fallback_url" : "https://www.example.com/breaking-news"
   }
}
Important

Deep Link and Landing Page Actions are not currently supported for web push notifications.

When open "type" is either landing_page or deep_link, objects MAY have a "fallback_url" attribute, whose value can be used on platforms that don't have full support for the otherwise defined action.

See open in our API reference for detail on the open object in the Actions framework.

Interactive Notifications

Example:

This interactive object contains a pre-defined "type" with actions defined for each button.

{
   "interactive": {
      "type": "ua_yes_no_foreground",
      "button_actions": {
         "yes": {
            "add_tag": "more_cake_please",
            "remove_tag": "lollipop",
            "open": {
               "type": "url",
               "content": "http://www.urbanairship.com"
            }
         },
         "no": {
            "add_tag": "nope"
         }
      }
   }
}

Example:

This interactive object contains the pre-defined "ua_share" type with the share button action and text defined.

{
   "interactive": {
      "type": "ua_share",
      "button_actions": {
         "share": { "share": "Look at me! I'm on a boat." }
      }
   }
}

Interactive Notifications are specified by the "interactive" attribute in a notification object. The "interactive" attribute must be an object as described in this section. The interactive object may contain the following two attributes:

The type attribute is mandatory and the button_actions attribute is optional. If any other attribute is present, an HTTP 400 response will be returned. Attempting to specify an interactive payload on an unsupported device will result in an HTTP 400 response.

Type

The type field of the interactive object must be a string and specify either the name of one of the predefined interactive notifications or a custom defined interactive notification. Note that all predefined interactive notification types begin with the prefix "ua_", and custom defined interactive notification types must not begin with "ua_".

Button Actions

The button_actions field of the interactive object must be an object if present. The keys are the button IDs for the specified interactive notification type. If the notification type begins with "ua_", the keys must match exactly the button IDs for that type or a strict subset. The names of the button IDs cannot be validated for custom notifications. The values must be valid Actions objects as described in the Actions API documentation.

Message Center

Example: Message Object

{
   "audience": {
      "tag": [
         "tag1",
         "tag2"
      ]
   },
   "notification": {
      "alert": "New message!"
   },
   "message": {
      "title": "Message title",
      "body": "<html><body><h1>Your Title</h1>Your content</html>",
      "content_type": "text/html"
   }
}

For apps utilizing the Urban Airship Message Center, rich content may be optionally associated with a push notification by including a message object with your request.

Message Center Content

Message Center messages will automatically result in a badge update, even if the notification object is not included in the payload. This is default behavior. If you would like to turn off this behavior, contact Support or your technical account manager.

Message Center Object

Example:

{
   "audience": "all",
   "notification": {
      "ios": {
         "badge": "+1"
      }
   },
   "message": {
      "title": "This week's offer",
      "body": "<html><body><h1>blah blah</h1> etc...</html>",
      "content_type": "text/html",
      "expiry": "2015-04-01T12:00:00",
      "extra": {
         "offer_id": "608f1f6c-8860-c617-a803-b187b491568e"
      },
      "icons": {
         "list_icon": "http://cdn.example.com/message.png"
      },
      "options": {
         "some_delivery_option": true
      }
   }
}

The Message Center object may have the following attributes:

  • title — Required, string.

  • body — Required, string.

  • content_type or content-type — Optional, a string denoting the MIME type of the data in body. Defaults to "text/html".

  • content_encoding or content-encoding — Optional, a string denoting encoding type of the data in body. For example, utf-8 or base64. Defaults to utf-8 if not supplied. base64 encoding can be used in cases which would be complex to escape properly, just as HTML containing embedded JavaScript code, which itself may contain embedded JSON data.

  • expiry - The expiry time at which a Message Center message deletes from the user’s inbox or ceases to be delivered to user inboxes. Can be an integer encoding number of seconds from now, or an absolute timestamp in ISO UTC format. An integer value of 0 is equivalent to no expiry set. If the message has already expired at processing time, if a push is included with this message, neither the message nor the push will be sent.

  • extra — a JSON dictionary of string values. Values for each entry may only be strings. If you wish to pass structured data in an extra key, it must be properly JSON-encoded as a string.

  • icons — an optional JSON dictionary of string key and value pairs. At this time, only one key, "list_icon", is supported. Values must be URI/URLs to the icon resources. For resources hosted by UA, use the following URI format "ua:". For example: "icons" : { "list_icon" : "ua:9bf2f510-050e-11e3-9446-14dae95134d2" }

Message ID

Message IDs generated by the API are in the form of web-safe base64-encoded UUIDs, which are 22 characters in length. For example, "hpkAHEIAAAl6wn2h6yUR4g".

When a rich message is accompanied by a push notification, the ID of the rich message will be added to the notification payload that is sent to the device for any platform that supports extra (currently iOS, Android, Amazon) as the value of the key "_uamid". This will be a root level key in the iOS payload, and a member of the "extra" map for Android and Amazon.

For iOS, this reduces the number of bytes available for the APNS alert payload from 2000 to 1966 (by adding, e.g., ,"_uamid":"hpkAHEIAAAl6wn2h6yUR4g" to the APNS payload).

Delete Rich Message From Inbox

Example Request:

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

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;

{
   "ok": true
}
DELETE /api/user/messages/(push_id)

Delete a Message Center message completely, removing it from every user’s inbox. This is an asynchronous call; as such, 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.

It will not work with a group_id from an automated message or a push to local time delivery. To delete rich messages that were part of automated or local time deliveries, you must use relevant push_id (s) from the operation.

Note

For time-sensitive messages you should consider including an expiry time, as detailed in Message Center Object. Using the expiry key will render this method unnecessary but this is a good option to have in case of error or anything that renders an existing message obsolete or inaccurate.

Local Time Delivery

Example Request:

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

{
   "schedule": {
      "local_scheduled_time": "2015-04-01T12:00:00"
   },
   "push": {
      "audience": "all",
      "notification": { "alert" : "OH HAI FUTURE PEOPLEZ" },
      "device_types": "all"
   }
}

Push to Local time is an option, when scheduling a push, to have it delivered at the same time of day across all time zones in your app's audience, around the world. If your application uses our library and has analytic events turned on, you can schedule a push to each device's local time by specifying local_scheduled_time in the schedule object when creating the schedule. The push will then arrive for that device or set of devices at local time, instead of UTC (as is the case with other scheduled pushes). This feature is available only on iOS and Android, and requires the integration of the library in your app. For more details, please see Push to Local Time.

Note

In order to be able to use Local Time Delivery, you must have Analytic Events turned on and integrated into your application. See iOS: Analytics and Reporting and Android: Analytics and Reporting for more information.

Note

A message delivered to local time includes a Delivery by Time Zone section in its message report. See: Message Reports: Delivery by Time Zone.

Tip

The dashboard equivalent of Push to Local Time is Delivery By Time Zone in the Message workflow. See: Message Workflow Tutorial: Delivery: Scheduled.

Device Information

Note

If you are looking for Channel information, please see the Channels section.

The Device Information API can be queried for information on either a specific device identifier or the full list of devices registered to your app.

Either type of request (Individual Device Lookup, Device listing) will return a device identifier object (or array of objects) containing data and metadata related to each identifier.

Device Identifier Objects

Each device identifier has an associated JSON object, which contains data and metadata about the device.

Device Token Object

{
   "device_token": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
   "active": true,
   "alias": "your_user_id",
   "tags": [
      "tag1",
      "tag2"
   ],
   "created": "2013-08-08 20:41:06",
   "last_registration": "2014-05-01 18:00:27",
   "badge": 2,
   "quiettime": {
      "start": "22:00",
      "end": "8:00"
   },
   "tz": "America/Los_Angeles"
}

JSON Parameters

  • device_token – (String) The APNs identifier associated to this device
  • active – (Boolean) Status of the device token. We do not push to inactive device tokens.
  • alias – (String) Displays the alias associated with this device token, if one exists.
  • tags – (Array of strings) A list of tags associated with this device token.
  • created – (String) The creation date of this device token.
  • last_registration – (String) Displays the last registration date of this device token, if it is known.
  • badge – (Integer) Your app's current badge value on this device
  • quiettime – (Object) Quiet time specifications
  • tz – (String) The timezone associated with this device.

    APID Object

{
   "apid": "11111111-1111-1111-1111-111111111111",
   "active": true,
   "alias": "",
   "tags": [
      "tag1",
      "tag2"
   ],
   "created": "2013-03-11 17:49:36",
   "last_registration": "2014-05-01 18:00:27",
   "gcm_registration_id": "your_gcm_reg_id"
}

JSON Parameters

  • apid – (String) The GCM identifier associated with this device.
  • active – (Boolean) Status of the APID. We do not push to inactive APIDs.
  • alias – (String) Displays the alias associated with this APID, if one exists.
  • tags – (Array of strings) A list of tags associated with this APID.
  • created – (String) The creation date of this APID.
  • last_registration – (String) Displays the last registration date of this APID, if it is known.
  • gcm_registration_id – (String) The GCM registration ID associated with your application.

Individual Device Lookup

Get information about an individual device using its device token, APID, or PIN.

Device Token Lookup

Example Request:

GET /api/device_tokens/FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660 HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "device_token": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
   "active": true,
   "alias": "your_user_id",
   "tags": [
      "tag1",
      "tag2"
   ],
   "created": "2013-08-08 20:41:06",
   "last_registration": "2014-05-01 18:00:27",
   "badge": 2,
   "quiettime": {
      "start": "22:00",
      "end": "8:00"
   },
   "tz": "America/Los_Angeles"
}
GET /api/device_tokens/(device_token)

Get information on a particular iOS device token.

Return Value

A Device Token Object.

Note

For iOS devices, we recommend transitioning to Channels as your primary identifier. Channels are available today for iOS apps using at minimum the 4.0 version of the Urban Airship SDK. See Channels Primer for more information.

APID Lookup

Example Request:

GET /api/apids/11111111-1111-1111-1111-111111111111 HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "apid": "11111111-1111-1111-1111-111111111111",
   "active": true,
   "alias": "",
   "tags": [
      "tag1",
      "tag2"
   ],
   "created": "2013-03-11 17:49:36",
   "last_registration": "2014-05-01 18:00:27",
   "gcm_registration_id": "your_gcm_reg_id"
}
GET /api/apids/(APID)

Get information on a particular Android APID.

Return Value

An APID Object.

Device listing

Fetch device identifiers and associated data and metadata.

Device Token Listing

Example Request:

GET /api/device_tokens HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "next_page": "https://go.urbanairship.com/api/device_tokens/?start=07AAFE44CD82C2F4E3FBAB8962A95B95F90A54857FB8532A155DE3510B481C13&limit=2",
   "device_tokens_count": 87,
   "device_tokens": [
      {
         "device_token": "0101F9929660BAD9FFF31A0B5FA32620FA988507DFFA52BD6C1C1F4783EDA2DB",
         "active": false,
         "alias": null,
         "tags": []
      },
      {
         "device_token": "07AAFE44CD82C2F4E3FBAB8962A95B95F90A54857FB8532A155DE3510B481C13",
         "active": true,
         "alias": null,
         "tags": ["tag1", "tag2"]
      }
   ],
   "active_device_tokens_count": 37
}
GET /api/device_tokens

Fetch iOS device tokens registered to this application, along with associated data and metadata

Response Body

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.
device_tokens_count
(Integer) The full count of device tokens registered to this app, both active and inactive.
device_tokens
(Array of objects) An array of .
active_device_tokens_count
(Integer) The number of active device tokens associated with this app.
Note

You may now encounter Channels (e.g., "9c36e8c7-5a73-47c0-9716-99fd3d4197d5") in the next page URLs for this endpoint. This is expected behavior resulting from our back-end migration of device tokens to Channels as primary push identifiers. Calls to this endpoint should still work as expected as long as your code is dynamically getting to the next page based on the given URL.

APID Listing

Example Request:

GET /api/apids HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

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

{
   "next_page": "https://go.urbanairship.com/api/apids/?start=11111111-1111-1111-1111-111111111111&limit=2000",
   "apids": [
      {
         "c2dm_registration_id": null,
         "created": "2012-04-25 23:01:53",
         "tags": [],
         "apid": "00000000-0000-0000-0000-000000000000",
         "alias": null,
         "active": false
      },
      {
         "c2dm_registration_id": null,
         "created": "2013-01-25 00:55:06",
         "tags": [
            "tag1"
         ],
         "apid": "11111111-1111-1111-1111-111111111111",
         "alias": "alias1",
         "active": true
      }
   ]
}
GET /api/apids

Fetch Android APIDs registered to this application, along with associated metadata

Response Body

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.
apids
(Array of objects) An array of .

Location

Location Boundary Information

Name Lookup

Example Request:

GET /api/location/?q=San%20Francisco&type=city HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "features": [
      {
         "bounds": [
            37.63983,
            -123.173825,
            37.929824,
            -122.28178
         ],
         "centroid": [
            37.759715,
            -122.693976
         ],
         "id": "4oFkxX7RcUdirjtaenEQIV",
         "properties": {
            "boundary_type": "city",
            "boundary_type_string": "City/Place",
            "context": {
               "us_state": "CA",
               "us_state_name": "California"
            },
            "name": "San Francisco",
            "source": "tiger.census.gov"
         },
         "type": "Feature"
      }
   ]
}
GET /api/location/?q=(query)&type=(boundary_type)

Search for a location boundary by name. The search primarily uses the location names, but you can also filter the results by boundary type. For a full reference, please see our Boundary Types and Aliases Catalog. Because there are over 2.5M location boundaries available in Segments, we recommend you provide a type parameter along with your search to increase the chance you find the polygon you're looking for. If you are not getting satisfactory results with searching for a location by name, you may want to consider using "Search for location by latitude and longitude" or "Search for location by bounding box" below.

Query Parameters

q
Text search query.
type
Optional location type, e.g. city, province, or country.

Response Body

features
features that match the query.
Note

Due to contractual obligations we do not return proprietary datasets such as Maponics Neighborhood Boundaries or Nielsen DMA© in this endpoint. You can, however, search for those locations using the web interface.

Lat/Long Lookup

Example Request:

GET /api/location/37.7749295,-122.4194155?type=city HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "features": [
      {
         "bounds": [
            37.63983,
            -123.173825,
            37.929824,
            -122.28178
         ],
         "centroid": [
            37.759715,
            -122.693976
         ],
         "id": "4oFkxX7RcUdirjtaenEQIV",
         "properties": {
            "boundary_type": "city",
            "boundary_type_string": "City/Place",
            "context": {
               "us_state": "CA",
               "us_state_name": "California"
            },
            "name": "San Francisco",
            "source": "tiger.census.gov"
         },
         "type": "Feature"
      }
   ]
}
GET /api/location/(latitude),(longitude)?type=(boundary_type)

Search for a location by latitude and longitude. For example, if you have (latitude: 37.7749295, longitude: -122.4194155), you could systematically convert those coordinates to the surrounding city (San Francisco) or the surrounding ZIP code (94103).

Query Parameters

type
Optional location type, e.g. city, province, or country.

Response Body

features
that match the query.

Bounding Box Lookup

Example Request:

GET /api/location/37.805172690644405,-122.44863510131836,37.77654930110633,-122.39404678344727?type=postalcode HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "features": [
      {
         "bounds": [
            37.758749999999999,
            -122.477411,
            37.778851000000003,
            -122.428426
         ],
         "centroid": [
            37.769751999999997,
            -122.448239
         ],
         "id": "191QgPcnG1Um9MW06h1fa6",
         "properties": {
            "aliases": {
               "us_zip": "94117"
            },
            "boundary_type": "postalcode",
            "boundary_type_string": "Postal/ZIP Code",
            "name": "94117",
            "source": "tiger.census.gov"
         },
         "type": "Feature"
      }
   ]
}
GET /api/location/(latitude_1),(longitude_1),(latitude_2),(longitude_2)&type=(boundary_type)

Search for locations using a bounding box. A bounding box is a rectangle that covers part of the earth. For example, you could say "give me all the ZIP codes in this area". This may be useful if you want to create Segments that cover multiple locations nearby a certain area.

Alias Lookup

Example Request:

GET /api/location/from-alias?us_state=CA HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "bounds": [
      32.528832,
      -124.482003,
      42.009517,
      -114.131211
   ],
   "centroid": [
      37.215297,
      -119.663837
   ],
   "id": "5LajTWicgiQKuX1RBBLDRI",
   "properties": {
      "abbr": "CA",
      "aliases": {
         "fips_10-4": "US06",
         "hasc": "US.CA",
         "state": "US06",
         "us_state": "CA"
      },
      "boundary_type": "province",
      "boundary_type_string": "State/Province",
      "name": "California",
      "source": "tiger.census.gov"
   },
   "type": "Feature"
}
GET /api/location/from-alias?(query)

Look up location boundary information based on real-world references.

 

 

 

 

 

 

 

 

 

 

 

 

Example Request:

GET /api/location/from-alias?us_state=CA&us_state=OR&us_state=WA HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Multiple queries may be passed in one API call:

Polygon Lookup

Example Request:

GET /api/location/1H4pYjuEW0xuBurl3aaFZS?zoom=1 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response (Coordinates listing truncated):

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

{
   "type": "Feature",
   "id": "1H4pYjuEW0xuBurl3aaFZS",
   "properties": {
      "source": "tiger.census.gov",
      "boundary_type_string": "City/Place",
      "name": "Portland",
      "context": {
         "us_state_name": "Oregon",
         "us_state": "OR"
      },
      "boundary_type": "city"
   },
   "bounds": [
      45.432393,
      -122.83675,
      45.653272,
      -122.472021
   ],
   "centroid": [
      45.537179,
      -122.650037
   ],
   "geometry": {
      "coordinates": [
         [
            [
               [
                  -122.586136,
                  45.462439
               ],
               [
                  "..."
               ]
            ]
         ]
      ],
      "type": "MultiPolygon"
   }
}
GET /api/location/(polygonID)?zoom=(zoomLevel)

Use this call to query polygons for which you already know the ID, for information such as context, boundary type, centroid, bounds, and its geometry.

The zoom level determines the level of detail of the coordinates (higher numbers are zoomed out farther, so they include fewer coordinates/the shape is simplified).

Valid range for zoom level is 1 (least detailed) through 20 (most detailed).

The polygon ID is what is returned from other location API lookup calls, and is the unique identifier for that polygon.

Note

Due to contractual obligations we do not return proprietary datasets such as Maponics Neighborhood Boundaries or Nielsen DMA© in this endpoint. You can, however, search for those locations using the web interface.

Location Date Ranges

Example request:

GET /api/segments/dates/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;

Example Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8

[
   {
      "unit": "hours",
      "cutoff": "2012-07-09 15"
   },
   {
      "unit": "days",
      "cutoff": "2012-05-12"
   },
   {
      "unit": "weeks",
      "cutoff": "2012-W18"
   },
   {
      "unit": "months",
      "cutoff": "2008-07"
   },
   {
      "unit": "years",
      "cutoff": "2002"
   }
]
GET /api/segments/dates/

Retrieve cutoff dates for each time granularity.

The historical part of location is subject to some generous restraints. For example, you can't use per-hour granularity for locations from 8 weeks ago, but you can do per-day granularity for locations from 8 weeks ago. This endpoint retrieves the possible date range bucket types that can be used for date ranges with location predicates and the cutoff date for history available for each range. This defines what time ranges are legal in location predicates. For example, 8 weeks = 1344 hours. You cannot say "was in ZIP code 94123 in the past 1344 hours", but you can say "was in ZIP code 94123 in the past 56 days".

You can query based on the following time ranges:

  • By hour for the past 48 hours

  • By day for the past 60 days

  • By week for the past 10 weeks

  • By month for the past 48 months

  • By year for the past 10 years

Data Formats

Push Object

A Push Object contains the 6 top-level objects that describe a notification.

{
   "audience": {
      "OR": [
         {
            "tag": [
               "sports",
               "entertainment"
            ]
         },
         {
            "ios_channel": "871922F4F7C6DF9D51AC7ABAE9AA5FCD7188D7BFA19A2FA99E1D2EC5F2D76506"
         }
      ]
   },
   "notification": {
      "alert": "Hi from Urban Airship!",
      "ios": {
         "extra": {
            "url": "http://www.urbanairship.com"
         }
      }
   },
   "options": {
      "expiry": "2017-04-01T12:00:00"
   },
   "message": {
      "title": "Message title",
      "body": "<Your message here>",
      "content_type": "text/html"
   },
   "in_app": {
      "alert": "This part appears in-app!",
      "display_type": "banner",
      "expiry": "2015-04-01T12:00:00",
      "display": {
         "position": "top"
      }
   },
   "device_types": [ "ios", "wns", "android" ]
}

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:

  • "audience" - Required Audience Selector object.

  • "notification" - Required if "message" is not present, optional if so.

  • "device_types" Required. Can either be "all" or an array of one or more of the following values: "ios", "android", "amazon", "wns", "web", "email", "sms", or "open::<open_platform_name>"

  • "options" - Optional, a place to specify non-payload-specific delivery options for the push. See Push Options.

  • "in_app" - Optional, an In-App message

  • "message" - Optional, a Message Center message

  • "campaigns" - Optional, a Campaigns Object specifying custom campaign categories related to the notification.

Audience Selection

An audience selector forms the expression that determines the set of devices to which a notification will be sent. A valid audience selector is a JSON expression which can identify an app installation by means of one of the following four selector types:

  • Atomic selector

  • Compound selector

  • Location expression

  • Special selector


Atomic Selectors

Examples:

Push to a tag with no tag group specified:

{
    "audience" : {
        "tag" : "Giants Fans"
    }
}

Push to a tag with a tag group specified:

{
   "audience": {
      "tag": "platinum-member",
      "group": "loyalty"
   }
}

Push to a static list:

{
   "audience": {
      "static_list": "subscriptions"
   }
}

Push to a single iOS device using a channel id:

{
   "audience": {
      "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
   }
}

Specify more than one Channel of the same type by including the values in an array:

{
   "audience": {
      "amazon_channel": ["user-1", "user-2"]
   }
}

Pushing to a single Android device using a channel id:

{
    "audience" : {
        "android_channel" : "b8f9b663-0a3b-cf45-587a-be880946e880"
    }
}

Pushing to a single Amazon device using a Channel ID:

{
    "audience" : {
        "amazon_channel" : "b8f9b663-0a3b-cf45-587a-be880946e880"
    }
}

Push to a single web browser using a channel ID:

{
   "audience": {
      "channel": "2c36e8c7-5a73-47c0-9716-99fd3d4197d5"
   }
}

Push to a single open channel using a channel ID:

{
   "audience": {
      "open_channel": "4c36e8c7-5a73-37c0-9716-99fd3d4197d5"
   }
}

Send to a single SMS device:

{
    "audience" : {
        "sms_id" :  {
            "sender" : "12345",
            "msisdn" : "15552243311"
        }
    }
}

Send to all SMS channels associated with a specific sender:

{
    "audience" : {
        "sms_sender" : "12345"
    }
}

Push to a single Windows device:

{
    "audience" : {
        "wns" : "3644dada-d807-a2da-19d0-90d902ea7636"
    }
}

And here's a Segment. You must know the segment-id for the target Segment:

{
    "audience" : {
        "segment" : "<segment-id>"
    }
}

And a Named User:

{
   "audience" : {
      "named_user" : "user-id-54320"
   }
}

Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a channel ID or metadata that maps to the device (or multiple devices) such as a tag. Atomic selectors may be one of:

tag
A tag is an arbitrary bit of metadata used to group different devices together. A tag specifier may or may not have an associated group declaration, which specifies what tag group the tag belongs to. If no tag group is specified, the default "device" group is used.
segment
a Segment is a subset of your audience that is predefined by combining Tags and/or devices that meet your specified location-targeting criteria
static_list
a list is a subset of your audience defined by a CSV file containing channel IDs, Named Users, or Aliases
named_user
a named_user is an alternate, non-unique name, mapped to a user profile in a different database, i.e., CRM, that can be used to target devices associated with that profile
alias
an alias is an alternate, non-unique name, often mapped to a user profile in a different database, that can be used to target devices associated with that profile.
Warning

Aliases are deprecated and superseded by named users. Contact Support if you need help migrating to named users.

channel
the unique channel identifier used to target a web device, i.e., browser
ios_channel
the unique channel identifier used to target an iOS device
device_token
the unique identifier used to target an iOS device, superseded by ios_channel
android_channel
the unique channel identifier used to target an Android device
apid
the unique identifier used to target an Android device, superseded by android_channel
amazon_channel
the unique channel identifier used to target an Amazon device
open_channel
the unique channel identifier used to target a device on an open platform
wns
the unique identifier used to target a Windows device
sms_id
an object containing the required fields sender and msisdn; used to target a single SMS device
sms_sender
a numeric string representing an SMS sender which when used as an audience selector; targets all SMS devices associated with the sender


Compound Selectors

Implicit OR

{
   "audience" : {
      "tag" : ["apples", "oranges", "bananas"]
   }
}

or explicit, employing a boolean operator followed by an array of atomic expression objects. In the above expression, the push will be sent to any device matching any of the three tags, and is equivalent to the explicit form as follows:

Explicit OR

{
   "audience" : {
      "OR" : [
         { "tag" : "apples" },
         { "tag" : "oranges" },
         { "tag" : "bananas" }
      ]
   }
}

Compound selectors combine boolean operators (AND, OR, or NOT) with one or more of the atomic expressions mentioned above. The syntax can be either implicit, using an array of values associated with an atomic selector, as seen in this example:

Logical Expressions

Examples:

Select devices which have subscribed to pushes about sports or entertainment, in English:

{
   "audience": {
      "AND": [
         {"OR": [
            {"tag": "sports"},
            {"tag": "entertainment"}
         ]},
         {"tag": "language_en"}
      ]
   }
}

A simple group message could be composed to send to all members of the group Group1 except for the sender, UserA:

{
   "audience": {
      "AND": [
         { "tag": "Group1" },
         { "NOT":
            { "alias": "UserA" }
         }
      ]
   }
}

An explicit logical expression is a JSON object consisting of a logical operator as the key, and an array of one or more expressions (which can be atomic, implicit OR, or other explicit logical expressions -- anything except "all").

Use Caution with NOT Operators

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.

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

Example:

There are two types of people who have your app. Those who like Justin Bieber and those who hate Justin Bieber.

Tag Strategy

  • Users who like Justin Bieber tag "belieber" and "nonhater"
  • Users who hate Justin Bieber tag "hater" and "nonbelieber"

Using tags this way assigns a positive and non-negative tag attribute to a user when possible, making it easier and faster to identify audience with the absence of an attribute.

Location Expressions

Example: (referencing a location by id)

{
   "audience": {
      "location": {
         "id": "4oFrxA7ncddPratuelEQIV",
         "date": {
            "days": {
               "start": "2015-10-15",
               "end": "2015-10-21"
            }
         }
      }
   }
}

Example: (referencing a location by alias)

{
   "audience": {
      "location": {
         "<alias-type>": "some_alias_value",
         "date": {
            "days": {
               "start": "2015-10-15",
               "end": "2015-10-21"
            }
         }
      }
   }
}

When sending to a location, include a location expression in the audience object, identifying the intended polygon by means of:

  1. either an id or location alias and

  2. the window of time for the targeted message

The notification will match devices that have checked in with a location within the given polygon during the given time window. The time window is required and must be specified by a Time Period Specifier.

JSON Parameters

id
Optional, a polygon ID
<alias-type>
Optional, a polygon alias, with the key indicating the type of alias. One of id or alias must be provided. See: Boundary Types and Aliases Catalog for more information.
date

Time Period Specifier

The time period specifier is an object indicating a time period in which to match device locations.

Fields

Response Codes

<resolution>
Optional. An object with "start" and "end"
recent
Optional. An object specifying a relative window. See table
below.

One of either days or recent must be set.

Resolutions

Valid time resolutions are:

  • "hours"

  • "days"

  • "weeks"

  • "months"

  • "years"

Absolute Window

Example: (absolute window)

{
   "audience": {
      "location": {
         "id": "00xb78Jw3Zz1TyrjqRykN9",
         "date": {
            "days": {
               "start": "2015-01-01",
               "end": "2015-01-15"
            }
         }
      }
   }
}
{
    "audience": {
        "location": {
            "id": "00xb78Jw3Zz1TyrjqRykN9",
            "date": {
                "days": {
                    "start": "2015-01-01",
                    "end": "2015-01-02"
                }
            }
        }
    }
}

An absolute window is indicated by setting the "days" attribute on the location selector. The value of that must be an object with two required fields, "start", and "end", both of which must contain ISO formatted date values as strings.

An absolute window is indicated by setting one of the time resolution attributes on the location selector, which has two required attributes - "start", and "end", both of which must be ISO-formatted dates.

Relative Window

{
   "audience": {
      "location": {
         "id": "00xb78Jw3Zz1TyrjqRykN9",
         "date": {
            "months": {
               "start": "2012-01",
               "end": "2012-06"
            }
         }
      }
   }
}

A relative window is indicated by setting the "recent" attribute on the location selector. The value of that must be an object with a single integer-valued attribute set. The name of the attribute determines the unit of time and must be one of the resolution specified, and the value, which must be a positive integer, determines the period.

ResolutionValid RangeNotes
"hours"1-48Up to the last two days
"days"1-60Up to the past 60 days
"weeks"1-10Up to the past 10 weeks
"months"1-48Up to the past 4 years
"years"1-10Up to the past 10 years
{
   "location": {
      "id": "xyz123",
      "date": {
         "days": {
            "recent": 1
         }
      }
   }
}

Using the number 1 in a relative window location expression may result in a smaller audience than expected. When recent is passed a value of 1, the location API assumes that you are referring to the current unit of time. For example, suppose you have the following location payload:

{
   "location": {
      "id": "xyz123",
      "date": {
         "hours": {
            "recent": 24
         }
      }
   }
}

If you were to send a push with this location payload at 12:01 AM, your push would only go to users that have been in location "xyz123" in the past minute. This is because the API interprets "recent": 1 to refer to the window 12:00 AM - 12:00 PM, or the current day. If you would like to push to all devices that have been in the given location in the past 24 hours, you would use hours as your unit:

Assuming the above push was sent at 1:01 PM, it would go to all devices that have been in location "xyz123" between 12:01 and 1:01 PM.

Example: (relative window)

This example sends to devices that have been in the given location ID in the past four weeks.

{
   "audience": {
      "location": {
         "id": "00xb78Jw3Zz1TyrjqRykN9",
         "date": {
            "weeks": {
               "recent": 4
            }
         }
      }
   }
}

Special Selectors

Certain audience selectors cannot be described as atomic and are represented by a string which then maps to a special Urban Airship internal accounting of all devices that meet the criteria for that string.

Broadcast

Send a broadcast (to all users) message by using "all" as the audience selector.

Example:

{
   "audience": "all",
   "device_types": "all",
   "notification": {
      "alert": "This one goes out to all of the mobile people."
   }
}
Triggered Audience

Another special selector value is for use with Create Pipeline (Automated Message). The string "triggered" indicates that the audience is comprised of the device(s) that activated the trigger.

See: Pipeline Objects for more detail.

Notification Payload

The notification payload is a JSON object assigned to the "notification" attribute on a Push Object, which contains the actual contents to be delivered to devices. At its simplest, the payload consists of a single string-valued attribute, "alert", which sends a push notification consisting of a single piece of text.

{
    "audience": "all",
    "device_types": "all",
    "notification": {
        "alert": "Hello from Urban Airship."
    }
}

The notification payload MAY include an optional "actions" object, which is described in the Actions section. If present, the actions object cannot be null or empty ({}), or an HTTP 400 will be returned.

Push Options

The options attribute is a JSON dictionary for specifying non-payload options related to the delivery of the push.

Available push options include expiry.

Expiry

Example:

{
   "audience": "all",
   "device_types": [
      "ios"
   ],
   "notification": {
      "ios": {
         "badge": "+1"
      }
   },
   "options": {
      "expiry": "2017-04-01T12:00:00"
   }
}
expiry
string | ISO timestamp or relative number of seconds indicating when the message should expire.

Expiry is a delivery expiration, also commonly referred to as TTL. If an expiry time is included with the push, and that time is subsequently reached before the push is delivered, the platform provider, e.g., APNs or GCM/FCM will not attempt to redeliver the message.

For Web Notifications, if no expiry time is set and a device is offline, the delivery service, e.g., Google or Mozilla, preserves the notification and attempts to deliver it as soon as it comes online, for a maximum of 28 days.

The value is expressed as either absolute ISO UTC timestamp, or number of seconds from now. When the delivery platform supports it, a value of zero (0) indicates that the message should be delivered immediately and never stored for later attempts.

If the value of expiry is zero and the underlying platform for a push does not support a "never store this message" option, the minimum TTL for that platform will be used.

Campaigns Object

Campaign Object example in a push payload

{
   "audience": "all",
   "notification": {
      "alert": "Taco Kitten wins Kentucky Derby by a whisker"
   },
   "campaigns": {
      "categories": [
         "kittens",
         "tacos",
         "horse_racing"
      ]
   },
   "device_types": [
      "all"
   ]
}

The Campaigns Object in a notification payload associates the notification with the categories that you add in the categories field.

categories
Required field if Campaign Object is present. Array of strings representing the campaigns you wish to associate with the notification. Must have between 1 to 10 elements, with a character and byte limit of 64 per category.
Note

Note: Apps are limited to 1,000 custom categories. Contact your Account Manager if your Urban Airship project requires more than 1000 campaign categories.

Channel Object

A channel object describes everything germane to a channel registration.

{
   "channel_id": "01234567-890a-bcde-f012-3456789abc0",
   "device_type": "ios",
   "installed": true,
   "background": true,
   "opt_in": false,
   "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
   "created": "2013-08-08T20:41:06",
   "last_registration": "2014-05-01T18:00:27",
   "named_user_id": "some_id_that_maps_to_your_sytems",
   "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"
   }
}
channel_id
string, the unique channel identifier assigned to this device
device_type
string, specifies the platform. One of "ios", "android", "amazon", or "web"
installed
boolean, specifies whether the channel is installed or not
background
boolean, specifies whether the device associated with this channel has background app refresh enabled. If this is true, then the device can receive background push. This field only appears for iOS devices on the 5.0+ SDK.
opt_in
boolean, specifies whether this channel is opted-in to push. For devices on SDK 4.0 or under, we assume this is true except in the following two scenarios: the app has been uninstalled, or the user explicitly disabled push from within the app.
created
string, the creation date of this channel identifier
last_registration
string, displays the last registration date of this channel, if it is known.
named_user_id
string, a customer-chosen ID that represents the device user, e.g., CRM ID, hash of email address
alias
string, deprecated. Displays the alias associated with this channel, if one exists. Aliases are the precursor to Named Users, our user mapping system. If you are using aliases, please upgrade to Named Users.
tags
an array of tags associated with this channel.
tag_groups
object, listing customer-created Tag Groups and Device Property Tags
ios
object containing iOS-specific parameters. Contains the current badge value, quiet time preferences, and the timezone associated with the device.
web

object containing Web-specific parameters. Contains the current badge value, quiet time preferences, and the timezone associated with the device.

  • subscription - Required for signing the push package, includes the keys p256dh and auth.

Named User Object

The Named User Object lists tags that are associated with the Named User and the array of associated Channel Objects.

{
   "named_user_id": "user-id-1234",
   "tags": {
      "crm": ["tag1", "tag2"]
   },
   "channels": [
      {
         "channel_id": "ABCD",
         "device_type": "ios",
         "installed": true,
         "opt_in": true,
         "push_address": "FFFF",
         "created": "2013-08-08T20:41:06",
         "last_registration": "2014-05-01T18:00:27",
         "alias": "xxxx",
         "ios": {
            "badge": 0,
            "quiettime": {
               "start": "22:00",
               "end": "06:00"
            },
            "tz": "America/Los_Angeles"
         }
      }
   ]
}

JSON Parameters

  • named_user_id – (String) An identifier chosen by the customer to represent a user. The named_user_id cannot contain leading or trailing whitespace and must be between 1 and 128 characters.
  • tags – (Object) Contains a series of <tag_group>: [tag_1,...,tag_n] key value pairs.
  • channels – (Array of Objects) An array of channel objects.

Open Channel Object

An open channel object is the object used to create or update channels on an open platform.

{
   "channel": {
      "type": "open",
      "opt_in": true,
      "address": "Number Four",
      "tags": [
         "toaster",
         "caprica"
      ],
      "timezone": "America/Los_Angeles",
      "locale_country": "US",
      "locale_language": "en",
      "open": {
         "open_platform_name": "cylon",
         "identifiers": {
            "model": "4"
         }
      }
   }
}

JSON Parameters

  • "type" - Required. Must be "open".
  • "opt_in" - Required. If false, no payloads will be delivered for the channel.
  • "address" - Required. Unique identifier of the object used as the primary ID in the delivery tier (webhook). One-to-one association with Channel ID. Examples: email address, phone number.
  • "tags" - Optional. List of strings used for audience targeting. An empty list removes all tags.
  • "timezone" - Optional, string. An IANA tzdata identifier for the timezone as a string, e.g., "America/Los Angeles". Will set the timezone tag group tag with the specified value.
  • “locale_country” - Optional, string. The two-letter country locale shortcode. Will set the ua_locale_country tag group to the specified value.
  • “locale_language” - Optional, string. The two-letter language locale shortcode. Will set the ua_locale_language tag group to the specified value.
  • "open" - Required, Open Platform Options Object.
  • "created" - Optional, read-only date.
  • "last_modified" - Optional, read-only date.

Open Platform Options Object

JSON Parameters

  • "open_platform_name" - Required, string. The name of the open platform to which you are registering this channel.
  • "identifiers" - Optional map of string values. These will be delivered in open channels payloads, but cannot be used for segmentation. Maximum of 100 pairs of string values. This map should be exhaustive whenever this key is present. Values will not be unioned with existing identifiers; they will replace them.

Email Address Object

{
   "email_address" : "name@example.com"
}

JSON Parameters

  • email_address - Required String. The email address associated with a channel.

SMS Address Object

{
   "sender": "12345",
   "msisdn": "15031112222"
}

JSON Parameters

  • sender - Required string. Must be numeric characters only.
  • msisdn - Required string. Must be numeric characters only, without leading zeros. 15 digits maximum.

Open Delivery Payload

Webhook POST Request Body

Here is an example request body with two objects, each containing all possible keys:

POST /hooks/ua/example_hook/push HTTP/1.1
Content-Type: application/vnd.urbanairship+json; version=3;
Content-encoding: gzip
Data-Attribute: values

{
   "values": [
      {
         "send_id": "ff76bb85-74bc-4511-a3bf-11b6117784db",
         "app_key": "ZGIwZTY3YjEtZTRiMi00ZG",
         "target": {
            "address": "test@example.com",
            "channel_id": "a61448e1-be63-43ee-84eb-19446ba743f0",
            "identifiers": {
               "cid": "1234567",
               "com.example.test_token": "a61448e1-be63-43ee-84eb-19446ba743f0"
            }
         },
         "payload": {
            "alert": "Giant StayPuft Marshmallow Man On a Rampage",
            "title": "Breaking News!",
            "extra": {
               "url": "https://www.example.com/"
            }
         }
      },
      {
         "send_id": "647e799e-3b15-46f0-b4f1-12360d51ce4a",
         "app_key": "ZGIwZTY3YjEtZTRiMi00ZG",
         "target": {
            "address": "sample@example.com",
            "channel_id": "5b7e9f63-df28-43f4-8182-b762c628c4c4",
            "identifiers": {
               "cid": "7654321",
               "com.example.test_token": "503640e8-88f7-4dee-9245-7479ac1a8501"
            }
         },
         "payload": {
            "alert": "Giant StayPuft Marshmallow Man On a Rampage",
            "title": "Breaking News!",
            "extra": {
               "url": "https://www.example.com/"
            }
         }
      }
   ]
}

Here is an example request body with one object, containing only the required keys:

POST /hooks/ua/example_hook/push HTTP/1.1
Content-Type: application/vnd.urbanairship+json; version=3;
Content-encoding: gzip
Data-Attribute: values

{
   "values": [
      {
          "send_id": "ff76bb85-74bc-4511-a3bf-11b6117784db",
          "app_key": "ZGIwZTY3YjEtZTRiMi00ZG",
          "target": {
              "address": "test@example.com",
              "channel_id": "a61448e1-be63-43ee-84eb-19446ba743f0",
          },
          "payload": {
              "alert":"Giant StayPuft Marshmallow Man On a Rampage",
          }
      }
  ]
}

The request body itself is a JSON object containing a single top level key, "values", pointing to an array of up to 1,000 JSON objects. Urban Airship will break up large pushes into groups of 1000.

Each object in the array is required to have the following keys:

  • "send_id"—UUID version 4 string. Uniquely identifies the object.
  • "app_key"—22 character string containing the characters: [-_A-Za-z0-9].
  • "payload"—push payload with all "open" overrides for the delivery type applied.
  • "target"—A target object containing the address and a string->string map of alternative identifiers.

Target Object

{
   "identifiers": {
      "com.urbanairship.aaid": "94b0c28e-0f00-4601-af28-e70322f46a75",
      "friend": "ship",
      "ice": "cream",
      "session_id": "5abe6b52-7dcf-4fec-b0a5-d24cb4deaafe",
      "com.urbanairship.limited_ad_tracking_enabled": "false"
   },
   "channel_id": "1e215090-e692-4d89-ab7f-1f2ace2a229b",
   "address": "+1 5558675309"
}

Information pertaining to the target related to a webhook payload is defined under the "target" key in each response item.

Target objects are required to have both of following keys:

  • "channel_id"—string, the channel identifier for the target.
  • "address"— string, the customer-provided delivery address for the target.

Target objects may have the following keys:

  • "identifiers"—A JSON object with identifiers specified by the app. Common uses are IDFA or the primary key in your CMS. The values of the keys and values in this object are up to you, however Urban Airship may make additional functionality available using keys prefixed with "com.urbanairship." so keys using that prefix should be avoided.

Payload Object

The payload to deliver to the target.

  • "alert"—required, string. The primary message to deliver to the target.
  • "title"—optional, string. The title of the payload. A good example use case would be an email header for an open email notification.
  • "extra"—optional, a string-to-string map of additional values to deliver to the target. Can contain any additional information that users want to deliver to the target.

Platform Overrides

Example:

The following example sends a different alert string for every supported platform:

{
   "audience": "all",
   "device_types": "all",
   "notification": {
      "ios": {
         "alert": "Hello, iDevices"
      },
      "android": {
         "alert": "These are not the...yeah, lame joke."
      },
      "amazon": {
         "alert": "Read any good books lately?"
      },
      "web": {
         "alert": "Oh the tangled web we weave"
      },
      "email": {
         "subject": "Did you get that thing I sent you?",
         "html_body": "<h2>Richtext body goes here</h2><p>Wow!</p>",
         "plaintext_body": "Plaintext version goes here",
         "message_type": "commercial",
         "sender_name": "Urban Airship",
         "sender_address": "team@urbanairship.com",
         "reply_to": "no-reply@urbanairship.com"
      },
      "wns": {
         "alert": "Developers, developers, developers."
      },
      "open::toaster": {
         "alert": "Would you like avocados with that?"
      }
   }
}

Each supported platform has an optional platform override section, which can change the value of alert for that platform, or provide more detailed platform-specific payload data.

If the alert key has been provided at the top level, it will be merged with the platform-specific payload. For example, an Android payload can add the extra map without overriding an alert value provided at the top level.

Note

Note: You must use the full email platform override object when sending an email notification via the Push API, regardless of how many platforms you are sending to. The alert key is not supported for email.

iOS

The platform override section for iOS uses the attribute ios. For more detailed discussion of iOS-specific push behavior, see iOS Push.

The iOS override section may have any of the following attributes:

  • "alert" - Override the alert value provided at the top level, if any. May be a JSON string or an object which conforms to Apple's spec. See the Payload Key Reference in Apple's developer documentation for more information.

  • "badge" - May be an integer, or an auto badge value (see Badge Values, below).

  • "category" - Optional, a string. Sets the APNs category for the push. This maps directly to the "category" field in the "aps" section of the APNs payload.

  • "collapse_id" - Optional, a string. When there is a newer message that renders an older, related message irrelevant to the client app, the new message replaces the older message with the same collapse_id. Similar to the GCM collapse_key. The value of this key must not exceed 64 bytes. iOS 10 or above.

  • "content-available" or "content_available" - a boolean, one of true or false.

  • "expiry" - The expiry time for APNS to cease trying to deliver a push. Can be an integer encoding number of seconds from now, or an absolute timestamp in ISO UTC format. An integer value of 0 (zero) will be passed directly to Apple, and indicates that the push should be delivered immediately and not stored by APNS ("now or never" delivery). If a global expiry value has been provided in the push options object, this will override it.

  • "extra" - a dictionary of string keys to arbitrary JSON values. The key "aps" would conflict with the generated APNS payload and is disallowed.

  • "interactive" - Optional, an object. The "interactive" object can be used to override the top-level interactive notification payload for iOS devices. It conforms to the standard interactive object specifications.

  • "media_attachment" - Optional, a JSON object (see Media Attachment below). Specifies a media attachment to be handled by the UA Media Attachment Extension. iOS 10 and Urban Airship iOS SDK 8.0.0 or later required.

  • "mutable_content" or "mutable-content" - Optional, a boolean, one of true or false. Defaults to false. When set to true, content may be modified by an extension. This flag will be automatically set to true if there is a media_attachment in the payload. iOS 10 or above.

  • "priority" - Optional, an integer. Sets the APNS priority of the delivery. This feature of APNS is specific to iOS 7+. Valid values are 10 (immediate delivery) and 5 (conserve battery). The default value is 10. The priority key must be set to 5 if sending a push without an alert, otherwise the request will fail silently.

  • "sound" - a string.

  • "subtitle" - Optional, a string that will display below the title of the notification. This is provided as a convenience for setting the subtitle in the alert JSON object. If a subtitle is also defined in the alert JSON object, this value is ignored. iOS 10 or above.

  • "title" - Optional, a string. Sets the title of the notification. Used for specifying the Apple Watch short look interface and the iOS Notification Center title text on iOS 8.2+.

Extras and Actions

Keys provided in the extras object may conflict with actions, if any are specified, and can result in an HTTP 400 being returned. See iOS, Extras and Actions for more details.

Badge Values

The "badge" key on the iOS override may be an integer, the value "auto", or an increment value. Increments are expressed by integers formatted as strings, and prefixed with either '+' (U+002B) or '-' (U+002D). The numeric portion may be an integer value.

Examples:

  • "+1"

  • "+12"

  • "-3"

  • 12

  • "auto"

The "badge" key is restricted to "auto" and integral values. Anything else will cause a validation failure, resulting in an HTTP 400 Bad Request response.

Alert

The "alert" key on the iOS override may be either a plain string, or a JSON object with one or more of the following fields.

KeyType
bodystring
action-loc-keystring or null
loc-keystring
loc-argsarray of strings
launch-imagestring

Media Attachment

Media Attachment Object:

The following example asks the extension to download the gif from the URL, crop it to the center 50% of the gif's dimensions for the thumbnail, and display frame #15 in the thumbnail.

{
    "audience": "all",
    "device_types": [
            "ios"
        ],
    "notification": {
        "ios": {
            "alert": "New Moustaches await you!",
            "media_attachment": {
                "content": {
                    "title": "Moustache Twirl",
                    "body": "Have you ever seen a moustache like this?!"
                },
                "options": {
                    "crop": {
                        "height": 0.5,
                        "width": 0.5,
                        "x": 0.25,
                        "y": 0.25
                    },
                    "time": 15
                },
                "url": "https://media.giphy.com/media/JYsWwF82EGnpC/giphy.gif"
            },
            "mutable_content": 1
        }
    }
}

The "media_attachment" key on the iOS override is a JSON object that describes a media attachment to be handled by the UA Media Attachment extension in iOS 10.

url
Required, a string, the URL to be downloaded by the UA Media Attachment extension. The media file should be one of the following types, and not exceed the maximum file size. HTTPS is required.
Important

it is recommended that you restrict image media attachments to 1 MB or less. While larger file sizes are technically supported (as shown in the table below), the ability to receive media may be limited by the download speed of the receiving device. If media is too large and takes too long to download, a notification may render without it.

TypeSpecifications
Image(5 MB) JPEG, GIF, PNG
Audio(10 MB) AIFF, WAV, MP3, M4A
Video(50 MB) MPEG, MPEG2, MP4, AVI
options
Optional, a JSON object that describes how to display the resource at the URL specified above, with any of the following fields:
crop*

Optional, A JSON object that describes the crop parameters to be used in the thumbnail. Each field is a decimal, normalized from 0 to 1:

  • x
    The X offset where the crop begins
  • y
    The Y offset where the crop begins
  • width
    The width of the final crop
  • height
    The height of the final crop
time

Optional, a decimal, the frame of the animated resource that should be used in the thumbnail.

For gifs, this value should be the frame number (an integer, with the first frame being frame 1) to show in the thumbnail

For movies, the value should be the time (in seconds) into the movie from which to grab the thumbnail

This value should not be set for static resources like JPGs.

If the time does not exist in the resource, either because it is out of bounds or because the resource is static, the thumbnail will not show.

hidden

Optional, a boolean, when true, the thumbnail will be hidden.

Before displaying the thumbnail, iOS additionally crops the thumbnail down to a square. Depending on the size of the original image, the relative height and width may need to be different from each other to create a square thumbnail.

content

Optional, a JSON object that describes portions of the notification that should be modified if the media attachment succeeds, with any of the following fields:

  • title

    String
  • subtitle

    String
  • body

    String

Android

Example:

{
   "android": {
      "title": "Shoe sale",
      "alert": "All the shoes are on sale!",
      "summary": "Don't miss out!",
      "extra": {
          "url": "http://example.com",
          "story_id": "1234",
          "moar": "{\"key\": \"value\"}"
      },
      "icon": "shoes",
      "icon_color": "#8B4513",
      "notification_channel": "promos"
   }
 }

Public Notification Example:

{
   "android": {
      "priority": 1,
      "category": "promo",
      "visibility": -1,
      "public_notification": {
         "title": "the title",
         "alert": "hello, there",
         "summary": "the subtext"
      }
   }
}

The platform override section for Android uses the attribute "android". The android override section may have any of the following attributes:

  • "alert" - Optional, override the alert value provided at the top level, if any.

  • "category" - Optional string from the following list: "alarm", "call", "email", "err", "event", "msg", "promo", "recommendation", "service", "social", "status", "sys", and "transport". It is used to help determine notification sort order. Available on Android Lollipop+

  • "extra" - a JSON dictionary of string values. Values for each entry may only be strings. If you wish to pass structured data in an extra key, it must be properly JSON-encoded as a string.

  • "icon" - Optional, the name of a drawable in the application's resource directory.

  • "icon_color" - Optional, a string in the format of #rrggbb that defines the notification accent color. Available on Android Lollipop+

  • "interactive" - Optional, an object. The "interactive" object can be used to override the top-level interactive notification payload for Android devices. It conforms to the standard interactive object specifications.

  • "notification_tag" - Optional, a string identifier used to replace an existing notification in the notification drawer. If the notification with the same tag does not exist, the new notification will still be displayed.

  • "notification_channel" - Optional, an identifier of a notification channel predefined by the application.

  • "priority" - Optional integer in the range from -2 to 2, inclusive. Used to help determine notification sort order. 2 is the highest priority, -2 is the lowest, and 0 is the default priority. Superseded by notification_channels for Android O and newer devices. Available on Android Lollipop - Android Nougat

  • "public_notification" - Optional object. A notification to show on the lock screen instead of the redacted one. This is only useful with "visibility" set to 0 (private). The object may contain any of the following fields: "title", "alert", or "summary". Available on Android Lollipop+

  • "sound" - Optional, a string representing a sound file name included in the application’s resources. Superseded by notification_channels for Android O and newer devices.

  • "style" - Optional advanced styles

  • "summary" - Optional, a string representing a summary/subtitle of the notification.

  • "title" - Optional, a string representing the title of the notification. The default value is the name of the app at the SDK.

  • "visibility" - Optional integer in the range from -1 to 1 inclusive. 1 is public (default), 0 is private, and -1 is secret. Secret does not show any notifications, while private shows a redacted version of the notification. Available on Android Lollipop+

For more detailed discussion of Android-specific push behavior, see Android Integration.

FCM/GCM Delivery Options

Example:

{
    "android": {
        "alert": "Hello",
        "extra": {
            "url": "http://example.com",
            "story_id": "1234",
            "moar": "{\"key\": \"value\"}"
        },
        "collapse_key": "gobbledygook",
        "time_to_live" : 10,
        "delay_while_idle" : true,
    }
}
  • "collapse_key" - Optional, a string.

  • "time_to_live" - Optional, an integer or timestamp specifying the expiration time for the message. 0 indicates that FCM/GCM should not store the message (i.e. "now or never" delivery).

  • "delivery_priority" - Optional, a string of either "high" or "normal", defaults to "normal" if not provided. Sets the FCM/GCM priority.

  • "delay_while_idle" - Optional, a boolean.

See Google's Downstream message syntax documentation for explanations of collapse_key, time_to_live, and delay_while_idle.

Wearables

Wearable Example:

{
   "android": {
      "local_only": true,
      "wearable": {
         "background_image": "http://example.com/background.png",
         "extra_pages": [
            {
               "title": "Page 1 title - optional title",
               "alert": "Page 1 title - optional alert"
            },
            {
               "title": "Page 2 title - optional title",
               "alert": "Page 2 title - optional alert"
            }
         ],
         "interactive": {
            "type": "ua_yes_no_foreground",
            "button_actions": {
               "yes": {
                  "add_tag": "butter",
                  "remove_tag": "cake",
                  "open": {
                     "type": "url",
                     "content": "http://www.urbanairship.com"
                  }
               },
               "no": {
                  "add_tag": "nope"
               }
            }
         }
      }
   }
}
  • "background_image" - String field containing the URL to a background image to display on the wearable device.

  • "extra_pages" - List of objects, each with "title" and "alert" string attributes for specifying extra pages of text to appear as pages after the notification alert on the wearable device.

  • "interactive" - An object which can be used to override the interactive notification payload for the wearable device. The object must conform to the interactive object specification.

  • "local_only" - Optional boolean (default false). Set this to true if you do not want this notification to bridge to other devices (wearables).

  • "wearable" - Optional object with the following optional fields:

Style

Big Text Example:

{
   "android": {
      "style": {
         "type": "big_text",
         "big_text": "This is big!",
         "title": "Big text title",
         "summary": "Big text summary"
      }
   }
}

Big Picture Example:

{
   "android": {
      "style": {
         "type": "big_picture",
         "big_picture": "http://pic.com/photo",
         "title": "Big picture title",
         "summary": "Big picture summary"
      }
   }
}

Inbox Style Example:

{
   "android": {
      "style": {
         "type": "inbox",
         "lines": ["line 1", "line 2", "line 3", "line 4"],
         "title": "Inbox title",
         "summary": "Inbox summary"
      }
   }
}

A number of advanced styles are available on Android 4.3+ by adding the "style" attribute to the platform-specific notation payload on Android and Amazon. The "style" object must contain a string field "type", which will be set to either "big_text", "big_picture", or "inbox". Whatever "type" is set to must also exist as an independent string field within the "style" object:

  • "big_picture" - If "type" is set to "big_picture", then the "big_picture" string field must also be present. "big_picture" should be set to the URL for some image.
Note

Note: The SDK attempts to scale large images down to .75 screen width x 240 DP, keeping the original aspect ratio. Android will then center crop images in notifications.

  • "big_text" - If "type" is set to "big_text", then the "big_text" string field must also be present. "big_text" should be set to the text that you want to display in big text style.

  • "inbox" - If "type" is set to "inbox", then the "lines" field must also be present. The "lines" field should be an array of strings.

The "style" object may also contain "title" and "summary" override fields:

  • "title" - Optional string field which will override the notification.

  • "summary" - Optional string field which will override the summary of the notification.

Web

{
   "audience": {
      "channel": "cab69081-0196-4f6b-91dc-53bc88a2e6ce"
   },
   "device_types": [
      "web"
   ],
   "notification": {
      "alert": "Hello, world!",
      "actions": {
        "open": {
          "type": "url",
          "content": "http://www.urbanairship.com"
        }
      },
      "web": {
         "alert": "Hello Web World",
         "title": "A Custom Web Title",
         "require_interaction": true,
         "extra": {
            "story_id": "1234",
            "moar": "{\"key\": \"value\"}"
         },
         "icon": {
            "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/2/2b/Urban_Airship_Logo.jpg/220px-Urban_Airship_Logo.jpg"
         }
      }
   }
}
Note

Google Chrome, Mozilla Firefox, and Opera are currently supported.

The platform override section for web notifications uses the attribute "web". The "web" object may have zero or more of the following attributes:

  • alert - Optional, override the alert value provided at the top level, if any.

  • title - Optional, a string representing the title of the notification.

  • extra - JSON dictionary of string values. Values for each entry may only be strings. If you wish to pass structured data in an extra key, it must be properly JSON-encoded as a string.

  • require_interaction - Optional, a boolean. If true, indicates that an end user must interact with the notification in order to remove it from their computer screen.

  • icon - Optional, a JSON object. Specifies an icon to be used with the notification.

    • url - Required if icon is present, a string, the URL to be used for the icon
Note

If icon is omitted, the notification will display the icon configured in the service configuration page.


Email

Example email override

{
   "audience": {
      "named_user": "jane_doe"
   },
   "device_types": [
      "email",
      "android"
   ],
   "notification": {
      "android": {
        "alert": "Hello Android user!"
      },
      "email": {
         "subject": "Hello Email user! ",
         "html_body": "<h1>Greetings</h1><p>Hello!</p>",
         "plaintext_body": "Greetings!",
         "message_type": "commercial",
         "sender_name": "Urban Airship",
         "sender_address": "team@urbanairship.com",
         "reply_to": "no-reply@urbanairship.com"
      }
   }
}

The following fields in the email platform override inside of the notification object are required for sending an email:

  • message_type - Required string. Must be one of "transactional" or "commercial", corresponding to the email_opt_in_level for email channels. transactional emails can be sent to channels with email_opt_in_level set to commercial or transactional.
  • subject - Required string. The subject line of the email.
  • plaintext_body - Required string. The plaintext content of the email body.
  • sender_name - Required string. The common name for the sender, visible to email recipients, e.g., “Urban Airship”.
  • sender_address - Required string. The email address of the sender. The sending domain must be enabled for your project by Urban Airship.
  • reply_to Required string. Reply-to address, e.g., “no-reply@urbanairship.com“.
  • html_body Optional string. The rich-text HTML body of the email.

SMS

Example SMS override

{
    "alert": "A generic alert sent to all platforms specified in device_types",
    "sms": {
        "alert": "a shorter alert for sms users",
        "expiry": "2018-04-01T12:00:00"
    },
    "device_types": ["sms", "ios"]
}

The platform override section for SMS uses the attribute sms. The sms object may have zero or more of the following attributes:

  • alert - Optional, override the alert value provided at the top level, if any. The maximum length for an SMS alert is 1600 characters. The alert will be split into multiple messages if needed.
  • expiry - Optional, the expiry time after which Urban Airship will cease trying to deliver an SMS push notification. Can be an integer encoding number of seconds from now, or an absolute timestamp in ISO UTC format. If a global expiry value has been provided in the push options object, this will override it.

Open

Example open platforms alert override:

{
   "alert": "A generic alert sent to all platforms specified in device_types",
   "open::sms": {
      "title": "SMS Alert!",
      "alert": "a shorter alert for sms users",
      "extra": {
         "some_info": "for sms only",
         "some_id": "671ecd12-ad56-4b2f-98f1-107ce33d33e6"
      }
   },
   "open::email": {
      "alert": "a longer alert for users of email, who have more space.",
      "summary": "a longer summary of some content.",
      "media_attachment": "https://example.com/cat_standing_up.jpeg",
      "interactive": {
         "type": "ua_yes_no_foreground",
         "button_actions": {
            "yes": {
               "open": {
                  "type": "url",
                  "content": "http://www.urbanairship.com"
               }
            },
            "no": {
               "app_defined": {
                  "foo": "bar"
               }
            }
         }
      }
   },
   "device_types": [
      "open::sms",
      "open::email",
      "ios"
   ]
}

The platform override section for open platforms uses the prefix attribute "open::" before the configured open platform name. The "open::<open_platform_name>" object will contain an object with the following attributes:

  • alert - Optional, override the alert value provided at the top level, if any.

  • title - Optional, a string representing the title of the notification.

  • extra - Optional, a JSON dictionary of string values. Values for each entry may only be strings. If you wish to pass structured data in an extra key, it must be properly JSON-encoded as a string.

  • summary - Optional, a string value for providing a content summary.

  • media_attachment - Optional, a URI for an image or video somewhere on the internet.

  • interactive - * Optional. An Interactive object. Included button actions must be of type "add_tag", "remove tag", app_defined" or "open" with subtype "url".

Amazon

The platform override section for Amazon uses the attribute "amazon". the "amazon" object may have zero or more of the following attributes:

  • "alert" - Optional, override the alert value provided at the top level, if any.

  • "consolidation_key" - Optional, a string value. Similar to GCM’s collapse_key.

  • "expires_after" - Optional, an integer value indicating the number of seconds that ADM will retain the message if the device is offline. The valid range is 60 - 2678400 (1 minute to 31 days), inclusive. Can also be an absolute ISO UTC timestamp, in which case the same validation rules apply, with the time period calculated relative to the time of the API call.

  • "extra" - JSON dictionary of string values. Values for each entry may only be strings. If you wish to pass structured data in an extra key, it must be properly JSON-encoded as a string.

  • "interactive" - Optional, an object. The "interactive" object can be used to override the top-level interactive notification payload for Amazon devices. It conforms to the standard interactive object specifications.

  • "sound" - Optional, a string representing a sound file name included in the application’s resources.

  • "style" - Optional advanced styles available for certain Android and Amazon devices. See: Style.

  • "summary" - Optional, a string representing a summary of the notification.

  • "title" - Optional, a string representing the title of the notification. The default value is the name of the app at the SDK.

    Windows

The platform override section for Windows uses the attribute "wns". The "wns" object must have exactly one of the following attributes:

  • "alert"

  • "toast"

The "wns" object may also contain one or both of the following attributes:

  • "tile"

  • "badge"

In-App Message

The in-app message payload is an object assigned to the in_app attribute on a push object. Aside from the display and display_type attributes, which specify the appearance of the in-app message, the in_app object looks very similar to a push object:

{
   "alert": "Happy holidays",
   "display_type": "banner",
   "display": {
      "duration": 60
   },
   "expiry": "2015-04-01T12:00:00",
   "actions": {
      "open": {
         "type": "url",
         "content": "http://www.urbanairship.com"
      }
   },
   "interactive": {
      "type": "ua_share",
      "button_actions": {
         "share": { "share": "Happy holidays!" }
      }
   },
   "extra": {
      "message_num": 12345
   }
}

JSON Parameters

  • alert – (String) The text displayed on the in-app message.

  • display_type – (String) Specifies the display type. Currently, the only valid option is "banner".

  • display – (Object) A Display Object.

  • expiry – (String) String specifying an expiry value.

  • actions – (Object) An Actions object specifying actions which occur when the user taps on the banner notification.

  • interactive – (Object) An Interactive object specifying interactive category and associated actions.

  • extra – (Object) Mapping of additional key-value pairs.

In-app message sends use the same endpoint as standard push sends.

Example Request:

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

{
   "audience": "all",
   "device_types": ["ios","android"],
   "notification": { "alert": "This part appears on the lockscreen" },
   "in_app": {
      "alert": "This part appears in-app!",
      "display_type": "banner",
      "expiry": "2015-04-01T12:00:00",
      "display": {
         "position": "top"
      },
      "actions": {
         "add_tag": "in-app"
      }
   }
}

JSON Parameters

  • audience – (Required) An audience selector.

  • device_types – (Required) An array of device_type values

  • notification – (Optional) A notification object. This specifies the text that will appear on the lockscreen.

in_app

  • alert – (Required) String specifying the in-app message alert text.

  • display_type – (Required) Specifies the display type. Currently, the only valid option is "banner".

  • expiry – (Optional) String specifying an expiry value.

  • display – (Optional) A display object specifying the appearance of the in-app message.

  • actions – (Optional) An Actions object specifying actions which occur when the user taps on the banner notification.

  • interactive – (Optional) An Interactive object specifying interactive category and associated actions.

  • extra – (Optional) Object.

Note

If you would like to send a message that only includes an in-app component, simply exclude the notification attribute. When sending a message with both a notification and in_app component, the notification text will only appear on the lockscreens of opted-in users, while the in_app text will be sent to the entire specified audience.

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
Data-Attribute: push_ids

{
    "ok" : true,
    "operation_id" : "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078"
    ]
}

Display Object

The allowed fields for this object depend on the value of of the display_type field. Currently, the only valid type is "banner", so the following is an associated display object for the banner display type:

{
   "primary_color": "#FF0000",
   "secondary_color": "#00FF00",
   "position": "top",
   "duration": 600
}

JSON Parameters

  • primary_color – (String) Specifies the primary color of the in-app message.

  • secondary_color – (String) Specifies the secondary color of the in-app message.

  • position – (String) One of either "top" or "bottom", specifies the screen position of the message.

  • duration – (Int > 0) Specifies how long the notification should stay on the screen in seconds before automatically disappearing; set to 15 by default.

Schedule Object

{
    "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
    "schedule": {"scheduled_time": "2018-04-01T18:45:30"},
    "name": "My schedule",
    "push": {
        "audience": {"tag": "49ers"},
        "device_types": "all",
        "notification": {"alert": "Touchdown!"},
        "options": {"expiry": 10800}
    }
}

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

Note

The url key is set by the server and so is present in responses but not in creation requests sent from the client.

Schedule Specificiation

There are three forms of schedule. schedule_time and local_schedule_time specify delivery time in UTC; the best_time object uses predictive analytics to schedule a push localized to the timezone for a given channel.

A full schedule object, then, will have both a schedule and a push object.

{
   "scheduled_time": "2018-04-01T18:45:30"
}
  • Scheduled push to be delivered globally at the same moment:
{
  "best_time": {
    "send_date": "2018-06-01"
  }
}

 

  • Scheduled push to be delivered at the best time to maximize engagement. Best time pushes are sent on the send_date, localized to the time zone for a channel:

 

{
   "local_scheduled_time": "2018-04-01T18:45:30"
}
  • Scheduled push to be delivered at the device local time:

Pipeline Object

A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata.

A pipeline object has the following attributes:

Requests

name
string, optional | A descriptive name for the pipeline
enabled
boolean, required | Determines whether or not the pipeline is active
outcome
object, required | A single outcome object or an array of outcome objects
immediate_trigger
object, optional | A single event identifier or an array of event identifiers
cancellation_trigger
object, optional | A single event identifier or an array of event identifiers
historical_trigger
object, optional | A single historical trigger object or an array of historical trigger objects
constraint
object, optional | A single constraint object or array of constraint objects
condition
object, optional | A single condition set or array of condition sets
timing
object, optional | A single Timing Object

Responses

url
string. read-only | The canonical identify of the pipeline. This is a read-only field present on responses from the API, but will be ignored if it is present on requests.
status
string, read-only | One of live or disabled. An enumerated string value indicating whether the pipeline is currently capable of triggering pushes, based on evaluation of values for enabled
creation_time
timestamp, read-only | An ISO 8601 timestamp in UTC indicating the time that the pipeline was initially created. This is a read-only field which is present on GET responses. If it is included in a POST or PUT request it will be ignored
last_modified_time
timestamp, read-only | An ISO 8601 timestamp in UTC indicating the time that the pipeline was last modified. This is a read-only field which is present on GET responses. If it is included in a POST or PUT request it will be ignored

Outcome Object

An outcome object has the following attributes:

"delay"
Deprecated, use a delay object in the timing object to specify a post-trigger delay instead. An optional, integer >= 60 | The number of seconds to delay before processing the outcome. Only valid if the "push" attribute is present.
"push"
A single push object. The "audience" field must be set to "triggered"

Deleted Pipeline Object

A deleted pipeline object contains the id and the deletion time for each pipeline that is returned when you list deleted pipelines with GET /api/pipelines/deleted.

The object contains:

pipeline_id
The id of the pipeline.
deletion_time
An ISO 8601 UTC timestamp indicating the date and time that the pipeline was deleted.

Immediate Triggers

An immediate trigger object defines a condition that activates a trigger immediately when an event matching it occurs. If a pipeline has multiple immediate triggers, they're combined via an implicit OR operation. Any one of the triggers firing will activate the pipeline.

Immediate triggers are all event identifiers.

Cancellation Triggers

Example:

In the following example a pipeline with a 3-day delay is set into motion after a user indicates interest in sinks. If 3 days of sink-buying radio silence go by, the user will receive a notification with a fabulous sink offer, unless a "COMPLETED_CHECKOUT" event fires, canceling the notification.

{
   "immediate_trigger": {
      "tag_added": "interests::kitchen_sinks"
   },
   "timing": {
      "delay": { "seconds": 259200 }
   },
   "cancellation_trigger": {
      "custom_event": {
         "name": "COMPLETED_CHECKOUT"
      }
   },
   "outcome": {
      "push": {
         "audience": "triggered",
         "device_types": "all",
         "notification": {
            "alert": "Like sinks? You'll love this deal!"
         }
      }
   }
}

A cancellation trigger object defines a condition that cancels the fulfillment of a pipeline when an event matching it occurs. If a pipeline has multiple cancellation triggers, they are combined via an implicit OR operation. Any one of the triggers will cancel the fulfillment of the pipeline.

Cancellation triggers are only allowed when the pipeline has no historical triggers and it is possible for a pipeline’s fulfillment to be delayed using the Timing Object.

The value of a cancellation trigger can be one of: open, custom_event, tag_added, or tag_removed. See Event Identifiers for further information.

Note

First Open event identifiers are not valid with cancellation triggers.

Custom Event Triggers

Example: (this trigger will match a custom event named 'christmas')

{
  "custom_event": {
    "key": "name",
    "value": {
      "equals": "christmas"
    }
  }
}

Custom Event Triggers are pipelines that are created when a custom event is either fired from the app, or sent to Urban Airship via the Server-Side Custom Events API.

Creating an event-based trigger is a two step process:

  1. Create a custom event, either by tracking it in your client code or submitting a server-originated event through our Server-Side Custom Events API. See the Custom Events topic guide to learn how to set up custom events.
  2. Reference your custom event identifier(s) in either an Immediate or Cancellation trigger object.
Note

Note: Custom event names must be lowercase, and custom event triggers are case sensitive. When referencing custom events by name, you should use the lowercase name exactly as specified in the custom event, or your event trigger may not work.

Historical Trigger Object

Example: (this trigger will match if a device has not opened the app in 30 days)

{
   "event" : "open",
   "equals" : 0,
   "days" : 30
}

An historical trigger object defines a condition that matches against event data trended over time. Currently historical trigger objects are limited to inactivity triggers, which trigger on a user's failure to open the app within a defined number of days.

The trigger consists of the following fields:

"event"
An event identifier. open is the only allowable value for the event key.
"equals"
A matching operator. Since we are measuring inactivity with the historical trigger object, 0 is the only value supported with the equals operator, i.e., we are measuring number of events in a defined time window. Any number higher than zero would therefore represent activity.
"days"
A time period key. An integer indicating the length of the matching window, in days. Max 90 days.

Event Identifiers

Event identifiers describe events that Automation can detect and act on. They may be described by a simple string (e.g. "open"), or by an object for parameterized events (e.g. { "tag_added" : "<t>" }).

Simple Event Identifiers

A simple event identifier is a string that names an event which does not require any parameters to match.

Valid simple event identifiers are:

"open"
Matches on app opens.
"first_open"
Matches on first open of an app. First open events can only be used in immediate triggers.


Because an app open event is communicated to Urban Airship via our iOS and Android mobile client libraries, it is required that your app is utilizing the library and registering app open events.

Note

open is a valid Event Identifier only for Historical Triggers, and cannot be used to activate a pipeline via Immediate Trigger. Conversely, first_open is a valid Event Identifier only for Immediate Triggers.

Compound Event Identifiers

A compound event identifier is a JSON dictionary with a single key indicating the event type, and a value specifying the specific parameter to match on.

Valid compound event identifiers are:

"tag_added"
Matches when the specified tag is added. The value of the identifier is a simple string identifying a device tag. See tags.
"tag_removed"
Matches when the specified tag is removed. The value of the identifier is a simple string identifying a device tag. See tags.
"custom_event"
Matches when a custom event matching the specified criteria was emitted for/by a device. The value must be a Custom Event Selector.

Complex Selectors

A complex selector is a JSON dictionary consisting of a set of event-specific selectors, joined together by a doubly-nested set of operators, in either:

  • Disjunctive normal form, i.e., an OR of ANDs, i.e., a sum of products

~or~

  • Conjuntive normal form, i.e., an AND of ORs, i.e., a product of sums
Note

For the purposes of this documentation, you should understand that complex selectors will always only return a single AND of ORs or OR of ANDs.

Event-specific selectors are allowed to reference any field in a potentially matching event, at any nesting depth therein.

Event-specific "leaf" nodes are dictionaries with the following fields:

"key"
required | A string value, which is the key to access on a potentially matching event.
"value"
required | A value selector of the appropriate type to match the value of the specified key.
"scope"
optional | A string value, which if present signifies that an inner dictionary is to be accessed on a potentially matching event.


Supported complex selectors are listed below.

Custom Event Selectors

Example:

This selector will match if a device emits any custom event with the name "CHECKOUT":

{
   "key": "name",
   "value": {
      "equals": "CHECKOUT"
    }
}

Example:

This selector will match if a device emits a custom event with the name "POWER_LEVEL" and a value in the (9000, 10,000] range:

{
   "and": [
      {
         "key": "name",
         "value": {
            "equals": "POWER_LEVEL"
         }
      },
      {
         "key": "value",
         "value": {
            "greater_than": 9000,
            "at_most": 10000
         }
      }
   ]
}

Example: - this selector will match if a device emits a custom event that matches any of these criteria:

  • "director" is "Wes Anderson" (string matching)

  • "rating_percent" is at least 68 (numeric matching)

  • "actors" array contains "Bill Murray" (array contains)

  • "is_on_netflix" is true (boolean matching)

{
    "or": [
        {
            "key": "director",
            "value": {
                "equals": "Wes Anderson"
            },
            "scope": "properties"
        },
        {
            "key": "rating_percent",
            "value": {
                "greater_than": 68,
                "less_than": 99
            },
            "scope": "properties"
        },
        {
            "key": "actors",
            "value": {
                "array_contains": "Bill Murray"
            },
            "scope": "properties"
        },
        {
            "key": "is_on_netflix",
            "value": {
                "equals": true
            },
            "scope": "properties"
        }
    ]
}
Note

Custom events may be either in-app user actions that you track in your app or external events that you associate with a user via the custom events endpoint. See Custom Events for details.

A Custom Event selector describes the specific criteria that a custom event must fulfill in order for it to trigger a pipeline.

Supported custom event fields in the default scope are:

name
string, required
value
number, optional


Custom events also have a map of properties that may also be selected under the "properties" scope. Unlike the custom event name (string) and custom event value (number), these property values may be string, boolean, number, or an array of these types.

Therefore, for custom event properties, you can use String Selector, Numeric Selector, Boolean Selector or an Array Selector.

Region Selector

Example:

This selector will match if an enter/exit occurs at a region with the name "Voodoo Doughnut", by accessing a member of the default scope:

{
    "key": "name",
    "value": {
        "equals": "Voodoo Doughnut"
    }
}

Example:

Slightly more complicated, this example will match enter/exit events around Voodoo Doughnut locations that have a maximum of 20 people in the doughnut queue. Note that we are accessing the "name" key from the default scope, and the "line_length" field from the inner "attributes" scope. We are also excluding one specific region by its Gimbal Place ID.

{
    "and": [
        {
            "key": "name",
            "value": {
                "equals": "Voodoo Doughnut"
            }
        },
        {
            "scope": "attributes",
            "key": "line_length",
            "value": {
                "at_most": 20
            }
        },
        {
            "not": {
                "key": "region_id",
                "scope": "source_info",
                "value": {
                    "equals": "4DEAD8675309"
                }
            }
        }
    ]
}

A region selector is a Complex Selector that describes the specific criteria a region must fulfill in order for it to qualify as a match for triggering pipelines.

Supported default-scope region keys are currently: "name" (string) "region_id" (string)

Under the "source_info" scope, we support the following key: "region_id" (string)

We also have support for the arbitrary scope "attributes", which has no key restrictions because it is user-supplied in its entirety.

Value Selectors

{
   "key": "name",
   "value": {
         "equals": "PLATINUM_STATUS"
   }
}

Value selectors are dictionaries that describe the specific criteria a value must meet in order to qualify as a match:

String Selectors

Example:

This selector will match if a value is exactly equal to "foo":

{
   "equals": "foo"
}

A string selector is a value selector for matching string values, composed of exactly one field:

"equals"
A string value that a corresponding value in an event must be exactly equal to for it to qualify as a match.

Boolean Selector

Example: - this selector will match if a value is equal to false:

{
  "equals": false
}

A boolean selector is a value selector for matching boolean values, composed of exactly one field:

"equals"
A string value that a corresponding value in an event must be exactly equal to for it to qualify as a match.

Array Selector

Example: - this selector will match if a value "needle" is contained within an array:

{
  "array_contains": "needle"
}

An array selector is a value selector for matching string values, composed of exactly one field, though eventually other options may be added, so it will not be required:

"array_contains"
A string value that must be contained within the array to be qualify as a match.

Numeric Selectors

Example:

This selector will match if a value is exactly equal to 9:

{
   "equals" : 9
}

Example:

This selector will match if a value is greater than or equal to 1 and less than or equal to 10:

{
   "at_least": 1,
   "at_most": 10
}

Example - this selector will match if a value is greater than 9000 and less than 10000:

{
  "greater_than": 9000,
  "less_than": 10000
}

Example - this selector will match if a value is greater than 42 and less than or equal to 100

{
  "greater_than": 42,
  "at_most": 100
}

A numeric selector is a value selector for matching string values, composed of at least one of the following fields:

"equals"
A numeric value (with 6 digits of decimal precision) that a value must be exactly equal to for it to qualify as a match
"at_least"
A numeric value (with 6 digits of decimal precision) that a value must be greater than or equal to for it to qualify as a match
"at_most"
A numeric value (with 6 digits of decimal precision) that a value must be less than or equal to for it to qualify as a match
"greater_than"
A numeric value (with 6 digits of decimal precision) that a value must be strictly greater to for it to qualify as a match
"less_than"
A numeric value (with 6 digits of decimal precision) that a value must be strictly less to for it to qualify as a match.
Note

If the "equals" key is specified, no other keys may be specified. Value specified for "at_least" must be less than value specified for "at_most" if both are present.

Constraint Object

Example: (This pipeline is limited to a maximum of 10 pushes per day, per device.)

{
   "name": "Rate-limited pipeline",
   "enabled": true,
   "immediate_trigger": { "tag_added": "pipelines_are_people_too" },
   "outcome": { "push": { } },
   "constraint": [
      {
         "rate": {
            "pushes": 10,
            "days": 1
         }
      }
   ]
}

A constraint object describes a constraint placed on when triggered pushes can be sent, such as a rate limit, or a window in which pushes can be delivered or suppressed. A constraint object is expressed as a JSON dictionary with a single key indicating the type of the constraint, and a dictionary with its values.

Valid constraint types are:

rate
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.

A rate limit object is comprised of two fields:

pushes
An integer, specifying the maximum number of pushes that can be sent to a device per time period.
days
An integer, specifying the time period in number of days.

Tag Conditions

Tag Conditions use the top level attribute of the pipeline object, "condition". When present, the "condition" attribute will evaluate for the presence or non-presence of the only valid condition type, tag(s).

Upon evaluation, combined with boolean operators in a Condition Set, when true, Tag Conditions will execute the given outcomes of the pipeline.

Condition Object

Example:

The following example shows a Condition Object from a pipeline which will execute if the target device has the VIP tag, or does NOT have the dont_push tag.

{
   "condition": [
      {
         "or": [
            {
               "tag": {
                  "tag_name": "VIP"
               }
            },
            {
               "tag": {
                  "tag_name": "dont_push",
                  "negated": true
               }
            }
         ]
      }
   ]
}

A condition object defines an individual condition which will be evaluated when considering whether to execute the outcomes of a pipeline. Condition objects are JSON dictionaries with a key indicating the type of condition, and a value containing any necessary parameters to that condition.

There is one valid condition type: "tag", and Tag Conditions have three possible attributes:

tag_name
required | the name of the tag to be matched
group
optional | the name of the tag group. Defaults to device
negated
optional |a boolean indicating this condition should match on the absence of a tag

Condition Set

Example:

{
   "name": "Very Specific Pipeline With Conditions",
   "enabled": true,
   "immediate_trigger": { "tag_added": "new_customer" },
   "outcome": {
      "push": {
         "audience": "triggered",
         "device_types": "all",
         "notification": { "alert": "A fine conditional VIP hello to you!" }
      }
   },
   "condition": [
      {
         "or": [
            {
               "tag": {
                  "tag_name": "VIP"
               }
            },
            {
               "tag": {
                  "tag_name": "dont_push",
                  "negated": true
               }
            }
         ]
      }
   ]
}

A condition set is a collection of one or more conditions and an operator for combining them, in the case that there are multiple conditions. A condition set may contain a maximum of 20 conditions.

Taken together, the operator and set of conditions form a boolean expression which must evaluate to true for a pipeline to be activated and its outcomes executed.

Valid operators for a condition set are "and" and "or".

Nesting of operators is not supported within a condition set, i.e., you may not combine "and" logic with "or" logic.

Experiment Object

The following JSON defines an experiment object which our system stores by experiment_id for later retrieval and listing:

{
   "name": "<experiment name>",
   "description": "<experiment description>",
   "control": "<control group>",
   "audience": "<audience-selection>",
   "device_types": "<device-types>",
   "campaigns": "<campaigns>",
   "variants": "[<variant specifications>]",
   "id": "<id>",
   "created_at": "timestamp",
   "push_id": "<push_id>"
}

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

JSON Parameters

name
(string) Optional. A name for the experiment.
description
(string) Optional. A description of the experiment.
control
Optional. A float between 0 and 1, e.g., 0.4, representing the proportion of the audience that will not receive a push. The remaining audience will be split betweeen the variants. See: Splitting the Audience
audience
Required. The audience for the experiment. See: Audience Selection
device_types
Required. Device types for the experiment. See: Device Type Selection
campaigns
(string) Optional. Campaigns object that will be applied to resulting pushes. See: Campaigns
variants
(array) Required. An array of Variant Specifications. The array must have at least one element. It cannot have more than 26 elements.

The following attributes cannot be specified when the experiment is created. They will only be present when experiment objects are provided by the experiment retrieval and experiment listing endpoints:

JSON Parameters

id
(string) The unique ID assigned to this experiment.
created_at
(string) The time when this experiment's definition was created. The timestamp will be an ISO formatted timestamp given in UTC.
push_id
(string) The push ID associated with this experiment. For examples, please see the Experiment Examples section.

Variant Specification

{
  "name": "<variant name>",
  "description": "<variant description>",
  "schedule": "<scheduled time>",
  "push" : "<push specification>",
  "weight" : "<proportional amount of the audience>",
  "id" : "<id>"
}

This specification defines a push that will be sent to a subset of the experiment's audience.

The audience and device_types fields are not allowed because they are defined in the experiment object.

A variant is defined using the following JSON object:

JSON Parameters

name
Optional. The name of this variant.
description
Optional. A description of the variant.
schedule
Optional. The time at which the push should be sent, as defined by the schedule endpoint.
id
An integer. Holds the ID associated with the variant. Will reflect the position of the variant in the varied array (beginning at 0). The id attribute CANNOT be specified; it will only be provided when the object is returned from the listing or retrieval endpoints.
push
Required. A partial push specification object, as defined by the Push Object specification.
weight
Optional. Defaults to 1. A whole number, which we use to compute the proportion of the audience that will receive this variant. See: Splitting the Audience.
Note

Message Center is not currently supported. See Message Center.

Splitting the Audience

The audience specified by the audience and device_types fields is divided according to the control attribute in the Experiment object and the weight values specified in each Variant Specification object.

If a control is present, the total audience is reduced by the given proportion. The remaining audience is partitioned among the variants. Variants may either evenly split the remaining audience or they may specify weights to use custom splits.

The proportion assigned to a given variant is computed by dividing each variant's weight by the sum of all the weights specified by each variant.

Example:

Let $$W$$ be the sum of the weight attributes from each element in the variants array, $$w_i$$ be the weight specified by the $$i^{th}$$ element. Then we can define the proportion of the remaining audience that will receive the $$i^{th}$$ push from the variants array ($$p_i$$) as $$p_i = w_i / W$$.

For example, using weight attributes of 10, 10, and 5 would split the audience into subsets that are 40%, 40%, and 20% of the remaining audience:

10 + 10 + 5 = 25$$W$$
10 / 25 = 0.4 (40%)$$w_1 / W = p_1$$
10 / 25 = 0.4 (40%)$$w_2 / W = p_2$$
5 / 25 = 0.2 (20%)$$w_3 / W = p_3$$

Here is another example with messy percentages, using weight attributes of 10, 10, 5, and 5. This splits the audience into subsets that are 33.33%, 33.33%, 16.66%, and 16.66% of the remaining audience:

10 + 10 + 5 + 5 = 30$$W$$
10 / 30 = 0.3333 (33.33%)$$w_1 / W = p_1$$
10 / 30 = 0.3333 (33.33%)$$w_2 / W = p_2$$
5 / 30 = 0.1666 (16.66%)$$w_3 / W = p_3$$
5 / 30 = 0.1666 (16.66%)$$H / W = p_h$$

Template Object

{
   "name": "<template name>",
   "description": "<template description>",
   "variables": ["<variable specifications>"],
   "push": "<push-object>",
   "id": "<template-id>",
   "created_at" : "timestamp",
   "modified_at" : "timestamp",
   "last_used" : "timestamp"
}

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

The following JSON object defines an template object which our system stores by template id for later retrieval and listing:

name
Required. The name of the template.
description
Optional. A description of the template.
variables
Required. An array of Variable Specifications.
push

Optional. A partial push specification object, as defined by the Push Object specification. See the Template Creation and Push Example for an example push body with variables. The below fields are not allowed because they are defined in the push template object:

The following attributes cannot be specified when the template is created -- they will only be present when template objects are provided by the template retrieval and template listing endpoints:

id
The unique ID assigned to this template. A string.
created_at
The time when this template's definition was created. The timestamp will be an ISO formatted timestamp given in UTC.
modified_at
The time when this template's definition was last modified. The timestamp will be an ISO formatted timestamp given in UTC.
last_used
The time when this template's definition was last used. The timestamp will be an ISO formatted timestamp given in UTC.


Template Variable Object

{
   "key" : "<key>",
   "name" : "<variable name>",
   "description" : "<variable description>",
   "default_value" : "<fallback value>"
}

A template variable object describes the pieces of your template to override when creating template-based pushes:

JSON Parameters

key
Required. The key used to reference the variable inside the template push. (32 chars, starting with alphabetic character, ending with an alphanumeric character, and consisting of alphanumeric characters and underscores).
name
Optional. The name of the variable.
description
Optional. A description of the variable.
default_value
Optional. A default value of the variable. If a template variable is not specified in a Template Selector, the default value is used.

Push Template Object

{
    "audience" : {
        "OR" : [
            { "tag" : ["sports", "entertainment"]},
            { "device_token" : "871922F4F7C6DF9D51AC7ABAE9AA5FCD7188D7BFA19A2FA99E1D2EC5F2D76506" },
            { "apid" : "5673fb25-0e18-f665-6ed3-f32de4f9ddc6" }
        ]
    },
    "device_types" : [ "ios", "wns" ],
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob"
        }
    }
}

A push template object 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.

JSON Parameters

audience
Required. An audience object.
device_types
Required. An array of device types.
merge_data
Required, a Template Selector.

Scheduled Push Template Payload

Example scheduled push template payload

{
   "name": "Example Schedule Template Push",
   "schedule": {
      "scheduled_time": "2018-05-02T22:10:00Z"
   },
   "audience": {
      "tag": [
         "yanny",
         "laurel"
      ]
   },
   "device_types": [
      "email",
      "ios",
      "android",
      "web"
   ],
   "merge_data": {
      "template_id": "8cce6cc8-7d78-43c7-80b5-81ac24c07672",
      "substitutions": {
         "FIRST_NAME": "Bob",
         "LAST_NAME": "Takahashi",
         "TITLE": null
      }
   },
   "campaigns": {
      "categories": [
         "winter sale",
         "west coast"
      ]
   }
}
A scheduled push template payload describes a scheduled push by referencing a template along with schedule for when that push will be sent. It must also include the audience and device types.

JSON Parameters

name
Optional string, name given to the scheduled push.
schedule
Required object, a schedule specification for when the push should be scheduled.
audience
Required. An audience object.
device_types
Required. Either an array of device types, or the special string selector "all", indicating that the push should be delivered to all configured platforms.
merge_data
Required, a Template Selector.
campaigns
Optional object, campaigns object that will be applied to resulting pushes. See campaigns.

Template Selector

A template selector describes the template id and variable substitutions to use with it.

{
    "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
    "substitutions": {
        "TITLE": "Mr.",
        "FIRST_NAME": "Bob",
        "LAST_NAME": "Jones"
    }
}

JSON Parameters

template_id
Required. The specifies the template to override.
substitutions
Optional. An object containing overrides for your template's variables.

List Object

The list object contains eight attributes:

{
   "ok": true,
   "name": "platinum_members",
   "description": "loyalty program platinum members",
   "extra": { "key": "value" },
   "created": "2013-08-08T20:41:06",
   "last_updated": "2014-05-01T18:00:27",
   "channel_count": 1000,
   "status": "ready"
}

JSON Parameters

  • ok – (Bool)
  • name – (String) The user-provided name of the list. Maximum length of 64 characters
  • description – (String) An optional user-provided description of the list. Maximum length of 1000 characters
  • extra – (Object) An optional user-provided JSON map of string values associated with a list. A key has a maximum length of 64 characters, while a value can be up to 1024 characters. You may add up to 100 key-value pairs.
  • created – (String) The time the list was initially created, in UTC Timestamp form
  • last_updated – (String) The time the identifiers of the list were last updated successfully, in UTC timestamp form
  • channel_count – (Int) A count of resolved channel identifiers for the last uploaded and successfully processed identifier list.
  • status – (String) One of "ready", "processing", or "failure":

    • "ready" - The list was processed successfully and ready for sending

    • "processing" - The list is being processed

    • "failure" - There was an error processing the last uploaded list

Lifecycle List Names

Aside from uploading custom lists, you can send to one of Urban Airship's built-in Lifecycle Lists.

Note

Before using Lifecycle Lists, you must activate them through the Dashboard. See the User Guide documentation for more information.

The table below details the various Lifecycle Lists and the names used to refer to them within the API:

List TypeTime IntervalList API Name
First App OpenLast 7 daysua_first_app_open_last_7_days
First App OpenLast 30 daysua_first_app_open_last_30_days
Opened AppYesterdayua_app_open_last_1_day
Opened AppLast 7 daysua_app_open_last_7_days
Opened AppLast 30 daysua_app_open_last_30_days
Sent NotificationYesterdayua_message_sent_last_1_day
Sent NotificationLast 7 daysua_message_sent_last_7_days
Sent NotificationLast 30 daysua_message_sent_last_30_days
Direct OpenYesterdayua_direct_open_last_1_day
Direct OpenLast 7 daysua_direct_open_last_7_days
Direct OpenLast 30 daysua_direct_open_last_30_days
DormantYesterdayua_has_not_opened_last_1_day
DormantLast 7 daysua_has_not_opened_last_7_days
DormantLast 30 daysua_has_not_opened_last_30_days
UninstallsYesterdayua_uninstalls_last_1_day
UninstallsLast 7 daysua_uninstalls_last_7_days
Rich Page SentLast 7 daysua_message_center_sent_last_7_days
Rich Page SentLast 30 daysua_message_center_sent_last_30_days
Rich Page ViewLast 7 daysua_message_center_view_last_7_days
Rich Page ViewLast 30 daysua_message_center_view_last_30_days

Automation Timing

Automation Timing lets you set delays and delivery time windows for automated messages.

Timing Object

Example:

This example allows outcomes during weekdays from 9 a.m. to 12 p.m. and 1 p.m. to 5 p.m., and on the weekends any time from 9 a.m. to 5 p.m. If a triggering event happens between acceptable time windows, the message will be scheduled to send at the preferred time that is specified in the next allowed_time.

{
   "delay" : {
      "seconds" : 3600
   },
   "schedule" : {
      "type": "local",
      "miss_behavior": "wait",
      "dayparts": [
         {
            "days_of_week" : ["monday", "tuesday", "wednesday", "thursday", "friday"],
            "allowed_times" : [
               {
                  "start" : "09:00:00",
                  "end" : "12:00:00",
                  "preferred" : "09:15:00"
               },
               {
                  "start" : "13:00:00",
                  "end" : "17:00:00",
                  "preferred" : "13:15:00"
               }
            ]
         },
         {
            "days_of_week" : ["saturday", "sunday"],
            "allowed_times" : [
               {
                  "start" : "09:00:00",
                  "end" : "17:00:00",
                  "preferred" : "13:15:00"
               }
            ]
         }
      ]
   }
}

A timing object describes the allowable delivery times for an automated message, given the occurence of the triggering event, and may be comprised of one or both of the following fields:

delay
optional delay object, with delay given in seconds. If present, the value must be larger than zero (0) seconds.
schedule
optional timing schedule object by which to constrain the fulfillments of this pipeline.
Tip

First Open triggers will not work with a delay of zero seconds because of a race condition. We must first register the Channel ID before firing the trigger. We recommend using at least a 60 second delay on first open triggers.

Timing Schedule Object

Note

It may take a few minutes for us to process which time zone a device is in upon first registration, and we default to not sending to devices whose time zone is unknown. Including a delay with a Schedule/"Send during available window" automation may help with this and is highly recommended for automations that are intended to be sent shortly after first app open. This applies only to the local type of timing schedule object (see below).

A timing schedule object is composed of three fields: type, miss_behavior, and dayparts.

type
The mode in which to interpret the times in this schedule. Valid values are local and utc with default being local.
miss_behavior
Behavior of the pipeline when a fulfillment occurs outside the range of all allowed_times of all applicable daypart objects for the pipeline. Value may be either cancel or wait. Deafults to wait if unspecified.

JSON Parameters

wait
Delay the outcome until the preferred time of the next allowed_times window or the beginning of that window.
cancel
Do not process the outcome.
dayparts
A list of daypart objects that, when combined, are non-intersecting and form a nonempty group of time ranges on a nonzero number of days of the week.

JSON Parameters

days_of_week
A list of days of the week to which the allowed_times field is applicable. Valid values in the list are monday, tuesday, wednesday, thursday, friday, saturday and sunday
allowed_times
A list of allowed time objects. Time intervals specified by allowed time objects may not overlap.


Daypart is a term borrowed from the broadcasting industry, used to denote times of day within which you would like to reach your target audience. Some recognizable examples from television and radio include Morning Rush, Afternoon Drive, or Must-see TV. Since advertisers know that the eyeballs (or ears) they are targeting are in abundance during those days and times, they will pay a premium to advertise during those dayparts.

Allowed Time Object

An allowed time object contains the following fields:

start
Start time in ISO 8601 format "hh:mm:ss". Optional, unless end is specified.
end
End time in ISO 8601 format "hh:mm::ss". Optional, unless start is specified.
preferred
optional, preferred time (in ISO 8601 format "hh:mm::ss") to process an outcome. Must be between the start and end time. This time is used when an outcome is triggered or delayed until a disallowed time. If the subsequent allowed times object contains a preferred time, the outcome will be scheduled for that time instead of the next possible time.

Region Data Formats

Region Object

Example:

This location has a Polygon-type geofence and 2 beacons and was imported from Gimbal.

{
    "region_id": "abe5deb3-00d0-446e-8c5d-94b6421a01e0",
    "name": "My Favorite Place",
    "created_at": "2016-06-09T12:34:56",
    "updated_at": "2016-06-09T12:34:56",
    "geofence": {
        "type": "POLYGON",
        "points": [
            {
                "latitude": 90.0,
                "longitude": 180.0
            },
            {
                "latitude": 90.0,
                "longitude": 180.0
            },
            {
                "latitude": 0.0,
                "longitude": 0.0
            }
        ]
    },
    "beacons": [
        {
            "name": "entryway",
            "id": "VLSHLAOEXOFCMLDVTKFQ"
        },
        {
            "name": "Exhibit A",
            "id": "ZAQQMNOZKRFCRPYEUCZI"
        }
    ],
    "attributes": {
        "store_name": "REI"
    },
    "source_info": {
        "source": "GIMBAL",
        "region_id": "4BPSFLKJSDFLKJSDFLKJ",
        "vendor_href": "http://api.gimbal.com/2/places/4BPSFLKJSDFLKJSDFLKJ"
    }
}

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.

A Region object is comprised of the following fields:

"region_id"
A string containing a UUID that is the canonical identifier for this object, elsewhere referred to as "region_id".
"name"
optional, string | a human-readable name for the region
"created_at"
string | ISO timestamp of creation time for the region.
"updated_at"
string | ISO timestamp of last updated time for the region.
"geofence"
optional, a geofence object
"beacons"
optional, an array of beacon objects
"source_info"
optional, a source info object
"attributes"
optional, an attribute object

Geofence object

Examples of each type:

{
    "type": "POLYGON",
    "points": [
        {
            "latitude": 1.000,
            "longitude": 90
        },
        {
            "latitude": 2.000,
            "longitude": 90
        },
        {
            "latitude": 3.000,
            "longitude": 0
        }
    ]
}
{
    "type": "CIRCLE",
    "center": {
        "latitude": 0,
        "longitude": 0
    },
    "radius": 1000
}
{
    "type": "CONFIDENTIAL",
    "source": "Maponics",
    "version": "1.0.17-BETA",
    "id": "TheLouvreMuseumFloodZoneParis"
}

A Geofence object describes a geographical boundary corresponding to a physical location of relevance to the application or application owner.

All Geofence objects have the key "type" indicating which geofence subtype it is and therefore which additional keys it will have.

The "type" key will be one of the following:

  • "POLYGON"

  • "CIRCLE"

  • "CONFIDENTIAL"

A Polygon consists of a single key:

  • "points" - An ordered array of Points that correspond to the vertices of the polygon on the globe

A Circle consists of the following keys:

  • "center" - A single Point indicating the center of the circle

  • "radius" - An integer indicating the size (in meters) of the radius of the circle whose edge is the geofence boundary

A Confidential Geofence object consists of the following keys:

  • "source" - A string, the name of the company providing the geofence

  • "version" - A string, the version number for the source of this geofence

  • "id" - A string, the source-specific identifier for this geofence

Point object

Example:

{
    "latitude": 45,
    "longitude": 179.999999
}

A Point object is a simple JSON object corresponding to a point on the globe, consisting of only two keys:

  • "latitude" - Decimal with maximum 6 digits of decimal precision in the range [-90, 90]

  • "longitude" - Decimal with maximum 6 digits of decimal precision in the range [0, 180)

Beacon object

Example:

{
    "id": "2034071230471204710",
    "name": "Exhibit A"
}

A Beacon object is a simple JSON object consisting of only two keys:

  • "id" - string, the hardware ID of the beacon

  • "name" - optional string, the user-supplied name of the beacon

Source Info object

Example:

{
   "source": "GIMBAL",
   "region_id": "4BPSFLKJSDFLKJSDFLKJ",
   "vendor_href": "https://manager.gimbal.com/api/2/places/4BPSFLKJSDFLKJSDFLKJ"
}

A Source Info object is a simple JSON object providing the details about the origin of the region data. The possible keys are:

  • "source" - string, name of the company who originated the region data

  • "region_id" - string, internal identifier used by source for this region

  • "vendor_href" - (optional) string, URI indicating the location of the original source of this region data

Attribute Object

Example:

{
   "attributes": {
      "park_name": "alberta",
      "type": "park"
   }
}

An attribute object is an object containing the customer-provided region attributes associated with a particular region. See Region Selector for details on setting region attributes.

Custom Event Object

Example:

{
   "occurred": "2016-05-02T02:31:22",
   "user": {
      "android_channel": "e393d28e-23b2-4a22-9ace-dc539a5b07a8"
   },
   "body": {
      "name": "purchased",
      "value": 120.49,
      "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a",
      "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
      "interaction_type": "url",
      "properties": {
         "category": "mens shoes",
         "id": "pid-11046546",
         "description": "sky high",
         "brand": "victory"
      },
      "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
   }
}

When submitting a custom events or multitple custom events, the request body should be either a JSON object or an array of JSON objects with fields described as follows:

occurred
the date and time, formatted according to ISO 8601 in UTC, when the event occurred.
Note

We will only accept events that have occured within the previous 90 days, and no events that occur in the future.

user

an object containing the Urban Airship channel identifier for the user who triggered the event. It has one of the following fields:

  • android_channel

    Urban Airship canonical identifier for a user on an Android device
  • ios_channel

    Urban Airship canonical identifier for a user on an iOS device
  • amazon_channel

    Urban Airship canonical identifier for a user on an Amazon device
  • web_channel

    Urban Airship canonical identifier for a user on a web device
  • channel

    Urban Airship canonical identifier for a user. The Urban Airship system will determine the device.
Note

If no such channel exists, the event will be rejected with a 404 response code.

body

The body object which describes the user action. It has the following fields:

  • name

    A description of what happened. Urban Airship's analytics systems will roll up events with the same name, providing counts and total value associated with the event.
  • value

    If the event is associated with a count or amount, the value field carries that information. Our system will treat this field as though it were money—mathematical operations will use fixed precision representations of the field. We will respect up to six digits of precision to the right of the decimal point. This field is optional; if it is absent its value will default to zero.
  • interaction_type

    String describing the type of interaction that led to the firing of the custom event, e.g., url, social, email. This should almost always be url for web events. See Custom Event to see how we handle custom event objects on the client side.
  • transaction

    Optional. If the event is one in a series representing a single transaction, use the transaction field to tie them together.
  • session_id

    The user session during which the event occurred. You must supply and maintain session identifiers.
  • interaction_id

    Optional. The identifier defining where the event occurred. In a traditional website, this would be the path and query string portion of the URL. In a single page app that uses hash routing, it would be the path, query string, and fragment identifier.
  • properties

    Object supporting key/value pairs that describe event custom properties. Events are limited to 100 properties. Maximum 255 character string length.
Note

All date/time values are represented according to ISO 8601 in UTC. A "T" separator is preferred but not required; it will be included in all date/time values generated by the API. Example: 2015-04-01T12:00:00. A trailing time zone identifier or offset should not be included--UTC is implicit.