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

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

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

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

{
    "audience": {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    "notification": {
        "alert": "Hello!"
    },
    "device_types": [ "ios" ]
}

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

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

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 [Push Object]

    Max items: 100

    Min items: 1

Responses

202 Accepted

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.

• 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

  • 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

406 Not Acceptable

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

• Content-Type: application/json

  Error Response

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

Validate Push

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

{
   "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 [Push Object]

    Max items: 100

    Min items: 1

Responses

200 OK

Everything worked as expected.

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

406 Not Acceptable

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

• Content-Type: application/json

  Error Response

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

Delete Message from Inbox

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

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

{
   "ok": true
}

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.

Security:

• HTTP basic auth

• 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 Accepted

The request has been accepted for processing.

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Schedules

Schedule notifications.

List Schedules

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

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

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

GET /api/schedules

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

Security:

• HTTP basic auth

• 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 OK

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

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

Schedule a Notification

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

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 Created

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

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

List a Specific Schedule

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

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

{
   "name": "I would like to subscribe to your newsletter",
   "schedule": {
      "scheduled_time": "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

• schedule_id : String Required

  A required string ID of the schedule.

Responses

200 OK

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

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

  Schedule Object

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Update Schedule

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

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

• 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 OK

Returned if the scheduled push has been successfully updated.

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Delete Schedule

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

HTTP/1.1 204 No Content

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

• schedule_id : String Required

  A required string ID of the schedule.

Responses

204 No Content

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Automation

Manage Automated notifications using the /api/pipelines endpoints.

List Existing Pipelines

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

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

{
    "ok": true,
    "pipelines": [
      {
          "creation_time": "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

• 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 OK

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

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

Create Pipeline (Automated Message)

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

{
    "name":"The Darkest Pipeline",
    "enabled":true,
    "immediate_trigger":"first_open",
    "outcome":{
      "push":{
          "audience":"triggered",
          "device_types":[
            "ios",
            "android",
            "web"
          ],
          "notification":{
            "alert":"Cool goatee, Abed"
          }
      }
    },
    "timing":{
      "delay":{
          "seconds":7200
      },
      "schedule":{
          "type":"local",
          "miss_behavior":"wait",
          "dayparts":[
            {
                "days_of_week":[
                  "thursday"
                ],
                "allowed_times":[
                  {
                      "preferred":"21:30:00"
                  }
                ]
            }
          ]
      }
    }
}

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

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

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 Created

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

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

409 Conflict

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

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

  #/components/responses/409

  The request conflicts with another request.

List Deleted Pipelines

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

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

{
    "ok": true,
    "pipelines": [
      {
          "deletion_time": "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

• start : String

  Timestamp of the starting element for paginating results.

Responses

200 OK

Returns an array of deleted pipeline objects.

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

  OBJECT PROPERTIES

  • ok : Boolean

    Success.

  • pipelines : Array [Object]

    ARRAY ITEM
    • 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

Validate Pipeline

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

{
    "name":"The Darkest Pipeline",
    "enabled":true,
    "immediate_trigger":"first_open",
    "outcome":{
      "push":{
          "audience":"triggered",
          "device_types":[
            "ios",
            "android"
          ],
          "notification":{
            "alert":"Cool goatee, Abed"
          }
      }
    },
    "timing":{
      "delay":{
          "seconds":7200
      },
      "schedule":{
          "type":"local",
          "miss_behavior":"wait",
          "dayparts":[
            {
                "days_of_week":[
                  "thursday"
                ],
                "allowed_times":[
                  {
                      "preferred":"21:30:00"
                  }
                ]
            }
          ]
      }
    }
}

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

{
    "ok": true
}

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 [Pipeline Object]

Responses

200 OK

Everything worked as expected.

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

406 Not Acceptable

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

• Content-Type: application/json

  Error Response

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

Individual Pipeline Lookup

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

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

{
    "ok": true,
    "pipeline": {
      "creation_time": "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

• pipeline_id : String Required

  The pipeline you want to return or modify.

Responses

200 OK

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

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Update Pipeline

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

{
    "enabled": true,
    "immediate_trigger": {
      "tag_added": "new_customer"
    },
    "outcome": {
      "push": {
          "audience": "triggered",
          "device_types": [
            "ios"
          ],
          "notification": {
            "alert": "Hello new customer!"
          }
      }
    }
}

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

{
    "ok": true
}

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

• 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 OK

Everything worked as expected.

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

409 Conflict

The request conflicts with another request.

• Content-Type: application/json

  Error Response

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

Delete Pipeline

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

HTTP/1.1 204 No Content

DELETE /api/pipelines/{pipeline_id}

Delete a pipeline.

Security:

• HTTP basic auth

• pipeline_id : String Required

  The pipeline you want to return or modify.

Responses

204 No Content

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

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

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

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

 {
   "ok" : "true",
   "count" : 2,
   "total_count" : 2,
   "experiments" : [{
     "name" : "Experiment 1",
     "control" : 0.33,
     "audience" : "all",
     "device_types": [ "ios", "android" ],
     "variants" : [{
       "push" : {
         "notification" : {
           "alert" : "message 1"
         }
       },
       "id" : 0,
     },
     {
       "push" : {
           "notification" : {
             "alert" : "message 2"
           }
       },
       "id" : 1,
     }],
     "id" : "b5bc3dd1-9ea4-4208-b5f1-9e7ac3fe0502",
     "created_at" : "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

• 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 OK

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

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Create Experiment (A/B Test)

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

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 Created

The experiment was created.

• Location : String

  The newly created experiment.

  Format: uri

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Scheduled Experiment Listing

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

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

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

• 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 OK

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

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Delete Experiment

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

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

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

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

• experiment_id : String Required

  The unique identifier of the experiment.

Responses

200 OK

Returned if the experiment has been succesfully deleted.

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

405 Method Not Allowed

Returned when a request is made using an HTTP method not supported by the endpoint. For example, sending a DELETE to /api/schedules.

• Content-Type: application/json

  Error Response

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

Validate Experiment

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

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 OK

The experiment is valid.

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Experiment Lookup

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

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

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

GET /api/experiments/{experiment_id}

Look up an experiment (A/B Test).

Security:

• HTTP basic auth

• experiment_id : String Required

  The ID of the experiment you want to look up.

Responses

200 OK

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

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Personalization

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

List Templates

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

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

{
    "ok" : true,
    "count": 1,
    "total_count": 1,
    "templates": [
        {
            "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
            "created_at": "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.

Security:

• HTTP basic auth

• 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 OK

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

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Create Template

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

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "variables": [
        {
            "key": "TITLE",
            "name": "Title",
            "description": "e.g. Mr, Ms, Dr, etc.",
            "default_value": ""
        },
        {
            "key": "FIRST_NAME",
            "name": "First Name",
            "description": "Given name",
            "default_value": null
        },
        {
            "key": "LAST_NAME",
            "name": "Last Name",
            "description": "Family name",
            "default_value": null
        }
    ],
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
        }
    }
}

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

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

POST /api/templates

Create a new template.

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 Created

The template was created.

• Location : String

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

  Format: uri

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Push to Template

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

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

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

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

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.

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 [Push Template Payload]

Responses

202 Accepted

The push notification has been accepted for processing.

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

406 Not Acceptable

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

• Content-Type: application/json

  Error Response

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

Validate A Template

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

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

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

{
    "ok" : true
}

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 OK

Everything worked as expected.

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

406 Not Acceptable

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

• Content-Type: application/json

  Error Response

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

Schedule a Templated Push

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

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

  • 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 Accepted

The scheduled push has been accepted for processing.

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

406 Not Acceptable

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

• Content-Type: application/json

  Error Response

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

Lookup a Template

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

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

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

Security:

• HTTP basic auth

• template_id : String Required

  A required string ID of the template.

Responses

200 OK

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

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Update Template

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

{
    "name": "Welcome Message",
    "description": "Our welcome message",
    "push": {
        "notification": {
            "alert": "Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!"
        }
    }
}

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

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

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.

Security:

• HTTP basic auth

• template_id : String Required

  A required string ID of the template.

Request Body

• Content-Type: application/json

  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 OK

Returned if the template has been succesfully updated.

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Delete Template

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

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

{
    "ok": true,
    "operation_id": "a6394ff8-8a65-4494-ad06-677eb8b7ad6a"
}

DELETE /api/templates/{template_id}

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

Security:

• HTTP basic auth

• template_id : String Required

  A required string ID of the template.

Responses

200 OK

The template with given ID has been succesfully deleted.

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

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

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

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

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

• 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 OK

Returns OK for success.

• 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 Bad Request

returned when limit is greater than 1000.

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

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Region Lookup

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

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

{
    "ok": true,
    "region": {
        "region_id": "7dbd9a5c-eff5-40f2-b648-4352c1668878",
        "created_at": "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

• region_id : String Required

  The region you want to lookup.

Responses

200 OK

Returns OK for success.

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

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

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

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

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

POST /api/custom-events

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

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 OK

Returned on success.

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Channels

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

Channel Listing

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

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

Returns OK for success with the JSON response.

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

• 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Channel Tags

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

{
   "audience": {
      "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881",
      "android_channel": "13863b3c-f860-4bbf-a9f1-4d785379b8a2"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
   }
}

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

{
   "ok": true,
   "warnings": ["The following tag groups do not exist: my_fav_tag_group2", "The following tag groups are deactivated: my_fav_tag_group3"]
}

POST /api/channels/tags

Add, remove, or set tags on a channel.

Security:

• HTTP basic auth
• HTTP bearer auth

Request Body

• Content-Type: application/json

  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 OK

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

• 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

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

Uninstall Channels

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

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

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

{
   "ok": true
}

POST /api/channels/uninstall

Uninstalls a channel, removing it and all accompanying analytic data (including Performance Analytics) from Airshp systems in accordance with GDPR 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 Data Subject Rights Support Under GDPR for more information about GDPR compliance.

Security:

• HTTP basic auth
• HTTP bearer auth

Request Body

• Content-Type: application/json

  Array [Object]

  Max items: 1000

  Min items: 1

  ARRAY ITEM

  • specifies the channel ID and device type you want to uninstall.

    OBJECT PROPERTIES

    • channel_id : StringRequired

      The channel ID.

    • device_type : StringRequired

      The device type of the channel. Valid values are 'ios', 'amazon', 'android', 'web', 'open'.

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

Responses

202 Accepted

The request has been accepted for processing.

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Channel Lookup

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

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

Security:

• HTTP basic auth
• HTTP bearer auth

• channel_id : String Required

  The channel you want to look up.

Responses

200 OK

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.

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

  OBJECT PROPERTIES

  • channel : Channel Object

    A channel object.

  • ok : Boolean

    Success.

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

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

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

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.

Security:

• HTTP basic auth

Request Body

An open channel object.

• Content-Type: application/json

  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 shortcode. Will set the ua_locale_country tag group to the specified value.

    • locale_language : String

      The two-letter language locale shortcode. 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 OK

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

• Location : String

  Used for later API calls for this channel.

  Format: uri

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

429 Too Many Requests

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.

• Content-Type: application/json

  Error Response

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

Open Channel Tags

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

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.

Security:

• HTTP basic auth

Request Body

• Content-Type: application/json

  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 OK

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

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

Uninstall Open Channels

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

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

  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 Accepted

The request has been accepted for processing.

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Email

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

Register Email Channel

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

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

  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 Created

The email channel was created.

• Location : String

  The newly created email channel.

  Format: uri

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Email Tags

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.

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

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

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

Uninstall Email Channel

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

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 PROPERTIES

  • email_address : StringRequired

    The email address of the channel to uninstall.

Responses

202 Accepted

The request has been accepted for processing.

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

Lookup an Email Address

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

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

• email_channel_id : String Required

  The email address of the channel you want to look up.

Responses

200 OK

A channel exists for the email address

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

  Channel Object

  Describes a channel.

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Update an Email Channel

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

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

• email_channel_id : String Required

  The email channel_id you want to modify.

Request Body

• Content-Type: application/json

  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 OK

The email channel was updated.

• Location : String

  The updated email channel.

  Format: uri

• 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 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

SMS

Register and manage SMS channels. See SMS Platform Information to get started with SMS notifications.

Register SMS Channel

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

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

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

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

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.

Security:

• HTTP basic auth
• HTTP bearer auth

Request Body

• Content-Type: application/json

  OBJECT PROPERTIES

  • 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 number the app is configured to send from, provided by Airship. Must be numeric characters only.

Responses

200 OK

A channel with this msisdn/sender combination already exists.

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

  One of

  • 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

  • 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 Created

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.

• location : String

  URI of the channel, used for later registrations.

  Format: url

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

  One of

  • 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

  • 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 Bad Request

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.

• 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

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

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

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

    The SMS sender ID provided by Airship. Must be numeric characters only.

Responses

202 Accepted

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

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

  OBJECT PROPERTIES

  • ok : Boolean

    If true, the operation completed successfully.

400 Bad Request

The request body is not valid.

• 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

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

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

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 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 number the app is configured to send from, provided by Airship. Must be numeric characters only.

Responses

202 Accepted

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

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

  OBJECT PROPERTIES

  • ok : Boolean

    If true, the operation was successful.

400 Bad Request

The request body is not valid.

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

SMS Channel Lookup

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

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": [
            "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.

• 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 number the app is configured to send from, provided by Airship. Must be numeric characters only.

Responses

200 ok

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

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

  OBJECT PROPERTIES

  • channel : Channel Object

    Describes a channel.

  • ok : Boolean

    Success.

404 Not Found

A channel_id does not exist for the msisdn and sender.

• 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

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/transactions to see more about your account."
      "shorten_links": true
  },
  "mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}

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 for information about setting up a custom response webhook server.

This endpoint requires a bearer authorization.

Security:

• HTTP bearer auth

Request Body

• Content-Type: application/json

  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. This leaves more characters available for your message and produces short_link_click events in the Real-Time Data Stream for each link that a user engages with.

Responses

200 OK

The operation was successful.

• 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 Not Found

The mobile_originated_id could not be found.

• 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

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

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

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

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

• 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 OK

Returns OK for success.

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

  One of

  • Response for a single named_user_id query.

    OBJECT PROPERTIES

    • named_user : Named User Object

      The response body for named user lookup, including tags and channels associated with the named user.

    • ok : Boolean

      Success.

  • 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 Unauthorized

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

• Content-Type: application/json

  Error Response

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

404 Not Found

The requested resource doesn't exist.

• Content-Type: application/json

  Error Response

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

Named Users Association

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

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

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

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.

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

  • 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 OK

Everything worked as expected.

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

  Ok Response

  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc), the ok key will appear in the top-most object, outside the verbose response.

400 Bad Request

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.

• Content-Type: application/json

  Error Response

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

401 Unauthorized

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

• Content-Type: application/json

  Error Response

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

403 Forbidden

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

• Content-Type: application/json

  Error Response

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

Named Users Disassociation

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

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

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