Scroll down for code samples, example requests and responses.

Introduction

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

API Request Format

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

Version Syntax

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

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

Transport Layer Security

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

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

Delivery Speed Options

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

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

Boost

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

Throttling

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

Base URL

Select the domain (.com or .eu/asnapieu.com) associated with your Airship project.

https://go.urbanairship.com
The base URL for Airship’s North American cloud site.
https://go.airship.eu
The base URL for Airship’s European cloud site.

Authentication

HTTP Authentication
basic
Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your app key and app secret in appKey:appSecret format, e.g., Basic YXBwX2tleTphcHBfc2VjcmV0.
HTTP Authentication
basic
Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your app key and master secret in appKey:masterSecret format, e.g., Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0.
HTTP Authentication
bearer
A bearer token generated from the Airship dashboard. You can generate tokens for different roles; if your role does not grant you access to a feature, the endpoint will respond with a 401. Tokens can be revoked at will.

Push

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

Send a 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": [ "ios" ]
}

Example Push with Localizations

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

{
   "device_types": [ "ios", "android" ],
   "audience": {
      "tag": "needs_a_greeting",
      "group": "new_customer"
   },
   "notification": {
      "alert": "Hi!"
   },
   "localizations": [
       {
          "language": "de",
          "country": "AT",
          "notification": {
             "alert": "Grüss Gott"
          }
       },
       {
          "language": "de",
          "country": "DE",
          "notification": {
             "alert": "Guten Tag"
          }
       }
    ]
 }

Example Response

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

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

Example Response for Localized Push

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

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078",
        "1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6",
        "939c3796-a755-413b-a36b-3026b1f92df8"
    ],
    "localized_ids": [
       "1a38a2ba-c174-d32f-d01b-481a5d241934"
    ]
}

POST /api/push

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

Security:
HTTP basic auth
HTTP bearer auth

Request Body

A single push object or an array of push objects.

Content-Type: application/json
One of
- Push Object
  A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.
- Array of Push Objects. : Array [Push Object]
  Max items: 100
  Min items: 1

Responses

202

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
A push response contains a list of identifiers for the notifications sent in the request.
OBJECT PROPERTIES
- content_urls : Array [String]
  An array of URLs where the push payload contains a landing page action.
  Max items: 100
  Min items: 1
- localized_ids : Array [String]
  An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).
- message_ids : Array [String]
  An array of message IDs, each uniquely identifying a Message Center message.
- ok : Boolean
  Success.
- operation_id : String
  A unique string identifying the operation, useful for reporting and troubleshooting.
  Format: uuid
- push_ids : Array [String]
  An array of push IDs, each uniquely indentifying a push.
  Max items: 100
  Min items: 1

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

406

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate Push

Missing Payload Example: 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 a 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 in the "device_types" specifier, is invalid. This push is invalid because it includes an iOS channel in the audience selection, but has not specified “ios” as a delivery platform.

{
   "audience": {
      "or": [
         {
            "android_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d0"
         },
         {
            "ios_channel": "a5b41490-16c1-448a-ba27-af1c78c8de09"
         }
      ]
   },
   "device_types": [
      "android"
   ],
   "notification": {
      "alert": "Who wore it better: iOS or Android?"
   }
}

POST /api/push/validate

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

Security:
HTTP basic auth
HTTP bearer auth

Request Body

A single push object or an array of push objects.

Content-Type: application/json
One of
- Push Object
  A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.
- Array of Push Objects. : Array [Push Object]
  Max items: 100
  Min items: 1

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

406

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete 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; a success response means that the deletion has been queued for processing.

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

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

Note

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

Security:
HTTP basic auth

path PARAMETERS

push_id : String Required
The push_id or message_id of the Rich Message you want to delete from users` inboxes.
Format: uuid

Responses

202

The request has been accepted for processing.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedules

Schedule notifications.

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.

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
Count: 2
Data-Attribute: schedules
Content-Type: application/vnd.urbanairship+json; version=3;

{
    "ok": true,
    "count": 2,
    "total_count": 4,
    "next_page": "https://go.urbanairship.com/api/schedules/?start=5c69320c-3e91-5241-fad3-248269eed104&limit=2&order=asc",
    "schedules": [
        {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
            "schedule": { },
            "push": { }
        },
        {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed10A",
            "schedule": { },
            "push": { }
        }
    ]
}

GET /api/schedules

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

Security:
HTTP basic auth

query PARAMETERS

start : String
An optional string ID of the starting element for paginating results.
limit : Integer
An optional integer as maximum number of elements to return.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- count : Integer
- next_page : String
  There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.
  Format: url
- ok : Boolean
  Success.
- schedules : Array [Schedule Object]
  An array of Schedule Objects.
- total_count : Integer

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule a Notification

Example 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": [ "ios", "android" ]
    }
  },
  {
    "name": "Everybody Else",
    "schedule": {
        "best_time": {
          "send_date": "2018-06-03"
        }
    },
    "push": {
        "audience": { "tag": "normalPeople" },
        "notification": { "alert": "Stay Up Late" },
        "device_types": [ "ios", "android" ]
    }
  }
]

Example Scheduled Push with Localizations

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

[
  {
    "name": "Greetings",
    "schedule": {
        "best_time": {
          "send_date": "2019-11-15"
        }
    },
    "push": {
        "device_types": [
          "ios",
          "android"
        ],
        "audience": {
          "tag": "needs_a_greeting",
          "group": "new_customer"
        },
        "notification": {
          "alert": "Hi!"
        },
        "localizations": [
          {
              "language": "de",
              "country": "AT",
              "notification": {
                "alert": "Grüss Gott"
              }
          },
          {
              "language": "de",
              "country": "DE",
              "notification": {
                "alert": "Guten Tag"
              }
          }
        ]
    }
  }
]

Example Response

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

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

POST /api/schedules

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

Security:
HTTP basic auth

Request Body

A single schedule object or an array of schedule objects.

Content-Type: application/json
One of
- Schedule Object
  A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.
- Array [Schedule Object]

Responses

201

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  Success.
- operation_id : String
  A unique string which identifies a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs.
  Format: uuid
- schedule_ids : Array [String]
  An array of schedule IDs, each string uniquely identifying a schedule.
  Max items: 100
  Min items: 1
- schedule_urls : Array [String]
  An array of schedule URLs.
  Max items: 100
  Min items: 1
- schedules : Array [Schedule Object]
  An array of schedule objects.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List a Specific Schedule

Example 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": "I would like to subscribe to your newsletter",
   "schedule": {
      "scheduled_time": "2018-04-01T18:45:30"
   },
   "push": {
      "audience": {
         "tag": [
            "intriguing",
            "ideas"                       ]
      },
      "notification": {
         "alert": "Check your inbox!"
      },
      "device_types": [ "ios", "android" ]
   }
}

GET /api/schedules/{schedule_id}

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

Security:
HTTP basic auth

path PARAMETERS

schedule_id : String Required
A required string ID of the schedule.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update Schedule

Example 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": "I would like to subscribe to your newsletter",
   "schedule": {
      "scheduled_time": "2018-04-01T18:45:30"
   },
   "push": {
      "audience": {
         "tag": [
            "intriguing",
            "ideas",
            "thought_leadership"
         ]
      },
      "notification": {
         "alert": "Check your inbox!"
      },
      "device_types": [ "ios", "android" ]
   }
}

Example Response

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

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

PUT /api/schedules/{schedule_id}

Update the state of a single schedule resource. The body must contain a single schedule object. A PUT cannot be used to create a new schedule; it can only be used to update an existing one.

Security:
HTTP basic auth

path PARAMETERS

schedule_id : String Required
A required string ID of the schedule.

Request Body

A single schedule object.

Content-Type: application/json
Schedule Object
A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

Responses

200

Returned if the scheduled push has been successfully updated.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  Success.
- operation_id : String
  A unique string which identifies a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs.
  Format: uuid
- schedule_urls : Array [String]
  An array of schedule URLs.
  Max items: 100
  Min items: 1
- schedules : Array [Schedule Object]
  An array of schedule objects.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete Schedule

Example 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/{schedule_id}

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

Security:
HTTP basic auth

path PARAMETERS

schedule_id : String Required
A required string ID of the schedule.

Responses

204

The delete operation was successful.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Automation

Manage Automated notifications using the /api/pipelines endpoints.

Note

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

List Existing Pipelines

Example 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

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

Security:
HTTP basic auth

query PARAMETERS

limit : Integer
The maximum number of results to return; this is effectively the page size for the response.
Min: 1
enabled : Boolean
If true, limits the listing to enabled pipelines ("enabled": true). If false or ommitted, lists all pipelines, whether enabled is true or false.
offset : Integer
The first result you want to return. This parameter assists in pagination.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
The response body for a pipelines request.
OBJECT PROPERTIES
- next_page : String
  An URI that points to the next page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a next page we omit the next page link.
- ok : Boolean
  Success.
- operation_id : String
  A unique string identifying a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs.
  Format: uuid
- pipeline_ids : Array [String]
  An array of pipeline IDs.
- pipeline_urls : Array [String]
  An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.
- pipelines : Array [Pipeline Object]
  A list of pipeline objects.
- prev_page : String
  An URI that points to the previous page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a previous page we omit the previous page link.
- total_count : Integer
  The total count of pipelines.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create Pipeline (Automated Message)

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

Example Response

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

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

POST /api/pipelines

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

Security:
HTTP basic auth

Request Body

A single pipeline object or an array of pipeline objects.

Content-Type: application/json
One of
- Pipeline Object
  A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.
- Array [Pipeline Object]

Responses

201

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
The response body for a pipelines request.
OBJECT PROPERTIES
- next_page : String
  An URI that points to the next page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a next page we omit the next page link.
- ok : Boolean
  Success.
- operation_id : String
  A unique string identifying a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs.
  Format: uuid
- pipeline_ids : Array [String]
  An array of pipeline IDs.
- pipeline_urls : Array [String]
  An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.
- pipelines : Array [Pipeline Object]
  A list of pipeline objects.
- prev_page : String
  An URI that points to the previous page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a previous page we omit the previous page link.
- total_count : Integer
  The total count of pipelines.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

409

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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

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

Security:
HTTP basic auth

query PARAMETERS

start : String
Timestamp of the starting element for paginating results.

Responses

200

Returns an array of deleted pipeline objects.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  Success.
- pipelines : Array [Object]
  ARRAY ITEM
  - Object
    OBJECT PROPERTIES
    deletion_time : String
    An ISO 8601 UTC timestamp indicating the date and time that the pipeline was deleted.
    Format: date-time
    pipeline_id : String
    The unique identifier for a pipeline.
    Format: uuid

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate Pipeline

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

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

{
    "ok": true
}

POST /api/pipelines/validate

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

Security:
HTTP basic auth

Request Body

A single pipeline object or an array of pipeline objects.

Content-Type: application/json
One of
- Pipeline Object
  A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.
- Array of Push Templates : Array [Pipeline Object]

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

406

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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": [ "ios", "android" ],
            "notification": { "alert": "Hello new customer!" }
          }
      },
      "status": "live",
      "uid": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
      "url": "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
    }
}

GET /api/pipelines/{pipeline_id}

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

Security:
HTTP basic auth

path PARAMETERS

pipeline_id : String Required
The pipeline you want to return or modify.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
The response body for a pipelines request.
OBJECT PROPERTIES
- next_page : String
  An URI that points to the next page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a next page we omit the next page link.
- ok : Boolean
  Success.
- operation_id : String
  A unique string identifying a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs.
  Format: uuid
- pipeline_ids : Array [String]
  An array of pipeline IDs.
- pipeline_urls : Array [String]
  An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.
- pipelines : Array [Pipeline Object]
  A list of pipeline objects.
- prev_page : String
  An URI that points to the previous page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a previous page we omit the previous page link.
- total_count : Integer
  The total count of pipelines.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update Pipeline

Example 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/{pipeline_id}

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

Security:
HTTP basic auth

path PARAMETERS

pipeline_id : String Required
The pipeline you want to return or modify.

Request Body

A single pipeline object or an array of pipeline objects.

Content-Type: application/json
Pipeline Object
A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

409

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete Pipeline

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/{pipeline_id}

Delete a pipeline.

Security:
HTTP basic auth

path PARAMETERS

pipeline_id : String Required
The pipeline you want to return or modify.

Responses

204

An API request was successful, but there is no response body to return.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

A/B Tests

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

Experiment Listing

Example 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-Length: 123
Data-Attribute: experiments
Count: 2
Total-Count: 2
Content-Type: application/vnd.urbanairship+json; version=3;

 {
   "ok" : "true",
   "count" : 2,
   "total_count" : 2,
   "experiments" : [{
     "name" : "Experiment 1",
     "control" : 0.33,
     "audience" : "all",
     "device_types": [ "ios", "android" ],
     "variants" : [{
       "push" : {
         "notification" : {
           "alert" : "message 1"
         }
       },
       "id" : 0,
     },
     {
       "push" : {
           "notification" : {
             "alert" : "message 2"
           }
       },
       "id" : 1,
     }],
     "id" : "b5bc3dd1-9ea4-4208-b5f1-9e7ac3fe0502",
     "created_at" : "2016-03-03T21:08:05",
     "push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
   }, {
     "name" : "Experiment 2",
     "description" : "The second experiment",
     "audience" : "all",
     "device_types": [ "ios", "android" ],
     "variants" : [{
       "push" : {
         "notification" : {
           "alert" : "message 1"
         }
       },
       "id" : 0,
     },
     {
       "push" : {
           "notification" : {
             "alert" : "message 2"
           }
       },
       "id" : 1,
     }],
     "id" : "e464aa7e-be40-4994-a290-1bbada7187d8",
     "created_at" : "2016-03-03T21:08:05",
     "push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
   }]
}

GET /api/experiments

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

Security:
HTTP basic auth

query PARAMETERS

limit : Integer
Positive maximum number of elements to return per page. The default limit is 10 entries with a maximum of 100 entries.
Max: 100
Min: 1
offset : Integer
A zero-based integer offset into the result set. If you do not use an offset, results will begin with the most recently sent experiment. If offset is greater than the number of queryable experiments, an empty result will be returned.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- count : Integer
  The number of items returned in this page of results.
- experiments : Array [Experiment Object]
  Experiment objects sorted by either created_at from newest to oldest. The number of objects will never exceed the limit specified in the request.
- next_page : String
  A relative URL leading to the next page of results. If there are no more results, next_page is absent.
- ok : Boolean
  If true, the call was successful.
- total_count : Integer
  The total number of results.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create Experiment (A/B Test)

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

Example Response

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

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

POST /api/experiments

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

Security:
HTTP basic auth

Request Body

Content-Type: application/json
Experiment Object
An experiment object describes an A/B test, including the audience and variant portions.

Responses

201

The experiment was created.

RESPONSE HEADERS

Location : String
The newly created experiment.
Format: uri

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
The response body for an experiment request.
OBJECT PROPERTIES
- experiment_id : String
  Unique identifier for an experiment.
  Format: uuid
- ok : Boolean
  If true, the expeiment was successfully created. If false, the expriment was not created.
- operation_id : String
  A unique string that represents a single API call, used to identify the operation or side-effects in reporting and troubleshooting logs.
  Format: uuid
- push_id : String
  Unique identifier for a push.
  Format: uuid

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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-Length: 123
Data-Attribute: experiments
Content-Type: application/vnd.urbanairship+json; version=3;

{
    "ok": "true",
    "count": 2,
    "total_count": 2,
    "experiments": [
        {
            "id": "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
            "name": "Experiment 1",
            "audience": "all",
            "device_types": [ "ios", "android" ],
            "variants": [
                {
                    "id": 0,
                    "schedule": {
                        "scheduled_time": "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": [ "ios", "android" ],
            "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

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

Security:
HTTP basic auth

query PARAMETERS

limit : Integer
Positive maximum number of elements to return per page. The default limit is 10 entries with a maximum of 100 entries.
Max: 100
Min: 1
offset : Integer
A zero-based integer offset into the result set. If you do not use an offset, results will begin with experiment scheduled to begin at the soonest date-time. If the offset is greater than the number of queryable experiments, the result set will be empty.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- count : Integer
  The number of items in this page of results.
- experiments : Array [Experiment Object]
  Experiments listed by scheduled_time in ascending time order. The number of objects will never exceed the limit specified in the request.
- next_page : String
  A relative URL leading to the next page of results. If there are no more results, next_page is absent.
- ok : Boolean
  If true, the operation completed successfully and returns an expected result set.
- total_count : Integer
  The total number of results.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete 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-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3;

{
  "ok" : "true",
  "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}

DELETE /api/experiments/scheduled/{experiment_id}

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

Security:
HTTP basic auth

path PARAMETERS

experiment_id : String Required
The unique identifier of the experiment.

Responses

200

Returned if the experiment has been succesfully deleted.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
The response body for a pipelines deletion request.
OBJECT PROPERTIES
- ok : Boolean
  Success.
- operation_id : String
  A unique string that represents a single API call, used to identify the operation or side-effects in reporting and troubleshooting logs.
  Format: uuid

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

405

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate Experiment

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

Example Response

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

{
  "ok" : "true",
  "operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}

POST /api/experiments/validate

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

Security:
HTTP basic auth

Request Body

A single experiment object.

Content-Type: application/json
Experiment Object
An experiment object describes an A/B test, including the audience and variant portions.

Responses

200

The experiment is valid.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, the operation completed successfully and returns an expected response.
- operation_id : String
  A unique string that represents a single API call, used to identify the operation or side-effects in reporting and troubleshooting logs.
  Format: uuid

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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-Length: 123
Data-Attribute: experiment
Content-Type: application/vnd.urbanairship+json; version=3;

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

GET /api/experiments/{experiment_id}

Look up an experiment (A/B Test).

Security:
HTTP basic auth

path PARAMETERS

experiment_id : String Required
The ID of the experiment you want to look up.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- experiment : Experiment Object
  An experiment object describes an A/B test, including the audience and variant portions.
- ok : Boolean
  If true, the operation completed successfully and returns a result set.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Personalization

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

Note

Consider the /templates API deprecated. You should use Airship’s new Templates user interface to create your templates and send templated messages using the /create-and-send or /pipelines APIs.

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
Data-Attribute: templates
Count: 1
Total-Count: 1
Content-Type: application/vnd.urbanairship+json; version=3;

{
    "ok" : true,
    "count": 1,
    "total_count": 1,
    "templates": [
        {
            "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "created_at": "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 all existing templates. Returns an array of template objects in the templates attribute.

Note

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

Security:
HTTP basic auth

query PARAMETERS

page : Integer
Specifies the desired page number. Defaults to 1.
page_size : Integer
Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.
sort : String
Specifies the name of the field you want to sort results by. Defaults to created_at.
Possible values: created_at, modified_at, last_used
order : String
The direction of the sort, asc for ascending, and desc for descending. Defaults to asc.
Possible values: asc, desc

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- count : Integer
  The number of templates in the current response; this is effectively the page size.
- next_page : String
  There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.
  Format: url
- ok : Boolean
  Success.
- prev_page : String
  Link to the previous page, if available.
  Format: url
- templates : Array [Template Object]
  An array of Template Objects.
- total_count : Integer
  The total number of templates.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create 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
Location: https://go.urbanairship.com/api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161
Content-Type: application/vnd.urbanairship+json; version=3

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

POST /api/templates

Create a new template.

Note

Security:
HTTP basic auth

Request Body

A single template object.

Content-Type: application/json
Template Object
A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.

Responses

201

The template was created.

RESPONSE HEADERS

Location : String
The uri for the template, used for later updates or sends.
Format: uri

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, the operation completed successfully and returns an expected response.
- operation_id : String
  A unique string identifying the operation, useful for reporting and troubleshooting.
  Format: uuid
- template_id : String
  A unique string identifying the template, used to call the template for pushing and other operations.
  Format: uuid

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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": [ "ios" ],
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob",
            "LAST_NAME": "Smith",
            "TITLE": ""
        }
    }
}

Example Response

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

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

POST /api/templates/push

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

Note

Security:
HTTP basic auth

Request Body

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

Content-Type: application/json
One of
- Push Template Payload
  A push template payload defines a push by overriding the variables defined in a specific Template Object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.
- Array of Push Templates : Array [Push Template Payload]

Responses

202

The push notification has been accepted for processing.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, the operation completed successfully and returns an expected response.
- operation_id : String
  A unique string identifying the operation, useful for reporting and troubleshooting.
  Format: uuid
- push_ids : Array [String]
  An array of the push IDs for this operation.
  Max items: 100
  Min items: 1

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

406

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate A Template

Example 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": [ "ios" ],
    "audience": {
       "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob",
            "LAST_NAME": "Smith",
            "TITLE": ""
        }
    }
}

Example Response

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

{
    "ok" : true
}

POST /api/templates/push/validate

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

Security:
HTTP basic auth

Request Body

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

Content-Type: application/json
One of
- Push Template Payload
  A push template payload defines a push by overriding the variables defined in a specific Template Object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.
- Array [Push Template Payload]

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

406

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule a Templated Push

Example 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": [ "ios" ],
        "audience": {
           "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
        },
        "merge_data": {
            "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "substitutions": {
                "FIRST_NAME": "Bob",
                "LAST_NAME": "Takahashi",
                "TITLE": null
            }
        }
    },
    {
        "name": "Hello Joe",
        "schedule": {
           "scheduled_time": "2018-05-05T18:00:00Z"
        },
        "device_types": [ "android" ],
        "audience": {
           "android_channel": "df6a6b50-9843-0304-d5a5-743f246a4946"
        },
        "merge_data": {
            "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "substitutions": {
                "FIRST_NAME": "Joe",
                "LAST_NAME": "Smith",
                "TITLE": "Sir"
            }
        }
    }
]

Example Response

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

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

POST /api/templates/schedules

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

Request Body

an array of scheduled pushes

Content-Type: application/json
Array [Object]
ARRAY ITEM
- Object
  A scheduled push template object defines a push by overriding the variables defined in a specific Template Object and the schedule determining when the push should be sent. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.
  OBJECT PROPERTIES
  - audience : Audience SelectorRequired
    The audience for the template.
  - campaigns : Campaigns Object
    An object specifying custom campaign categories related to the notification.
  - device_types : Array [String]Required
    An array containing one or more strings identifying targeted platforms. Accepted platforms are ios, android, amazon, wns, web, sms, email, and open::<open_platform_name> (using the open_platform_name value of your open channel).
    Min items: 1
  - merge_data : ObjectRequired
    A template selector describing the template ID and variable substitutions to use with it.
    OBJECT PROPERTIES
    substitutions : Object
    An object containing overrides for your template’s variables. The key-value pairs in this object are the value of the key items defined in your template, and the values you want to substitute for the default_value of those keys.
    template_id : StringRequired
    Specifies the template to override.
  - name : String
    An optional name for the scheduled push operation.
  - schedule : Schedule SpecificationRequired
    Determines when the push is sent.

Responses

202

The scheduled push has been accepted for processing.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  Success.
- operation_id : String
  A unique string which identifies a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs.
  Format: uuid
- schedule_ids : Array [String]
  An array of schedule IDs.
  Max items: 100
  Min items: 1
- schedule_urls : Array [String]
  An array of schedule URLs. The URL for each schedule is the schedules endpoint, appended with the schedule_id of the schedule.
  Max items: 100
  Min items: 1
- schedules : Array [Schedule Object]
  An array of schedule objects.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

406

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Lookup a 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

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

{
    "ok" : true,
    "template": {
        "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "created_at": "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}

Fetch the current definition of a single template.

Note

Security:
HTTP basic auth

path PARAMETERS

template_id : String Required
A required string ID of the template.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, the operation completed successfully and returns an expected response.
- template : Template Object
  A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update Template

Example 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. The request body is a partially-defined template object, containing the field(s) you want to change and their updated values.

Note

Security:
HTTP basic auth

path PARAMETERS

template_id : String Required
A required string ID of the template.

Request Body

Content-Type: application/json
Object
A partially-defined template object. Provide only variables and push items that you want to update.
OBJECT PROPERTIES
- description : String
  The description of the template.
- name : StringRequired
  The name of the template.
- push : Template Push Object
  A partial push object describing everything about a push notification, except for the audience and device_types (which are defined in the pushTemplatePayload object).
- variables : Array [Template Variables]
  An array of Variable Specifications.

Responses

200

Returned if the template has been succesfully updated.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, the operation completed successfully and returns an expected response.
- operation_id : String
  A unique string identifying the operation, useful for reporting and troubleshooting.
  Format: uuid

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete 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. If the template is successfully deleted, the response does not include a body.

Note

Security:
HTTP basic auth

path PARAMETERS

template_id : String Required
A required string ID of the template.

Responses

200

The template with given ID has been succesfully deleted.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, the operation completed successfully and returns an expected response.
- operation_id : String
  A unique string identifying the operation, useful for reporting and troubleshooting.
  Format: uuid

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Regions

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

Region Listing

Example 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
Data-Attribute: regions
Link: <https://go.urbanairship.com/api/regions?limit=100&start=100>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "next_page": "https://go.urbanairship.com/api/regions?limit=100&start=100",
   "count": 100,
   "regions": [
       {
           "region_id": "abe5deb3-01d0-436e-8c5d-94b6421a01e0",
           "name": "My Favorite Place",
           "created_at": "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

Get a paginated list regions. The result is an array of Region Objects under the “regions” key.

Security:
HTTP basic auth

query PARAMETERS

limit : Integer
Determines the number of results per page. Defaults to 100 with a maximum of 1000 regions per page. Setting a limit greater than 1000returns a 400 response.
Max: 1000
start : Integer
A zero-based integer offset into the ordered list of regions, useful for addressing pages directly.

Responses

200

Returns OK for success.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- count : Integer
  The total number of regions returned.
- next_page : String
  There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.
  Format: url
- ok : Boolean
  Success.
- regions : Array [Region Object]
  An array of Region Objects.

400

returned when limit is greater than 1000.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Region Lookup

Example 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
Data-Attribute: region
Content-Type: application/vnd.urbanairship+json; version=3;

{
    "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 details for a specific region.

Security:
HTTP basic auth

path PARAMETERS

region_id : String Required
The region you want to lookup.

Responses

200

Returns OK for success.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  if true, indicates success.
- region : Region Object
  A Region object describes a geographical boundary or set of hardware identifiers and associated attributes that correspond to a physical location of relevance to the application or application owner.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Custom Events

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

Add Custom Events

Example Request

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

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

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 or named user, to Airship. You can use these events as custom event triggers for Automation or Journeys and can use handlebars to personalize messages using custom event properties (information in the body.properties object).

Note

Requests complete validation before returning a response.
Requests are authenticated with a bearer token which can provide access to this resource alone, or to this resource and others.
Requests are 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.

Security:
HTTP bearer auth

Request Body

An array of custom event objects.

Content-Type: application/json
Array [Custom Event object]
Max items: 100
Min items: 1

Responses

200

Returned on success.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  Success.
- operation_id : String
  A unique string identifying the API interaction. You can use the operation_id in support requests if something goes wrong.
  Format: uuid

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Channels

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

Channel Listing

Example Request

GET /api/channels 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

{
   "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_systems",
         "alias": "null",
         "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_systems",
         "alias": "null",
         "tags": [
            "tag1",
            "tag2"
         ],
         "tag_groups": {
            "tag_group_1": ["tag1", "tag2"],
            "tag_group_2": ["tag1", "tag2"]
         },
         "ios": {
            "badge": 0,
            "quiettime": {
               "start": null,
               "end": null
            },
            "tz": null
         }
      }
   ]
}

GET /api/channels

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

Security:
HTTP basic auth
HTTP bearer auth

Responses

200

Returns OK for success with the JSON response.

RESPONSE HEADERS

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- channels : Array [Channel Object]
  An array of Channel Objects.
- next_page : String
  If there is more than one page of results, use this link to get the next page of results.
  Format: url
- ok : Boolean
  Success.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Set or Remove Attributes on Channels

Example Request

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

{
    "audience": {
       "android_channel": ["b8f9b663-0a3b-cf45-587a-be880946e881"]
    },
    "attributes": [
       {
             "action": "set",
             "key": "major_league",
             "value": "sf_giants"
       },
       {
             "action": "remove",
             "key": "minor_league"
       },
       {
             "action": "set",
             "key": "position",
             "value": "LF"
       }
    ]
}

Example Request with Dates and Numbers

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

{
    "audience": {
       "android_channel": ["b8f9b663-0a3b-cf45-587a-be880946e881"]
    },
    "attributes": [
       {
             "action": "set",
             "key": "birthday",
             "value": "1983-03-15 10:00:00"
       },
       {
             "action": "set",
             "key": "fav_number",
             "value": 42
       },
       {
             "action": "remove",
             "key": "another_attribute"
       }
    ]
}

POST /api/channels/attributes

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

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
Include an audience selector and an array of attributes objects in your request.
All of
- Audience Selector
  An audience selector forms the expression that determines the set of channels to target.
- Array of Attributes Objects : Array [Attributes Object]

Responses

200

The operation was successful.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, your request was successful.
- warning : String
  Alerts you if your request could not be processed. You may receive a 200 with a warning if you provide a value that does not match your attribute type. For example, an attribute that expects a numeric value will allow a value of “25”, but fail if you input “twenty-five”.

400

Parsing or validating the request failed.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Channel Tags

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, remove, or set tags on a channel.

Important

A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response.

While we support billions of channels, testing a channel by repeatedly updating its tags can cause latency and service interruptions.

We support up to 1000 tags per channel. Adding more than 1000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per channel, and they will help you find an alternative.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
Object
A single request body may contain add and/or remove objects, or a single set object. At least one of the add, remove, or set objects must be present in a request.
OBJECT PROPERTIES
- add : Tag Group Object
  Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
- audience : ObjectRequired
  Specifies one or more channels that you want to apply tag operations to.
  OBJECT PROPERTIES
  amazon_channel : Array [String]
  The unique channel identifier for an Amazon device.
  Max items: 1000
  Min items: 1
  android_channel : Array [String]
  The unique channel identifier for an Android device.
  Max items: 1000
  Min items: 1
  channel : Array [String]
  The unique channel identifier for email, sms, open, or web device types.
  Max items: 1000
  Min items: 1
  ios_channel : Array [String]
  The unique channel identifier for an iOS device.
  Max items: 1000
  Min items: 1
- remove : Tag Group Object
  Removes the specified tags from the channel.
- set : Tag Group Object
  Assigns a list of tags exactly; any previously set tags that are not in this current list will be removed.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, your request was processed normally.
- warnings : Array [String]
  Returned when some tag groups could not be updated. Contains a string indicating each tag group that could not be updated and the reason the update failed.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Uninstall Channels

Example 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": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "device_type": "ios"
   },
   {
      "channel_id": "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
      "device_type": "android"
   }
]

Example Response

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

{
   "ok": true
}

POST /api/channels/uninstall

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

Uninstallation is handled automatically by the Airship SDK and push systems. If a user decides to opt-in to communications again (either by using your app or other user preferences), they will create a new channel and a new set of analytic data.

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

Note

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

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
Array [Object]
Max items: 1000
Min items: 1
ARRAY ITEM
- Object
  specifies the channel ID and device type you want to uninstall.
  OBJECT PROPERTIES
  - channel_id : StringRequired
    The channel ID.
  - device_type : StringRequired
    The device type of the channel. Valid values are ‘ios’, ‘amazon’, ‘android’, ‘web’, ‘open’.
    Possible values: ios, android, amazon, web, open

Responses

202

The request has been accepted for processing.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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_systems",
      "alias": null,
      "tags": [
         "tag1",
         "tag2"
      ],
      "tag_groups": {
         "tag_group_1": ["tag1", "tag2"],
         "tag_group_2": ["tag1", "tag2"]
      },
      "ios": {
         "badge": 0,
         "quiettime": {
            "start": null,
            "end": null
         },
         "tz": "America/Los_Angeles"
      }
   }
}

GET /api/channels/{channel_id}

Fetch an individual channel registered to the app key, along with associated data and metadata.

Note

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

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

channel_id : String Required
The channel you want to look up.

Responses

200

Tags added to a channel using /named_users/tags are not returned from this endpoint. To view those tags, you must lookup the named user associated with the channel.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- channel : Channel Object
  A channel object.
- ok : Boolean
  Success.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Open Channels

Open Channels are custom communication channels that you can configure for messaging, using the same segmentation and scheduling tools available on natively-supported platforms (iOS, Android, etc). With Open Channels, you define a new open platform, e.g., SMS, Slack, Acme™ Smart Toasters, and register the new platform with Airship. If you are sending through the push API, platform overrides for open platforms are covered in 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
Location: https://go.urbanairship.com/api/channels/df6a6b50-9843-0304-d5a5-743f246a4946
Content-Type: application/vnd.urbanairship+json; version=3;

{
    "ok": true,
    "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}

POST /api/channels/open

Create a new open channel, or update an existing open channel.

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.

Important

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

Security:
HTTP basic auth

Request Body

An open channel object.

Content-Type: application/json
Object
OBJECT PROPERTIES
- channel : ObjectRequired
  Properties of the open channel object.
  OBJECT PROPERTIES
  address : StringRequired
  Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel id. New addresses on existing channels will overwrite old associations.
  locale_country : String
  The two-letter country locale short code. Will set the ua_locale_country tag group to the specified value.
  locale_language : String
  The two-letter language locale short code. Will set the ua_locale_language tag group to the specified value.
  open : ObjectRequired
  Open channel-specific properties.
  OBJECT PROPERTIES
  identifiers : Object
  Optional object with string-to-string key:value pairs that represent non-segmentable identifiers for the channel in your delivery systems. Delivered as part of webhook payloads. If present, the value will overwrite (not union with) existing identifier records.
  Max items: 100
  OBJECT PROPERTIES
  * : String
  open_platform_name : StringRequired
  The name of the open platform to which you are registering this channel.
  opt_in : BooleanRequired
  If false, no payloads will be delivered for the channel.
  tags : Array [String]
  A list of strings used for audience targeting. When used for this endpoint, operates like the tags { set {}} operation; specified tags are applied, and all other tags are removed.
  Max items: 1000
  Min items: 1
  timezone : 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.
  type : StringRequired
  Required string. The only acceptable value for an open channel is open.
  Possible values: open

Responses

200

Returned if the new channel is created successfully or if an existing channel was found for the specified open_platform_name and address.

RESPONSE HEADERS

Location : String
Used for later API calls for this channel.
Format: uri

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- channel_id : String
  Identifies the new open channel or the open channel you successfully updated.
  Format: uuid
- ok : Boolean
  Success.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

429

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Open Channel Tags

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. Open channels are identified by address, not by thier channel_id.

Important

A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response.

While we support billions of channels, testing a channel by repeatedly updating its tags can cause latency and service interruptions.

Security:
HTTP basic auth

Request Body

Content-Type: application/json
Object
Add, remove, or set tags on a channel. A single request body may contain add and/or remove objects, or a single set field. At least one of the add, remove, or set objects must be present in a request.
OBJECT PROPERTIES
- add : Tag Group Object
  Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
- audience : ObjectRequired
  The request body containing an address and open_platform_name.
  OBJECT PROPERTIES
  address : StringRequired
  Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel id. New addresses on existing channels will overwrite old associations.
  open_platform_name : StringRequired
  An alphanumeric string that must be the name of a pre-created open platform object.
  Max length: 128
  Min length: 1
- remove : Tag Group Object
  Removes the specified tags from the channel.
- set : Tag Group Object
  Assigns a list of tags exactly; any previously set tags that are not in this current list will be removed.

Responses

200

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Uninstall 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

Uninstall a channel needing to know its channel ID. You cannot send notifications to, or get channel information for, an uninstalled channel.

Security:
HTTP basic auth

Request Body

An address and the open_platform_name you want to uninstall the address from.

Content-Type: application/json
Open Channel Identifier : Object
The request body containing an address and open_platform_name.
OBJECT PROPERTIES
- address : StringRequired
  Where notifications sent to this channel_id will be sent. Examples: email address, phone number. If missing, channel_id must be present. The address is one-to-one with the channel id. New addresses on existing channels will overwrite old associations.
- open_platform_name : StringRequired
  An alphanumeric string that must be the name of a pre-created open platform object.
  Max length: 128
  Min length: 1

Responses

202

The request has been accepted for processing.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Email

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",
        "commercial_opted_in": "2018-10-28T10:34:22",
        "address": "name@example.com",
        "timezone" : "America/Los_Angeles",
        "locale_country" : "US",
        "locale_language" : "en"
     }
  }

Example Response

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

{
    "ok": true,
    "channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd"
}

POST /api/channels/email

Create a new email channel or update an existing channel. If you provide the email address of an existing channel, the call is treated as a PUT.

If you want to update the address of an existing channel, see the Update email channel endpoint.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

A single email channel object.

Content-Type: application/json
Email Channel Object : Object
An email channel object is the object used to create or update channels.
There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal noticies, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out).
Each channel uses opted_in and opted_out keys for both commercial and transactional emails. The value of each key is the date-time when the user subscribed to or unsubscribed from emails of either type — commercial or transactional. If a user has opted out of a particular email type (or the user never opted into commercial emails), and the user is a part of your audience for a message of that type, the email designated for the opted-out user is dropped at delivery time. These values are all optional. However, an email channel with no opted_in or opted_out values can only receive transactional emails.
If a channel has both opt_in and opt_out values for a particular email type, Airship respects the most recent date-time. So, if a user opted into commercial emails after previously opting out, that user can receive commercial emails from you even though that user’s channel possesses both commercial_opted_in and commercial_opted_out values; if the opt-in date is prior to the opt-out date, the user will not receive commercial emails from you.
OBJECT PROPERTIES
- channel : ObjectRequired
  OBJECT PROPERTIES
  address : StringRequired
  The email address being registered.
  commercial_opted_in : String
  The date-time when a user gave explicit permission to receive commercial emails.
  Format: date-time
  commercial_opted_out : String
  The date-time when a user explicitly denied permission to receive commercial emails.
  Format: date-time
  locale_country : String
  The device property tag related to locale country setting.
  locale_language : String
  The device property tag related to locale language setting.
  timezone : String
  The device property tag related to timezone setting.
  transactional_opted_in : String
  The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.
  Format: date-time
  transactional_opted_out : String
  The date-time when a user explicitly denied permission to receive transactional emails.
  Format: date-time
  type : StringRequired
  The type of channel you are registering. For email channels, this value must be email.
  Possible values: email

Responses

201

The email channel was created.

RESPONSE HEADERS

Location : String
The newly created email channel.
Format: uri

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
The response body for an email channel request.
OBJECT PROPERTIES
- channel_id : String
  A unique string identifying the email channel.
  Format: uuid
- ok : Boolean
  Either true or false. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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

Add, remove, or set tags for a single email channel.

Important

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

Security:
HTTP basic auth
HTTP bearer auth

Request Body

A single request body can contain an add and/or remove field, or a single set field. One or more of the add, remove, or set keys must be present in the request.

Content-Type: application/json
Object
OBJECT PROPERTIES
- add : Tag Group Object
  Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
- audience : ObjectRequired
  Specifies the email address you want to perform tag operations against. Must contain a single email_address key.
  Max properties: 1
  OBJECT PROPERTIES
  email_address : StringRequired
  The email address you want to modify tags for. Accepts a single string value representing an email address.
- remove : Tag Group Object
  Removes the specified tags from the channel.
- set : Tag Group Object
  Assigns a list of tags exactly; any previously set tags that are not in this current list are removed.

Responses

200

Returns OK for success. If a tag request is partially valid, i.e. at least one tag group exists and is active, a 200 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.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

Bad Request. Parsing or validating the request failed. If a tag is present in both the add and remove fields, a HTTP 400 response will be returned.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Uninstall 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

Removes an email address from Airship. Use with caution. If the uninstalled email address opts-in again, it might generate a new channel_id. If a user generates a new channel_id when they opt-in again, the new channel_id cannot be reassociated with any opt-in information, tags, named users, Performance Analytics reports, or other information from the that belonged to the previously-uninstalled email channel.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

An email address of the channel to uninstall.

Content-Type: application/json
Object
OBJECT PROPERTIES
- email_address : StringRequired
  The email address of the channel to uninstall.

Responses

202

The request has been accepted for processing.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Lookup an Email Address

Example Request

GET /api/channels/email/name%40domain.com HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

Example Response

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

{
   "ok": true,
   "channel": {
      "channel_id": "01234567-890a-bcde-f012-3456789abc0",
      "device_type": "email",
      "installed": true,
      "created": "2013-08-08T20:41:06",
      "named_user_id": "some_id_that_maps_to_your_systems",
      "tag_groups": {
         "tag_group_1": ["tag1", "tag2"],
         "tag_group_2": ["tag1", "tag2"]
      },
      "address": null,
      "opt_in": true,
      "commercial_opted_in": "2018-10-28T10:34:22",
      "commercial_opted_out": "2018-06-03T09:15:00",
      "transactional_opted_in": "2018-10-28T10:34:22",
      "last_registration": "2014-05-01T18:00:27"
   }
}

GET /api/channels/email/{email_channel_id}

Returns a channel by email address. For security, email addresses are one-way hashed and aren’t returned when you look up a channel by ID. Use this endpoint to find a channel belonging to a particular email address.

You may need to escape the “@” character in URLs using%40.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

email_channel_id : String Required
The email address of the channel you want to look up.

Responses

200

A channel exists for the email address

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Describes a channel.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update an Email Channel

Example Request - Update Email Address

PUT /api/channels/email/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

 {
     "channel" : {
        "type": "email",
        "address": "new.name@new.domain.com"
     }
  }

Example Response

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

{
    "ok": true,
    "channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd"
}

PUT /api/channels/email/{email_channel_id}

Update an email channel. You can use this endpoint to update the email address associated with a channel and subscription/unsubscription values.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

email_channel_id : String Required
The email channel_id you want to modify.

Request Body

Content-Type: application/json
Email Channel Object : Object
An email channel object is the object used to create or update channels.
There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal noticies, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out).
Each channel uses opted_in and opted_out keys for both commercial and transactional emails. The value of each key is the date-time when the user subscribed to or unsubscribed from emails of either type — commercial or transactional. If a user has opted out of a particular email type (or the user never opted into commercial emails), and the user is a part of your audience for a message of that type, the email designated for the opted-out user is dropped at delivery time. These values are all optional. However, an email channel with no opted_in or opted_out values can only receive transactional emails.
If a channel has both opt_in and opt_out values for a particular email type, Airship respects the most recent date-time. So, if a user opted into commercial emails after previously opting out, that user can receive commercial emails from you even though that user’s channel possesses both commercial_opted_in and commercial_opted_out values; if the opt-in date is prior to the opt-out date, the user will not receive commercial emails from you.
OBJECT PROPERTIES
- channel : ObjectRequired
  OBJECT PROPERTIES
  address : StringRequired
  The email address being registered.
  commercial_opted_in : String
  The date-time when a user gave explicit permission to receive commercial emails.
  Format: date-time
  commercial_opted_out : String
  The date-time when a user explicitly denied permission to receive commercial emails.
  Format: date-time
  locale_country : String
  The device property tag related to locale country setting.
  locale_language : String
  The device property tag related to locale language setting.
  timezone : String
  The device property tag related to timezone setting.
  transactional_opted_in : String
  The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.
  Format: date-time
  transactional_opted_out : String
  The date-time when a user explicitly denied permission to receive transactional emails.
  Format: date-time
  type : StringRequired
  The type of channel you are registering. For email channels, this value must be email.
  Possible values: email

Responses

200

The email channel was updated.

RESPONSE HEADERS

Location : String
The updated email channel.
Format: uri

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
The response body for an email channel request.
OBJECT PROPERTIES
- channel_id : String
  A unique string identifying the email channel.
  Format: uuid
- ok : Boolean
  Either true or false. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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": "US:12345",
  "opted_in": "2018-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en"
}

Example Response (With ‘opted_in’)

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

{
  "ok": true,
  "operation_id": "62077236-d032-11e9-af71-ab156113d166",
  "channel_id": "7c5d7328-9bb4-4ff7-86b0-96a5f1da5868"
}

Example Response (Without ‘opted_in’)

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

{
  "ok": true,
  "operation_id": "62077236-d032-11e9-af71-ab156113d166",
  "push_id": "26350f60-d033-11e9-80e3-33def0e528d1",
  "channel_id": "79fbe330-d033-11e9-adfb-df10b89c5e04",
  "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

Create an SMS channel. If the channel has not opted in yet (the request did not contain opted_in), Airship creates the channel with opt_in set to false and the user receives a message prompting them to complete the opt-in flow; you can assign assign tags and organize pending channels before the user has finished the opt-in process, but you cannot send messages to channels until they opt in to your audience.

SMS notifications require a sender - a number that recipients will receive SMS notifications from. Contact Airship Support or your Account Manager to provision your project for SMS notifications and complete the configuration.

Note

Avoid repeated 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.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
Object
OBJECT PROPERTIES
- locale_country : String
  The ISO 3166 two-character country code. The value for this field becomes a tag in the ua_locale_country tag group.
- locale_language : String
  The ISO 639-1 two-character language code. The value for this field becomes a tag in the ua_locale_language tag group.
- msisdn : StringRequired
  The mobile phone number you want to register as an SMS channel (or send a request to opt-in). Must be numeric characters only, without leading zeros. 15 digits maximum.
  Pattern: ^[0-9]*$
  Max length: 15
- opted_in : String
  The UTC datetime in ISO 8601 format that represents the date and time when explicit permission was received from the user to receive messages.
  Format: date-time
- sender : StringRequired
  A long or short code the app is configured to send from. When using a short code, prepend the country code to the short code with a colon — US:12345. Failing to provide the country code will only cause an error if your app contains multiple short code senders for different countries.
  Max length: 100
  Min length: 1
- timezone : String
  The IANA identifier for a timezone, e.g. “America/Los_Angeles”. The value in this field becomes a tag in the timezone tag group.

Responses

200

A channel with this msisdn/sender combination already exists.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
One of
- New channel with opt-in : Object
  The request included a valid opted_in value. Airship creates a channel that is opted in to your audience.
  OBJECT PROPERTIES
  - channel_id : String
    Unique Channel ID for the SMS channel.
    Format: uuid
  - ok : Boolean
    If true, Airship creates a channel value with opt_in set to true.
  - operation_id : String
    A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
    Format: uuid
- New channel without opt-in : Object
  Response to a request that does not include an opted_in value. Airship creates a channel with opt_in set to false and sends the user a message prompting them to opt in.
  OBJECT PROPERTIES
  - channel_id : StringRequired
    Unique Channel ID for the SMS channel. This channel is created with opt_in set to false, as the user has not yet opted in to your audience.
    Format: uuid
  - ok : BooleanRequired
    If true, Airship creates a channel with opt_in set to false and Airship sends a message prompting the user to opt in to your audience.
  - operation_id : StringRequired
    A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
    Format: uuid
  - push_id : StringRequired
    Identifies the message prompting the user to opt in to your audience, sent as a result of a request without an opted_in value.
    Format: uuid
  - status : StringRequired
    The channel has been created but has not yet opted-in.
    Possible values: pending

201

The channel was created. If the request did not contain an opted_in value, the channel is created with a pending status and the channel’s opt_in value is set to false; you can assign assign tags and organize pending channels before the user has finished the opt-in process, but you cannot send messages to channels until they complete the opt-in flow.

RESPONSE HEADERS

location : String
URI of the channel, used for later registrations.
Format: url

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
One of
- New channel with opt-in : Object
  The request included a valid opted_in value. Airship creates a channel that is opted in to your audience.
  OBJECT PROPERTIES
  - channel_id : String
    Unique Channel ID for the SMS channel.
    Format: uuid
  - ok : Boolean
    If true, Airship creates a channel value with opt_in set to true.
  - operation_id : String
    A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
    Format: uuid
- New channel without opt-in : Object
  Response to a request that does not include an opted_in value. Airship creates a channel with opt_in set to false and sends the user a message prompting them to opt in.
  OBJECT PROPERTIES
  - channel_id : StringRequired
    Unique Channel ID for the SMS channel. This channel is created with opt_in set to false, as the user has not yet opted in to your audience.
    Format: uuid
  - ok : BooleanRequired
    If true, Airship creates a channel with opt_in set to false and Airship sends a message prompting the user to opt in to your audience.
  - operation_id : StringRequired
    A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
    Format: uuid
  - push_id : StringRequired
    Identifies the message prompting the user to opt in to your audience, sent as a result of a request without an opted_in value.
    Format: uuid
  - status : StringRequired
    The channel has been created but has not yet opted-in.
    Possible values: pending

400

The channel could not be created. This error occurs when the project is not configured with a valid sender, or the request was missing required fields.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- errors : String
  Returned with 40x responses; explains reason for the unsuccessful request.
- ok : Boolean
  If false, the request was unsuccessful.

Opt-out of SMS messages

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": "US: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 again with a valid opted_in value.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
Object
OBJECT PROPERTIES
- msisdn : StringRequired
  The mobile phone number you want to opt-out of SMS messages. Must be numeric characters only, without leading zeros. 15 digits maximum.
  Pattern: ^[0-9]*$
  Max length: 15
- sender : StringRequired
  A long or short code the app is configured to send from. When using a short code, prepend the country code to the short code with a colon — US:12345. Failing to provide the country code will only cause an error if your app contains multiple short code senders for different countries.
  Max length: 100
  Min length: 1

Responses

202

The msisdn/channel is opted-out of SMS notifications.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, the operation completed successfully.

400

The request body is not valid.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- details : Object
  OBJECT PROPERTIES
  error : String
  Specific error message that explains why the request was unsuccessful.
- error : String
  Returned with 40x responses; explains why the request was unsuccessful.
- error_code : Integer
  The 5-digit Airship error code, pointing to a more specific error than the HTTP Status.
- ok : Boolean
  If false, the request was unsuccessful.

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": "US: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

Removes phone numbers and accompanying data from 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, Performance Analytics reports, or other information from the uninstalled SMS channel.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
Object
OBJECT PROPERTIES
- msisdn : StringRequired
  The mobile phone number you want to remove from the Airship system. Must be numeric characters only, without leading zeros. 15 digits maximum.
  Pattern: ^[0-9]*$
  Max length: 15
- sender : StringRequired
  A long or short code the app is configured to send from. When using a short code, prepend the country code to the short code with a colon — US:12345. Failing to provide the country code will only cause an error if your app contains multiple short code senders for different countries.
  Max length: 100
  Min length: 1

Responses

202

The SMS channel and all information associated with the msisdn is uninstalled.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, the operation was successful.

400

The request body is not valid.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- details : Object
  OBJECT PROPERTIES
  error : String
  Specific error message that explains why the request was unsuccessful.
- error : String
  Returned with 40x responses; explains why the request was unsuccessful.
- error_code : Integer
  The 5-digit Airship error code, pointing to a more specific error than the HTTP Status.
- ok : Boolean
  If false, the request was unsuccessful.

Update SMS Channel

Example Request

PUT /api/channels/sms/{channel_id} HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
  "msisdn": "15035556789",
  "sender": "US:12345",
  "opted_in": "2018-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
}

PUT /api/channels/sms/{channel_id}

Update an existing SMS channel to reflect opt-in date, timezone and/or locale changes. The msisdn and sender in the request must match the existing channel or the request will 404.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

channel_id : String Required
The identifier for the SMS channel you want to update.

Request Body

Content-Type: application/json
Object
OBJECT PROPERTIES
- locale_country : String
  The ISO 3166 two-character country code. The value for this field becomes a tag in the ua_locale_country tag group.
- locale_language : String
  The ISO 639-1 two-character language code. The value for this field becomes a tag in the ua_locale_language tag group.
- msisdn : StringRequired
  The phone number corresponding to the channel_id in the request. You cannot change this value for the existing channel.
  Pattern: ^[0-9]*$
  Max length: 15
- opted_in : String
  The UTC datetime in ISO 8601 format that represents the date and time when explicit permission was received from the user to receive messages.
  Format: date-time
- sender : StringRequired
  The sender corresponding to the channel_id in the request. You cannot change this value for an existing channel.
- timezone : String
  The IANA identifier for a timezone, e.g. “America/Los_Angeles”. The value in this field becomes a tag in the timezone tag group.

Responses

200

A channel with this msisdn/sender combination already exists.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  True if the request was successful.
- operation_id : String
  A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
  Format: uuid

400

The request to update the channel failed. This error occurs when the msisdn or sender don’t match the channel_id in the request.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- errors : String
  Returned with 40x responses; explains reason for the unsuccessful request.
- ok : Boolean
  If false, the request was unsuccessful.

404

Occurs when the msisdn and/or sender don’t match any existing channel_id.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- errors : String
  A plain-text explanation of the error.
- ok : Boolean
  If false, your request was unsuccessful.

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
Data-Attribute: channel
Content-Type: application/vnd.urbanairship+json; version=3;

{
   "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": [
            "US: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}

Lookup an SMS channel by msisdn and sender.

path PARAMETERS

msisdn : Integer Required
The mobile phone number you want to lookup a channel for. 15 digits maximum; may not contain leading zeroes.
Pattern: ^[0-9]*$
Max length: 15
sender : Integer Required
A long or short code the app is configured to send from. If your app uses the same shortcode for audiences in different countries, prepend the country code to the short code with a colon — US:12345.

Responses

200

Returns an SMS channel object. An SMS channel object includes tag groups for ua_channel_type, ua_sender_id, and ua_opt_in.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- channel : Channel Object
  Describes a channel.
- ok : Boolean
  Success.

404

A channel_id does not exist for the msisdn and sender.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- error : String
  Returned with 40x responses; explains why the request was unsuccessful.
- error_code : Integer
  The 5-digit Airship error code, pointing to a more specific error than the HTTP Status.
- ok : Boolean
  If false, the request was unsuccessful.

Custom SMS Response

Example SMS Request

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

{
  "sms" : {
      "alert": "Your balance is $1234.56. Go to https://www.mybank.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.",
      "shorten_links": true
  },
  "mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}

Example MMS Request

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

{
  "mms" : {
    "fallback_text": "See fun cat pics at https://example.com/cat/pics/12345678",
    "slides": [
      {
        "media": {
          "url": "https://example.com/cat/pics/12345678.gif",
          "content_type": "image/gif",
          "content_length": 23098
        }
      }
    ],
    "shorten_links": true
  },
  "mobile_originated_id" : "3e1e4fb3-2d3c-431e-96bf-9b235a12f84b"
}

Example Response

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

{
      "ok": true,
      "operation_id": "f3d0993e-e3e1-4aae-b1c0-864a715bfaff",
      "push_id": "7502abe6-e6ea-4f2b-906f-ebbab612c69e"
}

POST /api/sms/custom-response

Respond to a mobile originated message based on a keyword consumed by your custom-response webhook, using a mobile-originated ID. See Inbound Message Handling for information about setting up a custom response webhook server.

This endpoint requires bearer authorization.

Security:
HTTP bearer auth

Request Body

Content-Type: application/json
One of
- Object
  OBJECT PROPERTIES
  - mobile_originated_id : StringRequired
    The identifier that you received through your SMS webhook corresponding to the mobile-originated message that you’re issuing a custom response to. The mobile_originated_id is valid for 10 minutes from the received_timestamp in the payload sent to your webhook server’s /inbound-sms endpoint.
    Format: uuid
  - sms : ObjectRequired
    OBJECT PROPERTIES
    alert : StringRequired
    Your custom SMS message.
    shorten_links : Boolean
    If true, Airship will shorten http/https links (space delimited) in the message text fields, producing unique, 25 character URLs for each member of your audience. Airship produces short_link_click events in the Real-Time Data Stream for each link that a user engages with.
    When this setting is enabled, you can add or remove tags from users who click your links by adding query strings to your URLs. You can serialize tag operations with &:
    ?ua-tag-add=tag_group:tag&another_group:tag2 — adds a tag in tag_group to the channel_id.
    ?ua-tag-remove=tag_group:tag&another_group:tag2 — removes a tag in tag group from the channel_id.
- Object
  OBJECT PROPERTIES
  - mms : MMS Platform OverridesRequired
    Provides the content for a push to MMS channels. If sms is in the device_type array, your request may include this object. It cannot be combined with an SMS Platform Override as a single push can only include either an SMS or MMS payload.
  - mobile_originated_id : StringRequired
    The identifier that you received through your SMS webhook corresponding to the mobile-originated message that you’re issuing a custom response to. The mobile_originated_id is valid for 10 minutes from the received_timestamp in the payload sent to your webhook server’s /inbound-sms endpoint.
    Format: uuid

Responses

200

The operation was successful.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, your request was successful.
- operation_id : String
  A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
  Format: uuid
- push_id : String
  A unique identifier for a push operation.
  Format: uuid

404

The mobile_originated_id could not be found.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- error : String
  A plain-text explanation of the error.
- ok : Boolean
  If false, your request was unsuccessful.
- operation_id : String
  A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
  Format: uuid

Manually Trigger a Keyword Interaction

Example Request

POST /api/sms/15035556789/keywords HTTP/1.1
User-Agent: Apache-HttpAsyncClient/4.0.1 (java 1.5)
Content-Type: application/json
Authorization: Basic <user:pass>
Connection: close

{
  "keyword" : "stop",
  "sender_ids" : [ "US:54321", "1234"]
}

Example Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true
}

Example Failure Response

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

{
  "ok" : false,
  "error" : "The following sender(s) are not configured for the 'stop' keyword: ['US:1234']",
  "error_code" : 400
}

POST /api/sms/{msisdn}/keywords

Trigger Mobile Originated (MO) keyword interactions on behalf of an MSISDN.

Security:
HTTP bearer auth
HTTP basic auth

path PARAMETERS

msisdn : String Required
The identifier for the SMS channel you want to trigger a mobile originated keyword from.

Request Body

Content-Type: application/json
Object
OBJECT PROPERTIES
- keyword : StringRequired
  The keyword you want to trigger an action for.
- sender_ids : Array [String]Required
  The sender IDs with keyword actions that you want to test. Airship returns a 400 if the keyword is not configured for one or more of the senders in the array.
  Min items: 1
- timestamp : String
  The ISO8601 date-time when the MO keyword was sent. If absent, Airship uses the server-time of your request.
  Format: date-time

Responses

200

The operation was successful.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, your request was successful.

400

The operation was not successful. If the request is formatted correctly, one or more sender_ids does not exist or the keyword is not configured for one or more of the sender_ids.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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.

Named User Listing or 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 with id query (named user lookup)

{
  "ok": true,
  "named_user": {
      "named_user_id": "user-id-1234",
      "tags": {
        "my_fav_tag_group": [
            "tag1",
            "tag2"
        ]
      },
      "attributes": {
        "item_purchased": "Fur removal tool",
        "cats_name": "Sammy",
        "pets_age": 12
      },
      "user_attributes": {
        "ua_country": "US",
        "ua_language": "en",
        "ua_tz": "America/Los_Angeles"
      },
      "channels": [
        {
            "channel_id": "dceafd02-b852-4305-83df-98b65fa40dd4",
            "device_type": "ios",
            "installed": true,
            "opt_in": true,
            "push_address": "FFFF",
            "created": "2019-08-08T20:41:06",
            "last_registration": "2020-05-01T18:00:27",
            "tags": [
              "meow"
            ]
        }
      ]
  }
}

Example Response without id query (list named users)

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

{
   "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

Return a list of named users or lookup a single named user by named_user_id.

Security:
HTTP basic auth
HTTP bearer auth

query PARAMETERS

id : String
The named_user_id you want to look up. When querying a named_user_id, the response contains a single named_user object. If you do not query a specific named_user_id, the response returns an array of named_users, in which each object represents an individual named user.

Responses

200

Returns OK for success.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
One of
- Named User Lookup Response Object : Object
  Response for a single named_user_id query.
  OBJECT PROPERTIES
  - named_user : Named User Object
    The response body for a named user listing, including tags, channels and attributes associated with the named user.
  - ok : Boolean
    Success.
- Named User Listing Response Body : Object
  Response returned when performing this operation without a query.
  OBJECT PROPERTIES
  - named_users : Array [Named User Object]
  - 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 page of results.
    Format: url
  - ok : Boolean
    Success.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users Association

Example Request - associate an iOS channel with a 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 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 request — associate an email 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

{
   "email_address": "monopoly.man@boardwalk.com",
   "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 or email address with a named user (named_user_id). If the named_user_id does not already exist, this operation will create it. If the channel_id or email address is already associated with the named_user_id, this operation will do nothing.

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.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Named user association requires a channel_id or email_address. Do not provide both in the same request.

Content-Type: application/json
One of
- Associate channel_id with named user : Object
  OBJECT PROPERTIES
  - channel_id : StringRequired
    The channel ID you want to associate with a named user.
    Format: uuid
  - device_type : String
    The device type of the channel, e.g., ios, android, amazon. Do not specify device_type for web, email, sms, or open channels.
    Possible values: ios, android, amazon
  - named_user_id : StringRequired
    A string value identifying the new user with no leading or trailing whitespace. If the named_user_id does not already exist, this operation will create a new named user and associate the channel_id with it.
    Pattern: ^[^\s].{1,125}\S$
    Max length: 128
    Min length: 1
- Associate email with named user : Object
  OBJECT PROPERTIES
  - email_address : StringRequired
    The email address you want to associate with a named user.
    Format: email
  - named_user_id : StringRequired
    A string value identifying the new user with no leading or trailing whitespace. If the named_user_id does not already exist, this operation will create a new named user and associate the channel_id with it.
    Pattern: ^[^\s].{1,125}\S$
    Max length: 128
    Min length: 1

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users 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 request — disassociate an email channel from named user

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

{
   "email_address": "monopoly.man@gotojail.com",
   "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 or an email address from a named_user_id.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
Object
OBJECT PROPERTIES
- channel_id : String
  The channel or email address you want to disassociate from the named_user_id. The schema should include one of email_address or channel_id, but not both.
  Format: uuid
- email_address : String
  The email address you want to disassociate from the named_user_id.
  Format: email
- named_user_id : String
  The named user that you want to remove the channel from.
  Pattern: ^[^\s].{1,125}\S$
  Max length: 128
  Min length: 1

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users Tags

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

Add, remove, or set tags on a named user. A single request body may contain add and/or remove objects, or a single set field. At least one of the add, remove, or set objects must be present in a request.

Important

A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response.

While we support billions of named users, testing a named user by repeatedly updating its tags can cause latency and service interruptions.

We support up to 1000 tags per named user. Adding more than 1000 tags per named user can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per named user, and they will help you find an alternative.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
Object
OBJECT PROPERTIES
- add : Tag Group Object
  Add the list of tags to the named user(s), but do not remove any. If the tags are already present, they are not modified.
- audience : ObjectRequired
  The named user(s) you want to associate/disassociate tags with.
  OBJECT PROPERTIES
  named_user_id : Array [String]
  Max items: 1000
  Min items: 1
- remove : Tag Group Object
  Remove the list of tags from the named user(s), but do not remove any others. If the tags are not currently present, nothing happens.
- set : Tag Group Object
  Set these tags for the audience; any tags previously associated with the audience tags that are not in this current list are removed.

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Named Users Uninstall

Example Request - deletes all users and their associated channels

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

{
   "named_user_id": ["user-id-1234","user-id-5678"]
}

Example Response

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

{
   "ok": true
}

POST /api/named_users/uninstall

Disassociate and delete all channels associated with the named_user_id(s) and also delete the named_user_id(s). This call removes all channels associated with a named user from Airship systems in compliance with data privacy laws.

Uninstalling channels also removes accompanying analytic data (including Performance Analytics) from the system.

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

Note

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

Security:
HTTP basic auth

Request Body

Content-Type: application/json
Object
OBJECT PROPERTIES
- named_user_id : Array [String]Required
  Array of strings representing the named_userid(s) you wish to be uninstalled. Must have between 1 to 100 items in the array with a 128 character/byte maximum per item.
  Max items: 100
  Min items: 1

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Set or Remove Attributes on Named Users

Example Request

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

{
    "attributes": [
        {
            "action": "set",
            "key": "firstName",
            "value": "Gyuri",
            "timestamp": "2019-09-19 12:00:00"
        },
        {
            "action": "remove",
            "key": "birthDate",
            "timestamp": "2019-09-19 12:00:00"
        },
        {
            "action": "set",
            "key": "lastName",
            "value": "Pataki",
            "timestamp": "2019-09-19 12:00:00"
        }
    ]
}

Example Response

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

{
   "ok": true
}

POST /api/named_users/{named_user_id}/attributes

Add, remove, or set attributes on a named user.

A single request body may contain a set or remove field, or both, or a single set field. If both set and remove fields are present and the intersection of the attributes in these fields is not empty, then a 400 will be returned.

If an attribute request is partially valid, i.e. at least one attribute exists, Airship returns a 200 with a warning in containing a CSV list of attributes that failed to update.

Note

Airship returns a 200 if you attempt to set attributes on a named user that does not exist.

Tip

If you wish to set attributes on multiple named users at once, we recommend using /api/channels/attributes which supports an audience object in the request body.

path PARAMETERS

named_user_id : String Required
The named user you are setting the attributes for.

Request Body

Content-Type: application/json
Array [Attributes Object]
Include an array of attributes objects in your request.

Responses

200

Success. If an attribute request is partially valid, i.e. at least one attribute exists, Airship returns a 200 with a warning in containing a CSV list of attributes that failed to update. Airship returns a 200 if you attempt to set attributes on a named_user, even if the named_user does not exist.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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 segments for the application.

Security:
HTTP basic auth
HTTP bearer auth

Responses

200

Returned on success a JSON object containing segments.

RESPONSE HEADERS

Link : String
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.
Format: uri

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- 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.
- segments : Array [Object]Required
  An array of segments for the application.
  ARRAY ITEM
  - Object
    OBJECT PROPERTIES
    creation_date : IntegerRequired
    The original creation date of segment in epoch milliseconds.
    display_name : StringRequired
    The segment display name.
    id : StringRequired
    A unique identifier for the segment.
    Format: uuid
    modification_date : IntegerRequired
    Latest modification date of the segment in epoch milliseconds.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create 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
Location: https://go.urbanairship.com/api/segments/f35da41d-59c1-4106-a192-9594bd480cb6
Content-Type: application/vnd.urbanairship+json;version=3

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

POST /api/segments

Create a new segment.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

A single segment object.

Content-Type: application/json
Segment object : Object
A set of audience selection criteria that you can reuse as a segment.
OBJECT PROPERTIES
- criteria : AnyRequired
  Defines the set of devices to send notifications to. criteria is a JSON expression containing the same information as the audience selector with the limitation that the only atomic selectors supported are tag, location, and static_list. See Audience Selection for more information.
  One of
  - Compound Selector
    Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.
  - Atomic Selector
    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.
- display_name : StringRequired
  Human readable name for this segment. This will be used in the dashboard.

Responses

201

The segment was created.

RESPONSE HEADERS

Location : String
The newly created segment.
Format: uri

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- ok : Boolean
  If true, the operation completed successfully and returns expected results.
- operation_id : String
  A unique string identifying an API call, and can be used to identify operations in reporting and troubleshooting logs.
  Format: uuid
- segment_id : String
  The ID of the newly created segment.
  Format: uuid

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Segment Lookup

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; charset=utf-8

{
   "criteria": {
      "and": [
         {
            "tag": "ipad"
         },
         {
            "not": {
               "tag": "foo"
            }
         }
      ]
   },
   "display_name": "A segment"
}

GET /api/segments/{segment_id}

Lookup a segment.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

segment_id : String Required
The segment you want to retrieve.

Responses

200

Returns OK for success.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
A set of audience selection criteria that you can reuse as a segment.
OBJECT PROPERTIES
- criteria : AnyRequired
  Defines the set of devices to send notifications to. criteria is a JSON expression containing the same information as the audience selector with the limitation that the only atomic selectors supported are tag, location, and static_list. See Audience Selection for more information.
  One of
  - Compound Selector
    Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.
  - Atomic Selector
    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.
- display_name : StringRequired
  Human readable name for this segment. This will be used in the dashboard.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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

{
   "ok": true,
   "operation_id": "1f93ca85-b8fd-4833-8d1a-6e2b7f4ceea9"
}

PUT /api/segments/{segment_id}

Change the definition of the segment.

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.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

segment_id : String Required
The segment you want to retrieve.

Request Body

A single segment object.

Content-Type: application/json
Segment object : Object
A set of audience selection criteria that you can reuse as a segment.
OBJECT PROPERTIES
- criteria : AnyRequired
  Defines the set of devices to send notifications to. criteria is a JSON expression containing the same information as the audience selector with the limitation that the only atomic selectors supported are tag, location, and static_list. See Audience Selection for more information.
  One of
  - Compound Selector
    Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.
  - Atomic Selector
    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.
- display_name : StringRequired
  Human readable name for this segment. This will be used in the dashboard.

Responses

200

Returned if the segment has been succesfully updated.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

segment_id : String Required
The segment you want to retrieve.

Responses

204

The delete operation was successful.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Segment Locations

You can configure segments based on user location and location history. The following endpoints return location information to help you determine the locations and time frames for location-based segments.

Important

Location history targeting capabilities are being discontinued and will not be available after January 31, 2021. Please contact Airship Support with any questions.

Location Lookup

Example Request for Location by Name

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

Search for a location boundary by name and type. See Boundary Types and Aliases Catalog for a list of available types. 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 searching for Locations by coordinates or bounding box.

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.

Security:
HTTP basic auth
HTTP bearer auth

query PARAMETERS

q : String
The name of the boundary you want to search for. Use in conjunction with the type query.
type : String
The type of boundary you want to search for. Use in conjunction with the q query string.

Responses

200

Success

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- features : Array [Location Object]
  Contains an array of location results.

Find Location by Alias

Example Request for Location by Alias

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;

Example Response for Location by Alias with 1 Result

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

Find locations using any of the keys appearing in the alias object. See the Boundary Types and Aliases Catalog for a list of supported aliases.

Security:
HTTP basic auth
HTTP bearer auth

query PARAMETERS

from-alias : Object
Search using any of the keys supported by the aliases object.

Responses

200

Success

RESPONSE BODY

Content-Type: application/json
One of
- Multiple Location Objects : Object
  If your query returns multiple results, they are contained in the features array.
  OBJECT PROPERTIES
  - features : Array [Location Object]
- Location Object
  If your query returns a single result, the features array is absent.

Location by Coordinates

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_1},{longitude_1}

Find a location using coordinates. Airship will search for a location containing the coordinates you provide.

Security:
HTTP basic auth
HTTP bearer auth

query PARAMETERS

type : String
The type of location you want to return.

path PARAMETERS

latitude_1 : Number Required
Latitude to search for.
longitude_1 : Number Required
Longitude to search for.

Responses

200

Success

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- features : Array [Location Object]

Location by Coordinates or bounding box

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}

Find locations within a bounding box. Provide two sets of coordinates representing opposing corners of a rectangular search area, and this endpoint will return locations that are at least partially contained within the bounding box. Use the type query to find specific types of locations within the bounding box.

Security:
HTTP basic auth
HTTP bearer auth

query PARAMETERS

type : String Required
The type of location you want to search for inside the boundary

path PARAMETERS

latitude_1 : Number Required
Latitude to search for the first corner of the bounding box.
longitude_1 : Number Required
Longitude for the first corner of the bounding box.
latitude_2 : Number Required
Latitude for the opposing corner of the bounding box.
longitude_2 : Number Required
Longitude for the oposing corner of the bounding box.

Responses

200

Success

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- features : Array [Location Object]

Location 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

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/{polygon_id}

Lookup a polygonal location by ID. The response including the coordinates defining the geometric shape of the location in the geometry object.

Security:
HTTP basic auth
HTTP bearer auth

query PARAMETERS

zoom : Integer
Determines the level of detail of the coordinates returned. The higher the zoom, the more detailed the polygon in the response (reflected by more coordinates defining the shape of the polygon in the geometry object).
Max: 20
Min: 1

path PARAMETERS

polygon_id : String Required
The ID of the polygon you want to return.

Responses

200

Success

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- bounds : Array [Number]
  The latitudinal and longitudinal coordinate values representing the boundaries of the search or location.
- centroid : Array [Number]
  The latitude and longitude representing the center point of the location.
- geometry : Object
  Contains the coordinates defining the geometric shape of a location.
  OBJECT PROPERTIES
  coordinates : Array [Array [Array [Array [Number]]]]
  Contains the coordinates for all the points in the geometric shape using arrays of arrays to represent the sides of the shape. Arrays containing coordinates contain latitudinal, lognitudinal pairs.
  ARRAY ITEM
  Array [Array [Array [Number]]]
  ARRAY ITEM
  Array [Array [Number]]
  ARRAY ITEM
  Array [Number]
  ARRAY ITEM
  Number
  type : String
  Geometric type, typically MultiPolygon.
  Possible values: MultiPolygon
- id : String
  A unique identifier for the location.
- properties : Object
  OBJECT PROPERTIES
  abbr : String
  An abbreviation for the location, if applicable.
  aliases : Object
  Aliases for the location name.
  boundary_type : String
  The type of geographical location – city, province, etc.
  boundary_type_string : String
  A normalized type of geographical location – State/Province, etc.
  context : Object
  Contains key-value pairs to help identify the location, frequently including parents of the location. For example, if the location is a city in the US, context might list us_state and other keys.
  OBJECT PROPERTIES
  name : String
  The common name for the location, if applicable.
  source : String
  The source defining the location.
- type : String
  The location type. May be “Feature” as in the coordinates are drawn outside the service, or MultiPolygon, representing a location drawn by a user through the Airship Segments Builder.

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": "2018-08-07 18"
    },
    {
        "unit": "days",
        "cutoff": "2018-06-10"
    },
    {
        "unit": "weeks",
        "cutoff": "2018-W22"
    },
    {
        "unit": "months",
        "cutoff": "2014-08"
    },
    {
        "unit": "years",
        "cutoff": "2008"
    }
]

GET /api/segments/dates

Retrieve cutoff dates for each time granularity. When creating segments, you can identify location events that happened in the past with maximum values changing based on the unit of time. For example, you can search back up to 10 years using yearly granularity, but only up to 4 years using monthly granularity. This endpoint lists the cutoff dates and times (where applicable) for different units of time. You can create location segments using the following units of time, going back:

48 hours ago * 60 days ago * 10 weeks ago * 48 months ago * 10 years ago

Security:
HTTP basic auth
HTTP bearer auth

Responses

200

Success

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
ARRAY ITEM
- Object
  OBJECT PROPERTIES
  - cutoff : String
    The farthest date/time in the past you can use when creating segments based on location using the specified granularity. Hours are represented from 0-23, weeks as w0 - w51.
  - unit : String
    Possible values: hours, days, weeks, months, years

Attribute Lists

Define and manage attribute lists; upload corresponding attribute data in CSV format.

Retrieve Lists

Example Request

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

Example Response

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

{
  "ok": true,
  "lists": [
      {
        "name": "ua_attributes_my_list",
        "description": "My first list",
        "extra": {
            "filename": "list.csv",
            "source": "crm"
        },
        "created": "2020-05-13T21:41:25",
        "last_updated": "2020-05-13T21:45:17",
        "channel_count": 0,
        "error_path": "https://go.urbanairship.com/api/attribute-lists/ua_attributes_my_list/errors",
        "status": "ready"
      },
      {
        "name": "ua_attributes_another_list",
        "description": "My second list",
        "extra": {
            "filename": "list2.csv",
            "source": "api"
        },
        "created": "2020-05-14T21:41:25",
        "last_updated": "2020-05-14T21:45:17",
        "channel_count": 0,
        "error_path": "https://go.urbanairship.com/api/attribute-lists/ua_attributes_another_list/errors",
        "status": "ready"
      }
  ]
}

GET /api/attribute-lists

Retrieve information about all attributes lists. This call returns a list of metadata that will not contain the actual lists of users.

Security:
HTTP basic auth
HTTP bearer auth

Responses

200

Lists metadata retrieved successfully.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- lists : Array [List Response Object]
  An array of List Objects.
- ok : Boolean
  Success.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create Attributes List

Example Request

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

{
  "name": "ua_attributes_my_new_list",
  "description": "First of many attributes lists!",
  "extra": {
      "filename": "attributes.csv",
      "source": "CRM"
  }
}

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://go.urbanairship.com/api/attribute-lists/ua_attributes_foobar

{
  "ok" : true
}

POST /api/attribute-lists

Create a new attributes list by defining it in the Airship system. The body of the request contains the name, description, and optional metadata for the list. After you define a list, you populate it with a call to the Upload Attribute List endpoint.

Important

You must prefix attribute list names with “ua_attributes_”.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
List Metadata Object
Contains all user-specified data when defining a static list or attributes list in Airship.

Responses

201

Returns OK for success.

RESPONSE HEADERS

Location : String
The URI of the list, used for later updates.
Format: uri

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the API may not be used to create or modify lists with “ua_” prefixed name.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

409

The 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).

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Upload Attribute List

Example Request

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

channel_id,Magic Score,Preferred Sport
c543f3a3-bc1d-4830-8dee-7532c6a23b9a,100,Basketball
6ba360a0-1f73-4ee7-861e-95f6c1ed6410,,Basketball
15410d17-687c-46fa-bbd9-f255741a1523,2,Football
c2c64ef7-8f5c-470e-915f-f5e3da04e1df,22.1,Rugby

Example Response

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

{
  "ok" : true
}

Attribute List CSV upload for SMS

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

msisdn,sms_sender,firstName
5035556789,18588675309,Jane
4155551212,18588675309,Rory

Example Response

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

{
  "ok" : true
}

PUT /api/attribute-lists/{list_name}/csv

Upload a CSV that will set attribute values on the specified channels or named users.

The first entry in the uploaded CSV must be a header row. The first field must be one of the following identifier types: channel_id, msisdn, named_user, email_address.

Only one identifier type is allowed per file unless the identifier type name matches a custom attribute schema for the associated app key.

You must include both msisdn and sms_sender columns when targeting SMS or MMS channel types. See example to the right.

Target Type	Required Column Headers
Web	channel_id
Open Channel	channel_id
iOS	channel_id
Android	channel_id
Named User	named_user
Email	email_address
SMS	- msisdn (numeric and no leading 0) - sms_sender (numeric or prefixed with country code and colon-separated, e.g. “US:1234”)
MMS	- msisdn (numeric and no leading 0) - sms_sender (numeric or prefixed with country code and colon-separated, e.g. “US:1234”)

Note

The maximum number of rows that may be uploaded to a list is 10 million, and the maximum number of columns is 101 (1 identifer column and 100 attribute or internal header columns) Content-Encoding: gzip is supported (and recommended) on this endpoint to reduce network traffic.

Warning

If your upload 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.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

list_name : String Required
The name of the list you want to retrieve or update.

Request Body

Content-Type: text/csv
String
Format: binary

Responses

202

The request has been accepted for processing.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

Bad Request. Parsing or validating the request failed.

error_code	Description
40002:	CSV contains too many identifiers.
40003:	CSV header contains too many columns.
40013:	CSV header’s first field must be an identifier.
40014:	CSV header contains an unknown attribute name.
40015:	CSV header contains duplicate attribute names.
40017:	CSV header contains duplicate column names.
40018:	CSV header does not contain required column for identifier type.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

The API may only be used to create or modify lists with “ua_attributes_” prefixed name.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Download list errors

Example Request

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

Example Response

HTTP/1.1 200 OK
Content-Type: text/csv

8b4de669-16f1-4e71-9a1f-0c62a8235a65,ERROR,"Unable to parse number: forty-two"
d5ebe607-a3e6-4601-b97e-83ec604223fe,ERROR,"Unable to parse date: monday"

GET /api/attribute-lists/{list_name}/errors

During processing, after a list is uploaded, errors can occur. Depending on the type of list processing, an error file may be created, showing a user exactly what went wrong.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

list_name : String Required
The name of the list.

Responses

200

Returns OK for success.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Contains all user-specified data about a static list or attributes list (metadata), but does not contain CSV list contents. Use the /api/lists/{name}/csv endpoints to upload or download list contents.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

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

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
Data-Attribute: lists
Content-Type: application/vnd.urbanairship+json; version=3;

{
   "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

Retrieve information about all static lists. This call returns a list of metadata that will not contain the actual lists of users.

Security:
HTTP basic auth
HTTP bearer auth

Responses

200

Lists metadata retrieved successfully.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- lists : Array [List Response Object]
  An array of List Objects.
- ok : Boolean
  Success.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create 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
Location: https://go.urbanairship.com/api/lists/platinum_members
Content-Type: application/vnd.urbanairship+json; version=3;

{
   "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.

Note

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

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
List Response Object
Contains all user-specified data about a static list or attributes list (metadata), but does not contain CSV list contents. Use the /api/lists/{name}/csv endpoints to upload or download list contents.

Responses

201

Returns OK for success.

RESPONSE HEADERS

Location : String
The URI of the list, used for later updates.
Format: uri

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the API may not be used to create or modify lists with “ua_” prefixed name.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

409

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Get a 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
Data-Attribute: static_list
Link: <https://go.urbanairship.com/api/platinum_members/list/?start=uuid101&limit=100>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3;

{
   "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/{list_name}

Retrieve information about one static list, specified in the URL. 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.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

list_name : String Required
The name of the list.

Responses

200

Returns OK for success.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Contains all user-specified data about a static list or attributes list (metadata), but does not contain CSV list contents. Use the /api/lists/{name}/csv endpoints to upload or download list contents.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update list metadata

Example Request

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/{list_name}

Update the metadata (description, extras, etc.) of a static list.

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.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

list_name : String Required
The name of the list.

Request Body

The body of the request will contain a list metadata object, though you can omit the name attribute. If present, it must match the name provided in the URL. You cannot change the name of a list; it is the primary identifier for the list.

Content-Type: application/json
List Metadata Object
Contains all user-specified data when defining a static list or attributes list in Airship.

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

Bad Request. Parsing or validating the request failed. error_code 40001: Attempted list rename. List renaming is not allowed.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the API may not be used to create or modify lists with “ua_” prefixed name.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete 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/{list_name}

Delete a list. 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.

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.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

list_name : String Required
The name of the list.

Responses

204

An API request was successful, but there is no response body to return.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

You cannot delete or modify lists with a “ua_” prefixed name.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Download a list of channels

Example Request

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

Example Response

HTTP/1.1 200 OK
Content-Type: text/csv

ios_channel,6d56ab7e-2c78-4ba9-ab11-d9b664ca2b32
ios_channel,d5ebe607-a3e6-4601-b97e-83ec604223fe
ios_channel,fa599af7-43e4-4862-a570-1470bf6f53ff
android_channel,0e91d0f2-c65d-4b40-b968-b9f8e8b0c987
android_channel,c346a3ce-5754-4d02-8ee5-500ce470a0b7
android_channel,e9a01369-5f74-4167-b660-df84014a2e57
amazon_channel,0356d138-d1d9-4572-b321-e1b67f4cd658
amazon_channel,24dc9a76-45fe-4b17-8ed7-841f96b658ad
amazon_channel,4d6b59f8-6d8c-4151-8b13-cd58d6ac8c6e

GET /api/lists/{list_name}/csv

Allows you to download the contents of a static list (as opposed to a GET /api/lists/{list_name} which will return metadata about the list). When you upload a list, alias and named_user entries are resolved to channels. Therefore, the CSV output from this endpoint will be in the same format as the uploaded list, but will only contain ios_channel, android_channel and amazon_channel entries.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

list_name : String Required
The name of the list you want to retrieve or update.

Responses

200

Returns a CSV list of channels.

RESPONSE BODY

Content-Type: text/csv

Update list contents

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

named_user,customer-42
named_user,room-27
ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634
web_channel,d132f5b7-abcf-4920-aeb3-9132ddac3d5a
android_channel,52b2b587-0152-4134-a8a0-38ae6933c88a

Example Response

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

{
   "ok" : true
}

PUT /api/lists/{list_name}/csv

Replace the contents of an existing static list via CSV file upload. Uploads must be newline delimited identifiers (text/CSV) with commas as the delimiter.

The CSV format is two columns: identifier_type and identifier. The identifier is the associated identifier you wish to send to. The identifier_type must be one of:

named_user
ios_channel
android_channel
amazon_channel
sms_channel
email_channel
open_channel
web_channel

Note

The maximum number of identifier_type,identifier pairs that may be uploaded to a list is 10 million. Content-Encoding: gzip is supported (and recommended) on this endpoint to reduce network traffic.

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.

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

list_name : String Required
The name of the list you want to retrieve or update.

Request Body

Content-Type: text/csv
String
Format: binary

Responses

202

The request has been accepted for processing.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

Bad Request. Parsing or validating the request failed.

error_code	Description
40002:	CSV contains too many identifiers.
40003:	CSV contains an entry with a column count other than 2.
40004:	CSV contains an invalid `identifier_type`.
40005:	CSV contains a channel `identifier` that is not a valid UUID.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the API may not be used to create or modify lists with “ua_” prefixed name.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

404

The requested resource doesn’t exist.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create and Send

Simultaneously send a notification to an audience of SMS, email, or open channel addresses and register channels for new addresses in your audience. Create and send can help you immediately notify new open::, email, or sms contacts without having to wait for channel registration.

Addresses in the audience that are not yet associated with channels are registered as new channels. Addresses in the payload that are already registered to opted-in, or have an opted_in value that is newer than an opted_out value for their channel_id will still receive notifications, but are not registered as new channels.

Note

You cannot update channel information or opt-in status from these endpoints. If you want to update channels, refer to the appropriate email, SMS, or open channel endpoints.

Create and Send

Example Create and Send Using Email

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

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@email.com",
        "ua_commercial_opted_in": "2018-11-29T10:34:22",
      },
      {
        "ua_address" : "ben@icetown.com",
        "ua_commercial_opted_in": "2018-11-29T12:45:10",
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "subject": "Welcome to the Winter Sale! ",
      "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
      "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
      "message_type": "commercial",
      "sender_name": "Airship",
      "sender_address": "team@urbanairship.com",
      "reply_to": "no-reply@urbanairship.com"
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

Example Create and Send with Stored Template

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

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@email.com",
        "ua_commercial_opted_in": "2018-11-29T10:34:22",
        "name": "New Person, Esq.",
        "location": "City, State"
      },
      {
        "ua_address" : "ben@icetown.com",
        "ua_commercial_opted_in": "2018-11-29T12:45:10",
        "name": "Ben Wyatt",
        "location": "Pawnee, IN"
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "message_type": "commercial",
      "sender_name": "Airship",
      "sender_address": "team@urbanairship.com",
      "reply_to": "no-reply@urbanairship.com",
      "bcc": ["blind@copy.com"],
      "template": {
        "template_id": "9335bb2a-2a45-456c-8b53-42af7898236a"
        }
      }
    }
  }
}

Example Response

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

{
    "ok": true,
    "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
    "push_ids": [
        "c0eead17-333b-4f86-8a42-9fb7be1ed627"
    ],
    "message_ids": [],
    "content_urls": []
}

POST /api/create-and-send

Send a notification to an audience of SMS, email, or open channel addresses and simultaneously register new addresses in the audience as new channels. Addresses that are not yet associated with channels are registered as new channels. Addresses in the payload that are already registered to a channel_id and are either opted_in or have an opted_in value in the payload that is newer than the opted_out value associated with a channel will receive the notification, but are not re-registered as new channels. You cannot update opted_in values for existing channels through this endpoint.

Warning

Duplicate addresses in the create-and-send array might receive redundant notifications, or fewer notifications than expected. You should remove duplicate addresses from your request before sending a create-and-send notification.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
One of
- Create and Send to Email Channels
  The payload for a create and send operation to email channels. When registering and sending to email channels, device_types must be set to email.
- Create and Send to SMS Channels
  The payload for a create and send operation to SMS channels. When registering and sending to SMS channels, device_types must be set to sms.
- Create and Send MMS Notification
  The payload for a create and send operation that registers SMS channels and sens a multimedia payload (MMS). When sending an MMS payload, device_types must be set to mms.
- Create and Send to Open Channels
  When registering and sending to open channels, the device_type must be set to open::<open_channel_name>.

Responses

202

Because this operation sends messages, a successful response is nearly identical to a /api/push response.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
A push response contains a list of identifiers for the notifications sent in the request.
OBJECT PROPERTIES
- content_urls : Array [String]
  An array of URLs where the push payload contains a landing page action.
  Max items: 100
  Min items: 1
- localized_ids : Array [String]
  An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).
- message_ids : Array [String]
  An array of message IDs, each uniquely identifying a Message Center message.
- ok : Boolean
  Success.
- operation_id : String
  A unique string identifying the operation, useful for reporting and troubleshooting.
  Format: uuid
- push_ids : Array [String]
  An array of push IDs, each uniquely indentifying a push.
  Max items: 100
  Min items: 1

400

You can only create-and-send to a single platform per request. Attempting to register channels and send notifications for multiple device_types in the same request will cause a 400 response.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate Create and Send Payload

Example Validating Create-and-send Payload

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

{
  "audience": {
    "create_and_send" : [
      {
        "ua_address": "new@email.com",
        "ua_commercial_opted_in": "2018-11-29T10:34:22",
      },
      {
        "ua_address" : "ben@icetown.com",
        "ua_commercial_opted_in": "2018-11-29T12:45:10",
      }
    ]
  },
  "device_types" : [ "email" ],
  "notification" : {
    "email": {
      "subject": "Welcome to the Winter Sale! ",
      "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
      "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
      "message_type": "commercial",
      "sender_name": "Airship",
      "sender_address": "team@urbanairship.com",
      "reply_to": "no-reply@urbanairship.com"
    }
  },
  "campaigns": {
      "categories": ["winter sale", "west coast"]
  }
}

Example Validation Response

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

{
   "ok" : true
}

POST /api/create-and-send/validate

Validate a create-and-send payload. This endpoint will not create channels or send notifications; it only parses and validates your payload.

Security:
HTTP basic auth
HTTP bearer auth

Request Body

Content-Type: application/json
One of
- Create and Send to Email Channels
  The payload for a create and send operation to email channels. When registering and sending to email channels, device_types must be set to email.
- Create and Send to SMS Channels
  The payload for a create and send operation to SMS channels. When registering and sending to SMS channels, device_types must be set to sms.
- Create and Send MMS Notification
  The payload for a create and send operation that registers SMS channels and sens a multimedia payload (MMS). When sending an MMS payload, device_types must be set to mms.
- Create and Send to Open Channels
  When registering and sending to open channels, the device_type must be set to open::<open_channel_name>.

Responses

200

Everything worked as expected.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule a Create and Send Operation

Example Scheduled Create and Send

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

{
  "schedule": {
    "scheduled_time" : "2018-11-11T12:00:00"
  },
  "name" : "scheduled winter sale email",
  "push" : {
    "audience": {
      "create_and_send" : [
        {
          "ua_address": "new@email.com",
          "ua_commercial_opted_in": "2018-11-29T10:34:22",
        },
        {
          "ua_address" : "ben@icetown.com",
          "ua_commercial_opted_in": "2018-11-29T12:45:10",
        }
      ]
    },
    "device_types" : [ "email" ],
    "notification" : {
      "email": {
        "subject": "Welcome to the Winter Sale! ",
        "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
        "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
        "message_type": "commercial",
        "sender_name": "Airship",
        "sender_address": "team@urbanairship.com",
        "reply_to": "no-reply@urbanairship.com"
      }
    },
    "campaigns": {
        "categories": ["winter sale", "west coast"]
    }
  }
}

Example Response

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

{
  "ok": true,
  "operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
  "push_ids": [
      "8cf8b2a5-7655-40c2-a500-ff498e60453e"
  ],
  "schedule_urls": [
      "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
  ],
  "schedules": [
      {
        "push": {
            "audience": {
              "create_and_send": [
                  {
                    "ua_address": "new@email.com",
                    "ua_commercial_opted_in": "2018-11-29T10:34:22"
                  },
                  {
                    "ua_address": "ben@icetown.com",
                    "ua_commercial_opted_in": "2018-11-29T12:45:10"
                  }
              ]
            },
            "device_types": [
              "email"
            ],
            "notification": {
              "campaigns": {
                  "categories": [
                    "winter sale",
                    "west coast"
                  ]
              },
              "email": {
                  "html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
                  "message_type": "commercial",
                  "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
                  "reply_to": "no-reply@urbanairship.com",
                  "sender_address": "team@urbanairship.com",
                  "sender_name": "Airship",
                  "subject": "Welcome to the Winter Sale! "
              }
            }
        },
        "schedule": {
            "scheduled_time": "2018-11-11T12:00:00"
        },
        "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
      }
  ]
}

POST /api/schedules/create-and-send

Schedule a notification to an audience of SMS, email, or open channel addresses and simultaneously register those addresses as new channels. Addresses that are not yet associated with channels are registered as new channels. Addresses in the payload that are already registered to a channel_id and are either opted_in or have an opted_in value in the payload that is newer than the opted_out value associated with a channel will receive the notification, but are not re-registered as new channels.

You cannot update opted_in values for existing channels through this endpoint.

Warning

Security:
HTTP basic auth

Request Body

The request is much like other create-and-send operations, with a leading schedule object. The standard create-and-send payload sits inside a push object.

Content-Type: application/json
Object
OBJECT PROPERTIES
- name : String
  A name for the schedule.
- push : AnyRequired
  One of
  - Create and Send to Email Channels
    The payload for a create and send operation to email channels. When registering and sending to email channels, device_types must be set to email.
  - Create and Send to SMS Channels
    The payload for a create and send operation to SMS channels. When registering and sending to SMS channels, device_types must be set to sms.
  - Create and Send MMS Notification
    The payload for a create and send operation that registers SMS channels and sens a multimedia payload (MMS). When sending an MMS payload, device_types must be set to mms.
  - Create and Send to Open Channels
    When registering and sending to open channels, the device_type must be set to open::<open_channel_name>.
- schedule : ObjectRequired
  Similar to other schedule objects. However, create-and-send requests support scheduled_time only.
  OBJECT PROPERTIES
  scheduled_time : StringRequired
  The date and time when you want to perform your create-and-send operation. Users will receive the notification as soon as possible after the specified datetime.
  Format: datetime

Responses

202

Because this operation sends messages, a successful response is nearly identical to a /api/push response.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
A push response contains a list of identifiers for the notifications sent in the request.
OBJECT PROPERTIES
- content_urls : Array [String]
  An array of URLs where the push payload contains a landing page action.
  Max items: 100
  Min items: 1
- localized_ids : Array [String]
  An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).
- message_ids : Array [String]
  An array of message IDs, each uniquely identifying a Message Center message.
- ok : Boolean
  Success.
- operation_id : String
  A unique string identifying the operation, useful for reporting and troubleshooting.
  Format: uuid
- push_ids : Array [String]
  An array of push IDs, each uniquely indentifying a push.
  Max items: 100
  Min items: 1

400

You can only create-and-send to a single platform per request. Attempting to register channels and send notifications for multiple device_types in the same request will cause a 400 response.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Reports

The 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.

Devices Report

Example Request

GET /api/reports/devices 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;

{
    "total_unique_devices": 13186,
    "date_closed": "2018-08-28 00:00:00",
    "date_computed": "2018-08-29 13:30:45",
    "counts": {
        "ios": {
            "unique_devices": 231,
            "opted_in": 142,
            "opted_out": 89,
            "uninstalled": 2096
        },
        "android": {
            "unique_devices": 11795,
            "opted_in": 226,
            "opted_out": 11569,
            "uninstalled": 1069
        },
        "amazon": {
            "unique_devices": 29,
            "opted_in": 22,
            "opted_out": 7,
            "uninstalled": 9
        },
        "sms": {
            "unique_devices": 26,
            "opted_in": 23,
            "opted_out": 3,
            "uninstalled": 17
        }
    }
}

GET /api/reports/devices

Get an app’s opted-in and installed device counts by device type.

Security:
HTTP basic auth
HTTP bearer auth

query PARAMETERS

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

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
The response body for the device report.
OBJECT PROPERTIES
- counts : Object
  The counts for each device type.
  OBJECT PROPERTIES
  amazon : Object
  The count object for a device type.
  OBJECT PROPERTIES
  opted_in : Integer
  Opted in to receiving push notifications.
  opted_out : Integer
  Opted out of receiving push notifications.
  uninstalled : Integer
  Devices for which Reports has seen an uninstall event.
  unique_devices : Integer
  Devices considered by Airship Reports to have the app installed.
  android : Object
  The count object for a device type.
  OBJECT PROPERTIES
  opted_in : Integer
  Opted in to receiving push notifications.
  opted_out : Integer
  Opted out of receiving push notifications.
  uninstalled : Integer
  Devices for which Reports has seen an uninstall event.
  unique_devices : Integer
  Devices considered by Airship Reports to have the app installed.
  ios : Object
  The count object for a device type.
  OBJECT PROPERTIES
  opted_in : Integer
  Opted in to receiving push notifications.
  opted_out : Integer
  Opted out of receiving push notifications.
  uninstalled : Integer
  Devices for which Reports has seen an uninstall event.
  unique_devices : Integer
  Devices considered by Airship Reports to have the app installed.
- date_closed : String
  All device events counted occurred before this date and time.
  Format: date-time
- date_computed : String
  The date and time the device event data was tallied and stored.
  Format: date-time
- total_unique_devices : Integer
  Sum of the unique devices for every device type.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Custom Events Detail Listing

Example Request

GET /api/reports/events?start=2019-08-01T10:00:00.000Z&end=2019-08-15T20:00:00.000Z&precision=MONTHLY&page_size=20 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,
    "total_value": 2,
    "total_count": 709,
    "next_page": "https://go.urbanairship.com/api/reports/events?start=2019-08-01T10:00:00.000Z&end=2019-08-15T20:00:00.000Z&precision=MONTHLY&page_size=20&page=2",
    "events": [
        {
            "name": "banner_image",
            "conversion": "indirect",
            "location": "ua_mcrap",
            "count": 1,
            "value": 1
        },
        {
            "name": "bounce",
            "conversion": "direct",
            "location": "custom",
            "count": 23,
            "value": 0
        },
        {
            "name": "button-click-Do it ",
            "conversion": "direct",
            "location": "in_app_message",
            "count": 1,
            "value": 0
        },
        {
            "name": "button-click-Get Notifications",
            "conversion": "unattributed",
            "location": "in_app_message",
            "count": 3,
            "value": 0
        },
        {
            "name": "button-click-RATE NOW",
            "conversion": "direct",
            "location": "in_app_message",
            "count": 1,
            "value": 0
        },
        {
            "name": "button-click-Rate the app.",
            "conversion": "direct",
            "location": "in_app_message",
            "count": 1,
            "value": 0
        }
    ]
}

GET /api/reports/events

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

Security:
HTTP basic auth
HTTP bearer auth

query PARAMETERS

start : String Required
An ISO formatted timestamp for start of report.
end : String Required
An ISO formatted timestamp for end of report.
precision : String
Granularity of results to return; defaults to DAILY.
Possible values: HOURLY, DAILY, MONTHLY
page : Integer
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 : Integer
Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.

Responses

200

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

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
The response body for custom events detail listing.
OBJECT PROPERTIES
- events : Array [Object]
  An array of custom events and its details.
  ARRAY ITEM
  - Object
    Detail information about the custom event including its counts and values.
    OBJECT PROPERTIES
    conversion : String
    Can be one of direct or indirect.
    count : Integer
    Number of instances of this event.
    location : String
    The source from which the event originates, e.g. Message Center, Landing Page, custom, etc.
    name : String
    The name of the custom event.
    value : Integer
    The value generated by the event.
- next_page : String
  There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.
  Format: url
- ok : Boolean
  Success.
- prev_page : String
  Link to the previous page, if available.
  Format: url
- total_count : Integer
  Sum of all the count fields in the above array.
- total_value : Integer
  Sum of all the value fields in the above array.

400

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

401

Authentication information (the app key & secret) was either incorrect or missing.

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

403

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

RESPONSE BODY

Content-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Experiment Variant Report

Example Request

GET /api/reports/experiment/detail/b43ae1b2-3ff6-4c02-adb2-79deac0bbb19/2 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;

{
    "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": 2,
    "variant_name": "thing_two",
    "sends": 64,
    "direct_responses": 3,
    "influenced_responses": 1,
    "platforms": {
        "android": {
            "direct_responses": 0,
            "influenced_responses": 0,
            "sends": 22
        },
        "ios": {
            "direct_responses": 0,
            "influenced_responses": 1,
            "sends": 36
        },
        "amazon": {
            "direct_responses": 0,
            "influenced_responses": 0,
            "sends": 0
        },
        "web": {
            "direct_responses": 3,
            "indirect_responses": 0,
            "sends": 6
        }
    }
}

GET /api/reports/experiment/detail/{push_id}/{variant_id}

Returns statistics and metadata about a specific variant in an experiment (A/B Test).

Security:
HTTP basic auth
HTTP bearer auth

path PARAMETERS

push_id : String Required
The push_id of the requested experiment.
Format: uuid
variant_id : Integer Required
The specific variant you want to return results for.
Max: 26
Min: 1

Responses

200

Returned on success.

RESPONSE BODY

Content-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIES
- app_key : String
  The app key for the given push_id.
- created : String
  The date and time when the variant was created.
  Format: date-time
- direct_responses : Integer
  The number of direct responses to the variant.
- experiment_id : String
  ID of the experiment that the variant belongs to.
  Format: uuid
- influenced_responses : Integer
  The total number of influenced responses to the variant.
- platforms : Object
  OBJECT PROPERTIES
  amazon : Object
  OBJECT PROPERTIES
  direct_responses : Integer
  The number of direct responses (clicks/app opens) to the variant notification on this platform as measured by the SDK.
  influenced_responses : Integer
  The number of opens or clicks resulting from your notification (directly or indirectly).
  sends : Integer
  The total number of audience members that accounted the variant on the specified platform.
  android : Object
  OBJECT PROPERTIES
  direct_responses : Integer
  The number of direct responses (clicks/app opens) to the variant notification on this platform as measured by the SDK.
  influenced_responses : Integer
  The number of opens or clicks resulting from your notification (directly or indirectly).
  sends : Integer
  The total number of audience members that accounted the variant on the specified platform.
  ios : Object
  OBJECT PROPERTIES
  direct_responses : Integer
  The number of direct responses (clicks/app opens) to the variant notification on this platform as measured by the SDK.
  influenced_responses : Integer
  The number of opens or clicks resulting from your notification (directly or indirectly).
  sends : Integer
  The total number of audience members that accounted the variant on the specified platform.
  </

Introduction

API Request Format

Version Syntax

Transport Layer Security

Delivery Speed Options

Boost

Throttling

Base URL

Authentication

HTTP Authentication

HTTP Authentication

HTTP Authentication

Push

Send a Push

POST /api/push

Security:HTTP basic authHTTP bearer auth

Request Body

Content-Type: application/json

Push Object

Array of Push Objects. : Array [Push Object]

Responses

202

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

content_urls : Array [String]

localized_ids : Array [String]

message_ids : Array [String]

ok : Boolean

operation_id : String

push_ids : Array [String]

400

Content-Type: application/json

401

Content-Type: application/json

406

Content-Type: application/json

Validate Push

POST /api/push/validate

Security:HTTP basic authHTTP bearer auth

Request Body

Content-Type: application/json

Push Object

Array of Push Objects. : Array [Push Object]

Responses

200

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

400

Content-Type: application/json

401

Content-Type: application/json

406

Content-Type: application/json

Delete Message from Inbox

DELETE /api/user/messages/{push_id}

Security:HTTP basic auth

push_id : String Required

Responses

202

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

404

Content-Type: application/json

Schedules

List Schedules

GET /api/schedules

Security:HTTP basic auth

start : String

limit : Integer

Responses

200

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

count : Integer

next_page : String

ok : Boolean

schedules : Array [Schedule Object]

total_count : Integer

401

Content-Type: application/json

403

Content-Type: application/json

Schedule a Notification

POST /api/schedules

Security:
HTTP basic auth
HTTP bearer auth

Security:
HTTP basic auth
HTTP bearer auth

Security:
HTTP basic auth

Security:
HTTP basic auth

Security:
HTTP basic auth

Security:
HTTP basic auth

Security:
HTTP basic auth

Security:
HTTP basic auth