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.
Base URL
All URLs referenced in the documentation have the following base: https://go.urbanairship.com.
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
- The base URL of the Airship server.
Authentication
HTTP Authentication
basic appAuthorization header containing the wordBasicfollowed by a space and a Base64-encoded string generated from your app key and app secret, e.g.,Basic YXBwX2tleTphcHBfc2VjcmV0.HTTP Authentication
basic masterAuthorization header containing the wordBasicfollowed by a space and a Base64-encoded string generated from your app key and master secret, e.g.,Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0.HTTP Authentication
bearerThe authorization header containing your Bearer token, which can be obtained from Airship. Tokens may be revoked at will.
Push
Send notifications or rich messages to supported channels, or validate JSON payloads.
Send a Push
Example Request
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
},
"notification": {
"alert": "Hello!"
},
"device_types": [ "ios" ]
}Example Response
HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
"push_ids": [
"9d78a53b-b16a-c58f-b78d-181d5e242078"
]
}Send a push notification to a specified audience. The body of the request must be a Push Object or an array of Push Objects.
Security:
Request Body
A single push object or an array of push objects.
application/json
Type: Any
- One of:
Type: 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.
Type: Array<Push Object>
Max items: 100. Min items: 1.
Response
202 Accepted
The push notification has been accepted for processing. The response contains
push_id,message_id, and/orcontent_urlarrays based on the type of push.Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
A push response contains a list of identifiers for the notifications sent in the request.
content_urls
Array<String>OptionalAn array of URLs where the push payload contains a landing page action.
Max items: 100. Min items: 1.
Format:
uri. Pattern:^https.*:\/\/.+.message_ids
Array<String>OptionalAn array of message IDs, each uniquely identifying a Message Center message.
ok
BooleanOptionalSuccess.
operation_id
StringOptionalA unique string identifying the operation, useful for reporting and troubleshooting.
Format:
uuid.push_ids
Array<String>OptionalAn array of push IDs, each uniquely indentifying a push.
Max items: 100. Min items: 1.
Format:
uuid.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
406 Not Acceptable
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
Response Body
application/json
Type: 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
Missing Payload Example: A push which specifies delivery to a platform, but does not supply a payload for that platform, is invalid. This push is invalid because it specifies Android as a delivery platform, but does not provide a payload for Android.
{
"audience": "all",
"device_types": [
"ios",
"android"
],
"notification": {
"ios": {
"alert": "Boo"
}
}
}Example: Device Identifier/Restriction Mis-Match: A push which includes a device identifier in the audience selection, but does not include the corresponding platform in the
"device_types"specifier, is invalid. This push is invalid because it includes an iOS channel in the audience selection, but has not specified "ios" as a delivery platform.
{
"audience": {
"or": [
{
"android_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d0"
},
{
"ios_channel": "a5b41490-16c1-448a-ba27-af1c78c8de09"
}
]
},
"device_types": [
"android"
],
"notification": {
"alert": "Who wore it better: iOS or Android?"
}
}Accept the same range of payloads as POSTing to /api/push, but parse and validate only, without sending any pushes. The body of the request must be a Push Object or an array of Push Objects.
Security:
Request Body
A single push object or an array of push objects.
application/json
Type: Any
- One of:
Type: 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.
Type: Array<Push Object>
Max items: 100. Min items: 1.
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
406 Not Acceptable
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
Response Body
application/json
Type: 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
Example Request
DELETE /api/user/messages/(push_id) HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}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.
For time-sensitive messages you should consider including an expiry time, as detailed in the In-App Message Object. Setting an expiry value will prevent you from having to manually remove messages.
Request Parameters
push_id path
StringRequiredThe
push_idormessage_idof the Rich Message you want to delete from users` inboxes.Format:
uuid.
Response
202 Accepted
The request has been accepted for processing.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey will appear in the top-most object, outside the verbose response.404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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.
The API prohibits batch sizes of larger than 1000 for scheduled pushes, and batches of larger than 100 for push to local time scheduled pushes.
List Schedules
Example Request
GET /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Count: 2
Data-Attribute: schedules
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"count": 2,
"total_count": 4,
"next_page": "https://go.urbanairship.com/api/schedules/?start=5c69320c-3e91-5241-fad3-248269eed104&limit=2&order=asc",
"schedules": [
{
"url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
"schedule": { },
"push": { }
},
{
"url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed10A",
"schedule": { },
"push": { }
}
]
}List all existing schedules. Returns an array of schedule objects in the schedules attribute.
Security:
Request Parameters
start query
StringOptionalAn optional string ID of the starting element for paginating results.
limit query
IntegerOptionalAn optional integer as maximum number of elements to return.
Response
200 OK
Returned on success, with the JSON representation of the scheduled pushes in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
count
IntegerOptionalnext_page
StringOptionalThere 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
BooleanOptionalSuccess.
An array of Schedule Objects.
total_count
IntegerOptional
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response Body
application/json
Type: 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
Example Request
POST /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
[
{
"name": "Morning People",
"schedule": {
"scheduled_time": "2018-06-03T09:15:00"
},
"push": {
"audience": { "tag": "earlyBirds" },
"notification": { "alert": "Good Day Sunshine" },
"device_types": [ "ios", "android" ]
}
},
{
"name": "Everybody Else",
"schedule": {
"best_time": {
"send_date": "2018-06-03"
}
},
"push": {
"audience": { "tag": "normalPeople" },
"notification": { "alert": "Stay Up Late" },
"device_types": [ "ios", "android" ]
}
}
]Example Response
HTTP/1.1 201 Created
Data-Attribute: schedule_urls
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
"schedule_urls": [
"https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
"https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
],
"schedule_ids": [
"eac2ace6-349a-41a2-b874-5496d7bf0100",
"6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
],
"schedules": [
{
"url": "https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
"schedule": {
"scheduled_time": "2016-06-03T09:15:00"
},
"name": "Morning People",
"push": {
"audience": { "tag": "earlyBirds" },
"notification": { "alert": "Good Day Sunshine" },
"device_types": [ "ios", "android" ]
},
"push_ids": [ "83046227-9b06-4114-9f23-0df349792bbd" ]
}
{
"url": "https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e",
"schedule": {
"best_time": {
"send_date": "2018-06-03"
}
},
"name": "Everybody Else",
"push": {
"audience": { "tag": "normalPeople" },
"notification": { "alert": "Stay Up Late" },
"device_types": [ "ios", "android" ]
},
"push_ids": [ "8438e81-bb31-82a9-5feb-e7fd5b21ca7e" ]
}
]
}Scheduled notifications are created by POSTing to the schedule URI. The body of the request must be one of a single schedule object or an array of one or more schedule objects.
Security:
Request Body
A single schedule object or an array of schedule objects.
application/json
Type: Any
- One of:
Type: Schedule Object
A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.
Type: Array<Schedule Object>
Response
201 Created
The response body will contain an array of response objects with the created resource URIs.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
ok
BooleanOptionalSuccess.
operation_id
StringOptionalA 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>OptionalAn array of schedule IDs, each string uniquely identifying a schedule.
Max items: 100. Min items: 1.
Format:
uuid.schedule_urls
Array<String>OptionalAn array of schedule URLs.
Max items: 100. Min items: 1.
Format:
uri. Pattern:^https.*:\/\/.+.An array of schedule objects.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: 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.
Response Body
application/json
Type: 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
Example Request
GET /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"name": "I would like to subscribe to your newsletter",
"schedule": {
"scheduled_time": "2018-04-01T18:45:30"
},
"push": {
"audience": {
"tag": [
"intriguing",
"ideas" ]
},
"notification": {
"alert": "Check your inbox!"
},
"device_types": [ "ios", "android" ]
}
}Fetch the current definition of a single schedule resource. Returns a single schedule object.
Security:
Request Parameters
id path
StringRequiredA required string ID of the schedule.
Response
200 OK
Returned on success, with the JSON representation of the scheduled push in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 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.
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.
Response Body
application/json
Type: 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.
Response Body
application/json
Type: 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
Example Request
PUT /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "I would like to subscribe to your newsletter",
"schedule": {
"scheduled_time": "2018-04-01T18:45:30"
},
"push": {
"audience": {
"tag": [
"intriguing",
"ideas",
"thought_leadership"
]
},
"notification": {
"alert": "Check your inbox!"
},
"device_types": [ "ios", "android" ]
}
}Example Response
HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "7c56d013-5599-d66d-6086-6205115d85e2",
"schedule_urls": [ "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e" ],
"schedules": [
{
"url": "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e",
"schedule": {
"scheduled_time": "2013-04-01T18:45:30"
},
"name": "I would like to subscribe to your newsletter",
"push": {
"audience": {"tag": ["intriguing", "ideas", "thought_leadership"] },
"notification": {"alert": "Check your inbox!"},
"device_types": [ "ios", "android" ]
},
"push_ids": [ "48fb8e8a-ee51-4e2a-9a47-9fab9b13d846" ]
}
]
}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:
Request Parameters
id path
StringRequiredA required string ID of the schedule.
Request Body
A single schedule object.
application/json
Type: Schedule Object
A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.
Response
200 OK
Returned if the scheduled push has been succesfully updated.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
ok
BooleanOptionalSuccess.
operation_id
StringOptionalA 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>OptionalAn array of schedule URLs.
Max items: 100. Min items: 1.
Format:
uri. Pattern:^https.*:\/\/.+.An array of schedule objects.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: 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.
Response Body
application/json
Type: 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
Example Request
DELETE /api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 204 No ContentDelete 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:
Request Parameters
id path
StringRequiredA required string ID of the schedule.
Response
204 No Content
The delete operation was successful.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 204
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.
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.
Response Body
application/json
Type: 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.
Response Body
application/json
Type: 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.
In the dashboard UI, we refer to pipelines as Automation or Automated Messages.
List Existing Pipelines
Example Request
GET /api/pipelines/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"pipelines": [
{
"creation_time": "2015-03-20T18:37:23",
"enabled": true,
"immediate_trigger": {
"tag_added": { "tag": "bought_shoes" }
},
"last_modified_time": "2015-03-20T19:35:12",
"name": "Shoe buyers",
"outcome": {
"push": {
"audience": "triggered",
"device_types": [ "android" ],
"notification": { "alert": "So you like shoes, huh?" }
}
},
"status": "live",
"uid": "3987f98s-89s3-cx98-8z89-89adjkl29zds",
"url": "https://go.urbanairship.com/api/pipelines/3987f98s-89s3-cx98-8z89-89adjkl29zds"
},
{
"..."
}
]
}List existing pipelines. Pipelines are ordered by creation_date from newest to oldest.
Security:
Request Parameters
limit query
IntegerOptionalThe maximum number of results to return; this is effectively the page size for the response.
Min: 1.
enabled query
BooleanOptionalIf true, limits the listing to enabled pipelines (
"enabled": true). If false or ommitted, lists all pipelines, whetherenabledistrueorfalse.offset query
IntegerOptionalThe first result you want to return. This parameter assists in pagination.
Response
200 OK
Returned on success, with a JSON representation of pipelines matching your query parameters.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
The response body for a pipelines request.
next_page
StringOptionalAn URI that points to the next page of pipelines. The page size is specified by the
limitparameter and the start point by thestartparameter. If there are no more pipelines for a next page we omit the next page link.ok
BooleanOptionalSuccess.
operation_id
StringOptionalA 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>OptionalAn array of pipeline IDs.
A string uniquely identifying a pipeline.
pipeline_urls
Array<String>OptionalAn 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.
A string URL of the newly created pipeline.
Format:
uri.A list of pipeline objects.
prev_page
StringOptionalAn URI that points to the previous page of pipelines. The page size is specified by the
limitparameter and the start point by thestartparameter. If there are no more pipelines for a previous page we omit the previous page link.total_count
IntegerOptionalThe total count of pipelines.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response Body
application/json
Type: 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)
Example Request
POST /api/pipelines HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name":"The Darkest Pipeline",
"enabled":true,
"immediate_trigger":"first_open",
"outcome":{
"push":{
"audience":"triggered",
"device_types":[
"ios",
"android",
"web"
],
"notification":{
"alert":"Cool goatee, Abed"
}
}
},
"timing":{
"delay":{
"seconds":7200
},
"schedule":{
"type":"local",
"miss_behavior":"wait",
"dayparts":[
{
"days_of_week":[
"thursday"
],
"allowed_times":[
{
"preferred":"21:30:00"
}
]
}
]
}
}
}Example Response
HTTP/1.1 201 Created
Content-Length: 123
Data-Attribute: pipeline_urls
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
"pipeline_urls": [
"https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
]
}Create one or more pipelines. You can provide a single pipeline object or an array of pipeline objects.
Security:
Request Body
A single pipeline object or an array of pipeline objects.
application/json
Type: Any
- One of:
Type: 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_triggerorhistorical_triggermust be supplied.Type: Array<Pipeline Object>
Response
201 Created
If creating more than one pipeline, pipeline URIs are returned in the same order as the pipeline objects in the request.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
The response body for a pipelines request.
next_page
StringOptionalAn URI that points to the next page of pipelines. The page size is specified by the
limitparameter and the start point by thestartparameter. If there are no more pipelines for a next page we omit the next page link.ok
BooleanOptionalSuccess.
operation_id
StringOptionalA 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>OptionalAn array of pipeline IDs.
A string uniquely identifying a pipeline.
pipeline_urls
Array<String>OptionalAn 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.
A string URL of the newly created pipeline.
Format:
uri.A list of pipeline objects.
prev_page
StringOptionalAn URI that points to the previous page of pipelines. The page size is specified by the
limitparameter and the start point by thestartparameter. If there are no more pipelines for a previous page we omit the previous page link.total_count
IntegerOptionalThe total count of pipelines.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: 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.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 409
The request conflicts with another request.
List Deleted Pipelines
Example Request
GET /api/pipelines/deleted/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"pipelines": [
{
"deletion_time": "2014-03-31T20:54:45",
"pipeline_id": "0sdicj23-fasc-4b2f-zxcv-0baf934f0d69"
},
{
"..."
}
]
}Produces a list of all deleted pipelines starting with the most recently deleted entry.
Security:
Request Parameters
start query
StringOptionalTimestamp of the starting element for paginating results.
Response
200 OK
Returns an array of deleted pipeline objects.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalSuccess.
pipelines
Array<Object>Optionaldeletion_time
StringOptionalAn ISO 8601 UTC timestamp indicating the date and time that the pipeline was deleted.
Format:
date-time.pipeline_id
StringOptionalThe unique identifier for a pipeline.
Format:
uuid.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response Body
application/json
Type: 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
Example Request
POST /api/pipelines/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name":"The Darkest Pipeline",
"enabled":true,
"immediate_trigger":"first_open",
"outcome":{
"push":{
"audience":"triggered",
"device_types":[
"ios",
"android"
],
"notification":{
"alert":"Cool goatee, Abed"
}
}
},
"timing":{
"delay":{
"seconds":7200
},
"schedule":{
"type":"local",
"miss_behavior":"wait",
"dayparts":[
{
"days_of_week":[
"thursday"
],
"allowed_times":[
{
"preferred":"21:30:00"
}
]
}
]
}
}
}Example Request
HTTP/1.1 200 OK
Content-Length: 11
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}This endpoint accepts the same range of payloads as a POST to /api/pipelines, but only parses and validates the payload, without creating the pipeline. The body of the request must be a single pipeline object or an array of pipeline objects.
Security:
Request Body
A single pipeline object or an array of pipeline objects.
application/json
Type: Any
- One of:
Type: 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_triggerorhistorical_triggermust be supplied.Type: Array<Pipeline Object>
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
406 Not Acceptable
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
Response Body
application/json
Type: 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
Example Request
GET /api/pipelines/4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"pipeline": {
"creation_time": "2015-02-14T19:19:19",
"enabled": true,
"immediate_trigger": { "tag_added": "new_customer" },
"last_modified_time": "2015-03-01T12:12:54",
"name": "New customer",
"outcome": {
"push": {
"audience": "triggered",
"device_types": [ "ios", "android" ],
"notification": { "alert": "Hello new customer!" }
}
},
"status": "live",
"uid": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
"url": "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
}
}Fetch a single pipeline resource. Returns an array containing a single pipeline object in the pipelines attribute.
Security:
Request Parameters
pipeline_id path
StringRequiredThe pipeline you want to return or modify.
Response
200 OK
Returned on success, with the JSON representation of the pipeline in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
The response body for a pipelines request.
next_page
StringOptionalAn URI that points to the next page of pipelines. The page size is specified by the
limitparameter and the start point by thestartparameter. If there are no more pipelines for a next page we omit the next page link.ok
BooleanOptionalSuccess.
operation_id
StringOptionalA 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>OptionalAn array of pipeline IDs.
A string uniquely identifying a pipeline.
pipeline_urls
Array<String>OptionalAn 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.
A string URL of the newly created pipeline.
Format:
uri.A list of pipeline objects.
prev_page
StringOptionalAn URI that points to the previous page of pipelines. The page size is specified by the
limitparameter and the start point by thestartparameter. If there are no more pipelines for a previous page we omit the previous page link.total_count
IntegerOptionalThe total count of pipelines.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response Body
application/json
Type: 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.
Response Body
application/json
Type: 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
Example Request
PUT /api/pipelines/0f927674-918c-31ef-51ca-e96fdd234da4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json;
{
"enabled": true,
"immediate_trigger": {
"tag_added": "new_customer"
},
"outcome": {
"push": {
"audience": "triggered",
"device_types": [
"ios"
],
"notification": {
"alert": "Hello new customer!"
}
}
}
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}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:
Request Parameters
pipeline_id path
StringRequiredThe pipeline you want to return or modify.
Request Body
A single pipeline object or an array of pipeline objects.
application/json
Type: 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.
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: 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.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 409
The request conflicts with another request.
Delete Pipeline
Example Request
DELETE /api/pipelines/0f927674-918c-31ef-51ca-e96fdd234da4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 204 No ContentDelete a pipeline.
Security:
Request Parameters
pipeline_id path
StringRequiredThe pipeline you want to return or modify.
Response
204 No Content
The delete operation was successful.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 204
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.
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.
Response Body
application/json
Type: 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.
Response Body
application/json
Type: 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
Example Request
GET /api/experiments HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiments
Count: 2
Total-Count: 2
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"count" : 2,
"total_count" : 2,
"experiments" : [{
"name" : "Experiment 1",
"control" : 0.33,
"audience" : "all",
"device_types": [ "ios", "android" ],
"variants" : [{
"push" : {
"notification" : {
"alert" : "message 1"
}
},
"id" : 0,
},
{
"push" : {
"notification" : {
"alert" : "message 2"
}
},
"id" : 1,
}],
"id" : "b5bc3dd1-9ea4-4208-b5f1-9e7ac3fe0502",
"created_at" : "2016-03-03T21:08:05",
"push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
}, {
"name" : "Experiment 2",
"description" : "The second experiment",
"audience" : "all",
"device_types": [ "ios", "android" ],
"variants" : [{
"push" : {
"notification" : {
"alert" : "message 1"
}
},
"id" : 0,
},
{
"push" : {
"notification" : {
"alert" : "message 2"
}
},
"id" : 1,
}],
"id" : "e464aa7e-be40-4994-a290-1bbada7187d8",
"created_at" : "2016-03-03T21:08:05",
"push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
}]
}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:
Request Parameters
limit query
IntegerOptionalPositive maximum number of elements to return per page. The default
limitis 10 entries with a maximum of 100 entries.Max: 100. Min: 1.
offset query
IntegerOptionalA 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
offsetis greater than the number of queryable experiments, an empty result will be returned.
Response
200 OK
Returned on success, with the JSON representation of the experiments in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
count
IntegerOptionalThe number of items returned in this page of results.
Experiment objects sorted by either
created_atfrom newest to oldest. The number of objects will never exceed the limit specified in the request.next_page
StringOptionalA relative URL leading to the next page of results. If there are no more results, next_page is absent.
ok
BooleanOptionalIf true, the call was successful.
total_count
IntegerOptionalThe total number of results.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
Create Experiment (A/B Test)
Example Request
POST /api/experiments HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "Experiment 1",
"audience": "all",
"device_types": [ "ios", "android" ],
"variants": [
{
"push": {
"notification": {
"alert": "message 1"
}
}
},
{
"push": {
"notification": {
"alert": "message 2"
}
}
}
]
}Example Response
HTTP/1.1 201 Created
Content-Length: 123
Location: https://go.urbanairship.com/api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4",
"experiment_id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
"push_id" : "7e13f060-594c-11e4-8ed6-0800200c9a66"
}Create an experiment. The body of the request should consist of a single experiment object. The experiment is processed and sent immediately unless a schedule is present.
Security:
Request Body
application/json
Type: Experiment Object
An experiment object describes an A/B test, including the audience and variant portions.
Response
201 Created
The experiment was created.
Response Headers
Location
StringThe newly created experiment.
Format:
uri.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for an experiment request.
experiment_id
StringOptionalUnique identifier for an experiment.
Format:
uuid.ok
BooleanOptionalIf true, the expeiment was successfully created. If false, the expriment was not created.
operation_id
StringOptionalA 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
StringOptionalUnique identifier for a push.
Format:
uuid.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Scheduled Experiment Listing
Example Request
GET /api/experiments/scheduled HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiments
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": "true",
"count": 2,
"total_count": 2,
"experiments": [
{
"id": "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
"name": "Experiment 1",
"audience": "all",
"device_types": [ "ios", "android" ],
"variants": [
{
"id": 0,
"schedule": {
"scheduled_time": "2015-11-17T20:58:00Z"
},
"push": {
"notification": {
"alert": "message 1"
}
}
},
{
"id": 1,
"schedule": {
"scheduled_time": "2015-11-17T20:58:00Z"
},
"push": {
"notification": {
"alert": "message 2"
}
}
}
]
},
{
"id": "29705c10-5951-11e4-8ed6-0800200c9a66",
"name": "Experiment 2",
"audience": "all",
"device_types": [ "ios", "android" ],
"variants": [
{
"id": 0,
"schedule": {
"scheduled_time": "2015-12-17T20:58:00Z"
},
"push": {
"notification": {
"alert": "message 1"
}
}
},
{
"id": 1,
"schedule": {
"scheduled_time": "2015-12-17T20:58:00Z"
},
"push": {
"notification": {
"alert": "message 2"
}
}
}
]
}
]
}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:
Request Parameters
limit query
IntegerOptionalPositive maximum number of elements to return per page. The default
limitis 10 entries with a maximum of 100 entries.Max: 100. Min: 1.
offset query
IntegerOptionalA 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
offsetis greater than the number of queryable experiments, the result set will be empty.
Response
200 OK
Returned on success, with the JSON representation of the experiments in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
count
IntegerOptionalThe number of items in this page of results.
Experiments listed by
scheduled_timein ascending time order. The number of objects will never exceed thelimitspecified in the request.next_page
StringOptionalA relative URL leading to the next page of results. If there are no more results, next_page is absent.
ok
BooleanOptionalIf true, the operation completed successfully and returns an expected result set.
total_count
IntegerOptionalThe total number of results.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
Delete Experiment
Example Request
DELETE /api/experiments/scheduled/(experiment_id) HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}Delete 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:
Request Parameters
experiment_id path
StringRequiredThe unique identifier of the experiment.
Response
200 OK
Returned if the experiment has been succesfully deleted.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
The response body for a pipelines deletion request.
ok
BooleanOptionalSuccess.
operation_id
StringOptionalA 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.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Experiments can only be deleted before they start; afterwards, a HTTP 405 is returned.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 405
Returned when a request is made using an HTTP method not supported by the endpoint. For example, sending a DELETE to /api/schedules.
Validate Experiment
Example Request
POST /api/experiments HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "Experiment 1",
"audience": "all",
"device_types": [ "ios", "android" ],
"variants": [
{
"push": {
"notification": {
"alert": "message 1"
}
}
},
{
"push": {
"notification": {
"alert": "message 2"
}
}
}
]
}Example Response
HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}Accepts the same range of payloads as /api/experiments, but only parses and validates the payload without creating the experiment. This does the same amount of validation as the creation endpoint, including platform-specific validation, e.g., APNS byte limit checks. While this operation ensures the experiment is technically valid, it does not guarantee that a resulting push will succeed. An experiment may validate and still fail to be delivered. For example, you may have a valid experiment with no devices in your audience.
Security:
Request Body
A single experiment object.
application/json
Type: Experiment Object
An experiment object describes an A/B test, including the audience and variant portions.
Response
200 OK
The experiment is valid.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, the operation completed successfully and returns an expected response.
operation_id
StringOptionalA 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Experiment Lookup
Example Request
GET /api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiment
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"experiment" : {
"id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
"push_id": "d00f07b0-594c-11e4-8ed6-0800200c9a66",
"name" : "Experiment 1",
"audience" : "all",
"device_types": [ "ios", "android" ],
"variants" : [{
"push" : {
"notification" : {
"alert" : "message 1"
}
},
"id" : 0,
},
{
"push" : {
"notification" : {
"alert" : "message 2"
}
},
"id" : 1,
}]
}
}Look up an experiment (A/B Test).
Security:
Request Parameters
experiment_id path
StringRequiredThe ID of the experiment you want to look up.
Response
200 OK
Returned on success, with the JSON representation of the experiment in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
An experiment object describes an A/B test, including the audience and variant portions.
ok
BooleanOptionalIf true, the operation completed successfully and returns a result set.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Example Request
GET /api/templates HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Data-Attribute: templates
Count: 1
Total-Count: 1
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true,
"count": 1,
"total_count": 1,
"templates": [
{
"id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"created_at": "2015-08-17T11:10:01Z",
"modified_at": "2015-08-17T11:10:01Z",
"last_used": null,
"name": "Welcome Message",
"description": "Our welcome message",
"variables": [
{
"key": "TITLE",
"name": "Title",
"description": "e.g. Mr, Ms, Dr, etc.",
"default_value": ""
},
{
"key": "FIRST_NAME",
"name": "First Name",
"description": "Given name",
"default_value": null
},
{
"key": "LAST_NAME",
"name": "Last Name",
"description": "Family name",
"default_value": null
}
],
"push": {
"notification": {
"alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
}
}
}
],
"next_page": null,
"prev_page": null
}List all existing templates. Returns an array of template objects in the templates attribute.
Security:
Request Parameters
page query
IntegerOptionalSpecifies the desired page number. Defaults to 1.
page_size query
IntegerOptionalSpecifies how many results to return per page. Has a default value of 25 and a maximum value of 100.
sort query
StringOptionalSpecifies the name of the field you want to sort results by. Defaults to
created_at.Possible values:
created_at,modified_at,last_used.order query
StringOptionalThe direction of the sort, asc for ascending, and desc for descending. Defaults to asc.
Possible values:
asc,desc.
Response
200 OK
Returned on success, with the JSON representation of the templates in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
count
IntegerOptionalThe number of templates in the current response; this is effectively the page size.
next_page
StringOptionalThere 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
BooleanOptionalSuccess.
prev_page
StringOptionalLink to the previous page, if available.
Format:
url.An array of Template Objects.
total_count
IntegerOptionalThe total number of templates.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
Create Template
Example Request
POST /api/templates HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "Welcome Message",
"description": "Our welcome message",
"variables": [
{
"key": "TITLE",
"name": "Title",
"description": "e.g. Mr, Ms, Dr, etc.",
"default_value": ""
},
{
"key": "FIRST_NAME",
"name": "First Name",
"description": "Given name",
"default_value": null
},
{
"key": "LAST_NAME",
"name": "Last Name",
"description": "Family name",
"default_value": null
}
],
"push": {
"notification": {
"alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
}
}
}Example Response
HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161
Content-Type: application/vnd.urbanairship+json; version=3
{
"ok" : true,
"operation_id" : "9ce808c8-7176-45dc-b79e-44aa74249a5a",
"template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161"
}Create a new template.
You should not edit a template in the dashboard that you created or updated via the API. The dashboard does not support all /api/template API options, causing you to lose information added via the API that is not supported by the dashboard.
Security:
Request Body
A single template object.
application/json
Type: 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.
Response
201 Created
The template was created.
Response Headers
Location
StringThe uri for the template, used for later updates or sends.
Format:
uri.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf
true, the operation completed successfully and returns an expected response.operation_id
StringOptionalA unique string identifying the operation, useful for reporting and troubleshooting.
Format:
uuid.template_id
StringOptionalA 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Push to Template
Example Request
POST /api/templates/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json
{
"device_types": [ "ios" ],
"audience": {
"ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
},
"merge_data": {
"template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"substitutions": {
"FIRST_NAME": "Bob",
"LAST_NAME": "Smith",
"TITLE": ""
}
}
}Example Response
HTTP/1.1 202 Accepted
Content-Length: 123
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true,
"operation_id" : "df6a6b50-9843-0304-d5a5-743f246a4946",
"push_ids": [
"1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6"
]
}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.
You must ensure that any variable with a null default value receives an override. For example, if you created a template with the variable FIRST_NAME, and that variable has null as a default value, you must provide a substitution for FIRST_NAME when pushing to that template.
Security:
Request Body
A single push template payload or an array of push template payloads.
application/json
Type: Any
- One of:
Type: 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.
Type: Array<Push Template Payload>
Response
202 Accepted
The push notification has been accepted for processing.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, the operation completed successfully and returns an expected response.
operation_id
StringOptionalA unique string identifying the operation, useful for reporting and troubleshooting.
Format:
uuid.push_ids
Array<String>OptionalAn array of the push IDs for this operation.
Max items: 100. Min items: 1.
Format:
uuid.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
406 Not Acceptable
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
Response Body
application/json
Type: 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
Example Request
POST /api/templates/push/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json
{
"device_types": [ "ios" ],
"audience": {
"ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
},
"merge_data": {
"template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"substitutions": {
"FIRST_NAME": "Bob",
"LAST_NAME": "Smith",
"TITLE": ""
}
}
}Example Response
HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true
}This endpoint accepts the same range of payloads as /api/template/push, but only parses and validates the payload. It does not actually send a push.
Security:
Request Body
A single push template payload or an array of push template payloads.
application/json
Type: Any
- One of:
Type: 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.
Type: Array<Push Template Payload>
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
406 Not Acceptable
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
Response Body
application/json
Type: 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
Example Request
POST /api/templates/schedules HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
[
{
"name": "Hello Bob",
"schedule": {
"scheduled_time": "2018-05-02T22:00:00Z"
},
"device_types": [ "ios" ],
"audience": {
"ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
},
"merge_data": {
"template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"substitutions": {
"FIRST_NAME": "Bob",
"LAST_NAME": "Takahashi",
"TITLE": null
}
}
},
{
"name": "Hello Joe",
"schedule": {
"scheduled_time": "2018-05-05T18:00:00Z"
},
"device_types": [ "android" ],
"audience": {
"android_channel": "df6a6b50-9843-0304-d5a5-743f246a4946"
},
"merge_data": {
"template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"substitutions": {
"FIRST_NAME": "Joe",
"LAST_NAME": "Smith",
"TITLE": "Sir"
}
}
}
]Example Response
HTTP/1.1 202 Accepted
Content-Length: 123
Data-Attribute: schedule_urls
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true,
"operation_id" : "efb18e92-9a60-6689-45c2-82fedab36399",
"schedule_urls" : [
"http://go.urbanairship/api/schedules/a0cef4f9-1fcd-47ef-b459-01f432b64043",
"http://go.urbanairship/api/schedules/fe2dab5e-f837-4707-8d0c-0e8c589ef4cf"
],
"schedule_ids" : [
"a0cef4f9-1fcd-47ef-b459-01f432b64043",
"fe2dab5e-f837-4707-8d0c-0e8c589ef4cf"
],
"schedules" : [
{
"url" : "http://go.urbanairship/api/schedules/a0cef4f9-1fcd-47ef-b459-01f432b64043",
"name": "Hello Joe",
"schedule" : { "..." },
"push" : { "..." },
"push_ids": [ "6a5ecb9c-46ee-4af4-9ced-9308121afaf9" ]
},
{
"url" : "http://go.urbanairship/api/schedules/fe2dab5e-f837-4707-8d0c-0e8c589ef4cf",
"name": "Hello Bob",
"schedule" : { "..." },
"push" : { "..." },
"push_ids": [ "5162bbf8-7de7-4040-a64d-e018b71f02f6" ]
}
]
}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
application/json
Type: Array<Object>
Type: Object
A scheduled push template object defines a push by overriding the variables defined in a specific Template Object and the
scheduledetermining 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.The audience for the template.
An object specifying custom campaign categories related to the notification.
device_types
Array<String>RequiredAn array containing one or more strings identifying targeted platforms. Accepted platforms are
ios,android,amazon,wns,web,sms,email, andopen::<open_platform_name>(using theopen_platform_namevalue of your open channel).Min items: 1.
Possible values:
android,amazon,ios,web,wns,sms,email,open::open_platform_name.merge_data
ObjectRequiredA template selector describing the template ID and variable substitutions to use with it.
substitutions
ObjectOptionalAn object containing overrides for your template's variables. The key-value pairs in this object are the value of the
keyitems defined in your template, and the values you want to substitute for thedefault_valueof those keys.template_id
StringRequiredSpecifies the template to override.
name
StringOptionalAn optional name for the scheduled push operation.
Determines when the push is sent.
Response
202 Accepted
The scheduled push has been accepted for processing.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
ok
BooleanOptionalSuccess.
operation_id
StringOptionalA 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>OptionalAn array of schedule IDs.
Max items: 100. Min items: 1.
Format:
uuid.schedule_urls
Array<String>OptionalAn array of schedule URLs. The URL for each schedule is the schedules endpoint, appended with the
schedule_idof the schedule.Max items: 100. Min items: 1.
Format:
uri. Pattern:^https.*:\/\/.+.An array of schedule objects.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
406 Not Acceptable
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
Response Body
application/json
Type: 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
Example Request
GET /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Data-Attribute: template
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true,
"template": {
"id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"created_at": "2015-08-17T11:10:02Z",
"modified_at": "2015-08-17T11:10:02Z",
"last_used": null,
"name": "Welcome Message",
"description": "Our welcome message",
"variables": [
{
"key": "TITLE",
"name": "Title",
"description": "e.g. Mr, Ms, Dr, etc.",
"default_value": ""
},
{
"key": "FIRST_NAME",
"name": "First Name",
"description": "Given name",
"default_value": null
},
{
"key": "LAST_NAME",
"name": "Last Name",
"description": "Family name",
"default_value": null
}
],
"push": {
"notification": {
"alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
}
}
}
}Fetch the current definition of a single template.
Security:
Request Parameters
id path
StringRequiredA required string ID of the template.
Response
200 OK
Returned on success, with the JSON representation of the template in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, the operation completed successfully and returns an expected response.
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.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Example Request
POST /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "Welcome Message",
"description": "Our welcome message",
"push": {
"notification": {
"alert": "Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!"
}
}
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}Update a template. The request body is a partially-defined template object, containing the field(s) you want to change and their updated values.
You should not edit a template in the dashboard that you created or updated via the API. The dashboard does not support all /api/template API options, causing you to lose information added via the API that is not supported by the dashboard.
Security:
Request Parameters
id path
StringRequiredA required string ID of the template.
Request Body
application/json
Type: Object
A partially-defined template object. Provide only variables and push items that you want to update.
description
StringOptionalThe description of the template.
name
StringRequiredThe name of the template.
A partial push object describing everything about a push notification, except for the
audienceanddevice_types(which are defined in the pushTemplatePayload object).An array of Variable Specifications.
Response
200 OK
Returned if the template has been succesfully updated.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, the operation completed successfully and returns an expected response.
operation_id
StringOptionalA 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Delete Template
Example Request
DELETE /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "a6394ff8-8a65-4494-ad06-677eb8b7ad6a"
}Delete a template. If the template is successfully deleted, the response does not include a body.
Security:
Request Parameters
id path
StringRequiredA required string ID of the template.
Response
200 OK
The template with given ID has been succesfully deleted.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, the operation completed successfully and returns an expected response.
operation_id
StringOptionalA 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.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Example Request
GET /api/regions/?limit=100&start=100 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Data-Attribute: regions
Link: <https://go.urbanairship.com/api/regions?limit=100&start=100>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3
{
"ok": true,
"next_page": "https://go.urbanairship.com/api/regions?limit=100&start=100",
"count": 100,
"regions": [
{
"region_id": "abe5deb3-01d0-436e-8c5d-94b6421a01e0",
"name": "My Favorite Place",
"created_at": "2016-06-09T12:34:56",
"updated_at": "2016-06-09T12:34:56",
"geofence": {
"type": "POLYGON",
"points": [
{
"latitude": 90.0,
"longitude": 120.0
},
{
"latitude": 45.0,
"longitude": 120.0
},
{
"latitude": 0.0,
"longitude": 0.0
}
]
},
"beacons": [
{
"name": "entryway",
"id": "VLSHZAOEXOFCMLDVTKFQ"
},
{
"name": "Exhibit A",
"id": "ZAQYMNOZKRFCRPYEUCZI"
}
],
"attributes": {
"store_name": "Tonali's Donuts"
},
"source_info": {
"source": "GIMBAL",
"region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
"vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
}
}
]
}Get a paginated list regions. The result is an array of Region Objects under the "regions" key.
Security:
Request Parameters
limit query
IntegerOptionalDetermines the number of results per page. Defaults to 100 with a maximum of 1000 regions per page. Setting a
limitgreater than 1000returns a 400 response.Max: 1000.
start query
IntegerOptionalA zero-based integer offset into the ordered list of regions, useful for addressing pages directly.
Response
200 OK
Returns OK for success.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
count
IntegerOptionalThe total number of regions returned.
next_page
StringOptionalThere 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
BooleanOptionalSuccess.
An array of Region Objects.
400 Bad Request
returned when
limitis greater than 1000.Response Body
application/vnd.urbanairship+json; version=3;
Type: 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.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Example Request
GET /api/regions/7d4d9a5c-eff5-40f2-b648-4352c166e878 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Data-Attribute: region
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"region": {
"region_id": "7dbd9a5c-eff5-40f2-b648-4352c1668878",
"created_at": "2016-08-24T23:15:22.900",
"updated_at": "2016-08-24T23:15:22.900",
"name": "Alberta Park",
"source_info": {
"source": "GIMBAL",
"region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
"vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
},
"geofence": {
"type": "CIRCLE",
"center": {
"latitude": 45.56447530000002,
"longitude": -122.64461097354126
},
"radius": 200
},
"attributes": {
"park_name": "alberta",
"type": "park"
}
}
}Get details for a specific region.
Security:
Request Parameters
region_id path
StringRequiredThe region you want to lookup.
Response
200 OK
Returns OK for success.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
ok
BooleanOptionalif true, indicates success.
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.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Example Request
POST /api/custom-events HTTP/1.1
Authorization: Bearer <token>
X-UA-Appkey: <application key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json
[
{
"occurred": "2016-05-02T02:31:22",
"user": {
"android_channel": "e393d28e-23b2-4a22-9ace-dc539a5b07a8"
},
"body": {
"name": "purchased",
"value": 120.49,
"transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a",
"interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
"interaction_type": "url",
"properties": {
"category": "mens shoes",
"id": "pid-11046546",
"description": "sky high",
"brand": "victory"
},
"session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
}
},
{
"occurred": "2016-06-09T05:20:12",
"user": {
"android_channel": "e393d28e-23b2-4a22-9ace-dc539a5b07a8"
},
"body": {
"name": "purchased",
"value": 100.00,
"transaction": "12536473-3e0f-46d7-930e-abc345261722",
"interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
"interaction_type": "url",
"properties": {
"category": "mens shoes",
"id": "pid-11312678",
"description": "low top",
"brand": "street"
},
"session_id": "22404b07-3f8f-4e42-a4ff-123231233122"
}
}
]Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
{
"ok": true,
"operation_id": "8c61c0c4-95b0-45a6-bc38-733f7fcb8979"
}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.
- Requests complete validation before returning a response.
- Requests are authenticated with a bearer token which can provide access to this resource alone, or to this resource and others.
- Requests are rate limited to 500 events per second per app.
- The
namevalue insidebodymust not contain any uppercase characters, or the event will be rejected with a 400 status code.
Security:
Request Parameters
X-UA-Appkey header
StringRequiredThe application key.
Request Body
An array of custom event objects.
application/json
Type: Array<Custom Event object>
Max items: 100. Min items: 1.
Response
200 OK
Returned on success.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalSuccess.
operation_id
StringOptionalA unique string identifying the API interaction. You can use the
operation_idin 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Channels
Channels are Airship’s unique identifiers for addressing applications on iOS, Android, Amazon, and web devices.
Channel Listing
Example Request
GET /api/channels HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"next_page": "https://go.urbanairship.com/api/channels?start=07AAFE44CD82C2F4E3FBAB8962A95B95F90A54857FB8532A155DE3510B481C13&limit=2",
"channels": [
{
"channel_id": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
"device_type": "ios",
"push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
"opt_in": true,
"installed": true,
"background": true,
"created": "2014-03-06T18:52:59",
"last_registration": "2014-10-07T21:28:35",
"named_user_id": "some_id_that_maps_to_your_systems",
"alias": "null",
"tags": [
"tag1",
"tag2"
],
"tag_groups": {
"tag_group_1": ["tag1", "tag2"],
"tag_group_2": ["tag1", "tag2"]
},
"ios": {
"badge": 2,
"quiettime": {
"start": "22:00",
"end": "8:00"
},
"tz": "America/Los_Angeles"
}
},
{
"channel_id": "bd36e8c7-5a73-47c0-9716-99fd3d4197d5",
"device_type": "ios",
"push_address": null,
"opt_in": false,
"installed": true,
"background": true,
"created": "2014-03-06T18:52:59",
"last_registration": "2014-10-07T21:28:35",
"named_user_id": "some_id_that_maps_to_your_systems",
"alias": "null",
"tags": [
"tag1",
"tag2"
],
"tag_groups": {
"tag_group_1": ["tag1", "tag2"],
"tag_group_2": ["tag1", "tag2"]
},
"ios": {
"badge": 0,
"quiettime": {
"start": null,
"end": null
},
"tz": null
}
}
]
}List all channels registered to this app key, along with associated data and metadata.
Security:
Response
200 OK
Returns OK for success with the JSON response.
Response Headers
Link
Stringprovides the URL to the current page of results. The query within the URL contains the
limit(the number of results on the page) andstart(the firstchannel_idin the result set) parameters.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
An array of Channel Objects.
next_page
StringOptionalIf there is more than one page of results, use this link to get the next page of results.
Format:
url.ok
BooleanOptionalSuccess.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Example Request
POST /api/channels/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881",
"android_channel": "13863b3c-f860-4bbf-a9f1-4d785379b8a2"
},
"add": {
"my_fav_tag_group1": ["tag1", "tag2", "tag3"],
"my_fav_tag_group2": ["tag1", "tag2", "tag3"],
"my_fav_tag_group3": ["tag1", "tag2", "tag3"]
}
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"warnings": ["The following tag groups do not exist: my_fav_tag_group2", "The following tag groups are deactivated: my_fav_tag_group3"]
}Add, remove, or set tags on a channel.
A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response.
While we support billions of channels, testing a channel by repeatedly updating its tags can cause latency and service interruptions.
We support up to 1000 tags per channel. Adding more than 1000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per channel, and they will help you find an alternative.
Security:
Request Body
application/json
Type: Object
A single request body may contain add and/or remove objects, or a single set object. At least one of the add, remove, or set objects must be present in a request.
Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
audience
ObjectRequiredSpecifies one or more channels that you want to apply tag operations to.
Removes the specified tags from the channel.
Assigns a list of tags exactly; any previously set tags that are not in this current list will be removed.
Response
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.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, your request was processed normally.
warnings
Array<String>OptionalReturned 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
Bad Request. Parsing or validating the request failed. You will get this error if a tag is present in both the add and remove fields.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Returned in cases when the app does not permit associations from the device. Secure tag groups require master secret to modify tags.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Uninstall Channels
Example Request
POST /api/channels/uninstall HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
[
{
"channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
"device_type": "ios"
},
{
"channel_id": "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
"device_type": "android"
}
]Example Response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"ok": true
}Uninstalls a channel, removing it and all accompanying analytic data (including Insight) 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.
Channel uninstallation, like channel creation, is an asynchronous operation, and may take some time to complete.
Security:
Request Body
application/json
Type: Array<Object>
Max items: 1000. Min items: 1.
Type: Object
specifies the channel ID and device type you want to uninstall.
channel_id
StringRequiredThe channel ID.
device_type
StringRequiredThe device type of the channel. Valid values are 'ios', 'amazon', 'android', 'web', 'open'.
Possible values:
ios,android,amazon,web,open.
Response
202 Accepted
The request has been accepted for processing.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Channel Lookup
Example Request
GET /api/channels/9c36e8c7-5a73-47c0-9716-99fd3d4197d5 HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"ok": true,
"channel": {
"channel_id": "01234567-890a-bcde-f012-3456789abc0",
"device_type": "ios",
"installed": true,
"opt_in": false,
"background": true,
"push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
"created": "2013-08-08T20:41:06",
"last_registration": "2014-05-01T18:00:27",
"named_user_id": "some_id_that_maps_to_your_systems",
"alias": null,
"tags": [
"tag1",
"tag2"
],
"tag_groups": {
"tag_group_1": ["tag1", "tag2"],
"tag_group_2": ["tag1", "tag2"]
},
"ios": {
"badge": 0,
"quiettime": {
"start": null,
"end": null
},
"tz": "America/Los_Angeles"
}
}
}Fetch an individual channel registered to the app key, along with associated data and metadata.
Tags added to a channel via the Named Users tag endpoint will not appear with a request to this endpoint. To view those tags, you must look up the Named User associated with the channel.
Security:
Request Parameters
channel_id path
StringRequiredThe channel you want to look up.
Response
200 OK
Tags added to a channel using
/named_users/tagsare not returned from this endpoint. To view those tags, you must lookup the named user associated with the channel.Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
A channel object.
ok
BooleanOptionalSuccess.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Example Request
POST /api/channels/open HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"channel": {
"type": "open",
"opt_in": true,
"address": "Number Four",
"tags": [
"toaster",
"caprica"
],
"timezone": "America/Los_Angeles",
"locale_country": "US",
"locale_language": "en",
"open": {
"open_platform_name": "cylon",
"identifiers": {
"model": "4"
}
}
}
}Example Response
HTTP/1.1 200 OK
Location: https://go.urbanairship.com/api/channels/df6a6b50-9843-0304-d5a5-743f246a4946
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}Create a new open channel, or update an existing open channel.
A 200 status will be returned if an existing channel was found for the specified open_platform_name and address. Otherwise a new channel will be created, also returning a 200 status.
The master secret is required to update an open channel, otherwise a 401 Unauthorized response is returned.
Security:
Request Body
An open channel object.
application/json
Type: Object
channel
ObjectRequiredProperties of the open channel object.
address
StringRequiredWhere notifications sent to this
channel_idwill be sent. Examples: email address, phone number. If missing, channel_id must be present. Theaddressis one-to-one with thechannel id. New addresses on existing channels will overwrite old associations.locale_country
StringOptionalThe two-letter country locale shortcode. Will set the
ua_locale_countrytag group to the specified value.locale_language
StringOptionalThe two-letter language locale shortcode. Will set the
ua_locale_languagetag group to the specified value.open
ObjectRequiredOpen channel-specific properties.
identifiers
ObjectOptionalOptional 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.
open_platform_name
StringRequiredThe name of the open platform to which you are registering this channel.
opt_in
BooleanRequiredIf false, no payloads will be delivered for the channel.
tags
Array<String>OptionalA 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.
Max length: 128. Min length: 1.
timezone
StringOptionalAn 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
StringRequiredRequired string. The only acceptable value for an open channel is
open.Possible values:
open.
Response
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.
Response Headers
Location
StringUsed for later API calls for this channel.
Format:
uri.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
channel_id
StringOptionalIdentifies the new open channel or the open channel you successfully updated.
Format:
uuid.ok
BooleanOptionalSuccess.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: 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
Example Request
POST /api/channels/open/tags HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"address": "Number Six",
"open_platform_name": "cylon"
},
"add": {
"my_fav_tag_group1": ["tag1", "tag2", "tag3"],
"my_fav_tag_group2": ["tag1", "tag2", "tag3"],
"my_fav_tag_group3": ["tag1", "tag2", "tag3"]
}
}Example Response
HTTP/1.1 200 Accepted
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"ok":true
}Manipulate a single open channel’s tags. Open channels are identified by address, not by thier channel_id.
A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response.
While we support billions of channels, testing a channel by repeatedly updating its tags can cause latency and service interruptions.
We support up to 1000 tags per channel. Adding more than 1000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per channel, and they will help you find an alternative.
Security:
Request Body
application/json
Type: Object
Add, remove, or set tags on a channel. A single request body may contain add and/or remove objects, or a single set field. At least one of the add, remove, or set objects must be present in a request.
Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
audience
ObjectRequiredThe request body containing an address and open_platform_name.
Removes the specified tags from the channel.
Assigns a list of tags exactly; any previously set tags that are not in this current list will be removed.
Response
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.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey will appear in the top-most object, outside the verbose response.400 Bad Request
Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Returned in cases when the app does not permit associations from the device. Secure tag groups require master secret to modify tags.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Uninstall Open Channels
Example Request
POST /api/channels/open/uninstall HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"address": "Number Four",
"open_platform_name": "cylon"
}Example Response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}Uninstall a channel needing to know its channel ID. You cannot send notifications to, or get channel information for, an uninstalled channel.
Security:
Request Body
An address and the open_platform_name you want to uninstall the address from.
application/json
Type: Object
The request body containing an address and open_platform_name.
address
StringRequiredWhere notifications sent to this
channel_idwill be sent. Examples: email address, phone number. If missing, channel_id must be present. Theaddressis one-to-one with thechannel id. New addresses on existing channels will overwrite old associations.open_platform_name
StringRequiredAn alphanumeric string that must be the name of a pre-created open platform object.
Max length: 128. Min length: 1.
Response
202 Accepted
The request has been accepted for processing.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Register email channels, set opt-in status, and manipulate tags on email channels.
Register Email Channel
Example Request
POST /api/channels/email HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"channel" : {
"type": "email",
"commercial_opted_in": "2018-10-28T10:34:22",
"address": "name@example.com",
"timezone" : "America/Los_Angeles",
"locale_country" : "US",
"locale_language" : "en"
}
}Example Response
HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/channels/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd
Content-Type: application/json
{
"ok": true,
"channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd"
}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:
Request Body
A single email channel object.
application/json
Type: Object
An email channel object is the object used to create or update channels.
There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal noticies, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out).
Each channel uses opted_in and opted_out keys for both commercial and transactional emails. The value of each key is the date-time when the user subscribed to or unsubscribed from emails of either type — commercial or transactional. If a user has opted out of a particular email type (or the user never opted into commercial emails), and the user is a part of your audience for a message of that type, the email designated for the opted-out user is dropped at delivery time. These values are all optional. However, an email channel with no opted_in or opted_out values can only receive transactional emails.
If a channel has both opt_in and opt_out values for a particular email type, Airship respects the most recent date-time. So, if a user opted into commercial emails after previously opting out, that user can receive commercial emails from you even though that user's channel possesses both commercial_opted_in and commercial_opted_out values; if the opt-in date is prior to the opt-out date, the user will not receive commercial emails from you.
channel
ObjectRequiredaddress
StringRequiredThe email address being registered.
commercial_opted_in
StringOptionalThe date-time when a user gave explicit permission to receive commercial emails.
Format:
date-time.commercial_opted_out
StringOptionalThe date-time when a user explicitly denied permission to receive commercial emails.
Format:
date-time.locale_country
StringOptionalThe device property tag related to locale country setting.
locale_language
StringOptionalThe device property tag related to locale language setting.
timezone
StringOptionalThe device property tag related to timezone setting.
transactional_opted_in
StringOptionalThe 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
StringOptionalThe date-time when a user explicitly denied permission to receive transactional emails.
Format:
date-time.type
StringRequiredThe type of channel you are registering. For email channels, this value must be
email.Possible values:
email.
Response
201 Created
The email channel was created.
Response Headers
Location
StringThe newly created email channel.
Format:
uri.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for an email channel request.
channel_id
StringOptionalA unique string identifying the email channel.
Format:
uuid.ok
BooleanOptionalEither
trueorfalse. 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Email Tags
Example Request
POST /api/channels/email/tags HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"email_address": "name@example.com"
},
"add": {
"my_fav_tag_group1": ["tag1", "tag2", "tag3"],
"my_fav_tag_group2": ["tag1", "tag2", "tag3"],
"my_fav_tag_group3": ["tag1", "tag2", "tag3"]
}
}Add, remove, or set tags for a single email channel.
A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response. While we support billions of channels, testing a channel by repeatedly updating its tags can cause latency and service interruptions. We support up to 1000 tags per channel. Adding more than 1000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per channel, and they will help you find an alternative.
Security:
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.
application/json
Type: Object
Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
audience
ObjectRequiredSpecifies the email address you want to perform tag operations against. Must contain a single
email_addresskey.Max properties: 1.
Removes the specified tags from the channel.
Assigns a list of tags exactly; any previously set tags that are not in this current list are removed.
Response
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.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey will appear in the top-most object, outside the verbose response.400 Bad Request
Bad Request. Parsing or validating the request failed. If a tag is present in both the add and remove fields, a HTTP 400 response will be returned.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the app does not permit associations from the device. Secure tag groups require master secret to modify tags, otherwise a 403 Forbidden response is returned.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Uninstall Email Channel
Example Request
POST /api/channels/email/uninstall HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
{
"email_address": "name@example.com"
}Example Response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}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, insight reports, or other information from the that belonged to the previously-uninstalled email channel.
Security:
Request Body
An email address of the channel to uninstall.
application/json
Type: Object
email_address
StringRequiredThe email address of the channel to uninstall.
Response
202 Accepted
The request has been accepted for processing.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Lookup an Email Address
Example Request
GET /api/channels/email/name%40domain.com HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/jsonExample Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"channel": {
"channel_id": "01234567-890a-bcde-f012-3456789abc0",
"device_type": "email",
"installed": true,
"created": "2013-08-08T20:41:06",
"named_user_id": "some_id_that_maps_to_your_systems",
"tag_groups": {
"tag_group_1": ["tag1", "tag2"],
"tag_group_2": ["tag1", "tag2"]
},
"address": null,
"opt_in": true,
"commercial_opted_in": "2018-10-28T10:34:22",
"commercial_opted_out": "2018-06-03T09:15:00",
"transactional_opted_in": "2018-10-28T10:34:22",
"last_registration": "2014-05-01T18:00:27"
}
}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:
Request Parameters
id path
StringRequiredThe email address of the channel you want to look up.
Response
200 OK
A channel exists for the email address
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Example Request - Update Email Address
PUT /api/channels/email/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"channel" : {
"type": "email",
"address": "new.name@new.domain.com"
}
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd"
}Update an email channel. You can use this endpoint to update the email address associated with a channel and subscription/unsubscription values.
Security:
Request Parameters
id path
StringRequiredThe
channel_idyou want to modify.
Request Body
application/json
Type: Object
An email channel object is the object used to create or update channels.
There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal noticies, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out).
Each channel uses opted_in and opted_out keys for both commercial and transactional emails. The value of each key is the date-time when the user subscribed to or unsubscribed from emails of either type — commercial or transactional. If a user has opted out of a particular email type (or the user never opted into commercial emails), and the user is a part of your audience for a message of that type, the email designated for the opted-out user is dropped at delivery time. These values are all optional. However, an email channel with no opted_in or opted_out values can only receive transactional emails.
If a channel has both opt_in and opt_out values for a particular email type, Airship respects the most recent date-time. So, if a user opted into commercial emails after previously opting out, that user can receive commercial emails from you even though that user's channel possesses both commercial_opted_in and commercial_opted_out values; if the opt-in date is prior to the opt-out date, the user will not receive commercial emails from you.
channel
ObjectRequiredaddress
StringRequiredThe email address being registered.
commercial_opted_in
StringOptionalThe date-time when a user gave explicit permission to receive commercial emails.
Format:
date-time.commercial_opted_out
StringOptionalThe date-time when a user explicitly denied permission to receive commercial emails.
Format:
date-time.locale_country
StringOptionalThe device property tag related to locale country setting.
locale_language
StringOptionalThe device property tag related to locale language setting.
timezone
StringOptionalThe device property tag related to timezone setting.
transactional_opted_in
StringOptionalThe 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
StringOptionalThe date-time when a user explicitly denied permission to receive transactional emails.
Format:
date-time.type
StringRequiredThe type of channel you are registering. For email channels, this value must be
email.Possible values:
email.
Response
200 OK
The email channel was updated.
Response Headers
Location
StringThe updated email channel.
Format:
uri.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for an email channel request.
channel_id
StringOptionalA unique string identifying the email channel.
Format:
uuid.ok
BooleanOptionalEither
trueorfalse. 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
SMS
Register and manage SMS channels. See SMS Platform Information to get started with SMS notifications.
Register SMS Channel
Example Request
POST /api/channels/sms HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
{
"msisdn" : "15035556789",
"sender": "12345",
"opted_in": "2018-02-13T11:58:59"
}Example Response (With 'opted_in')
HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/channels/7c5d7328-9bb4-4ff7-86b0-96a5f1da5868
Content-Type: application/json
{
"ok": true,
"channel_id": "7c5d7328-9bb4-4ff7-86b0-96a5f1da5868"
}Example Response (Without 'opted_in')
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"ok": true,
"status": "pending"
}Example Response (Project not configured with sender)
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"ok": false,
"errors": "Unable to retrieve details for sender 12345 with app_key <application key>"
}Begin the opt-in process for a new SMS channel.
SMS notifications require a sender - a number that recipients will recieve SMS notifications from.
Contact Airship Support or your Account Manager to provision your project for SMS notifications
and complete the configuration.
The opted_in key represents the time when explicit permission was received from the user to
receive messages. If the opted_in value is populated and with a valid date-time in the past, a channel
is created immediately. If this field is not present, a channel is not created, and a message will be
sent to the msisdn with instructions on how to opt in and receive messages.
Avoid repeated registration attempts. Repeated registrations of the same msisdn and sender without an opted_in value will result in multiple opt-in instruction messages being sent to the msisdn.
Request Body
application/json
Type: Object
msisdn
StringRequiredThe 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
StringOptionalThe 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
StringRequiredA number the app is configured to send from, provided by Airship. Must be numeric characters only.
Response
201 Created
The channel was created.
Response Headers
location
StringURI of the channel, used for later registrations. Only included when opted_in is set.
Format:
url.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
channel_id
StringOptionalUnique Channel ID for the SMS channel. Included when the request contains a valid
opted_invalue.Format:
uuid.ok
BooleanOptionalIf true, the request was successful. A successful request will not result in a created channel if the request does not include an
opted_indate-time.
202 Accepted
A successful request will not result in a created channel if the request did not include an
opted_indate-time.Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, the request was successful.
status
StringOptionalA response with a status key indicates that the channel has not been created. If the value is pending, the
opted_infield was not provided in the request, and the channel will be created pending the user’s affirmative response.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.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
errors
StringOptionalReturned with 40x responses; explains reason for the unsuccessful request.
ok
BooleanOptionalIf false, the request was unsuccessful.
Opt-out of SMS messages
Example Request
POST /api/channels/sms/opt-out HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
{
"sender": "12345",
"msisdn": "15035556789"
}Example Response
HTTP/1.1 202 Accepted
Content-type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}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.
Request Body
application/json
Type: Object
msisdn
StringRequiredThe 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
StringRequiredThe SMS sender ID provided by Airship. Must be numeric characters only.
Response
202 Accepted
The msisdn/channel is opted-out of SMS notifications.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, the operation completed successfully.
400 Bad Request
The request body is not valid.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
details
ObjectOptionalerror
StringOptionalSpecific error message that explains why the request was unsuccessful.
error
StringOptionalReturned with 40x responses; explains why the request was unsuccessful.
error_code
IntegerOptionalThe 5-digit Airship error code, pointing to a more specific error than the HTTP Status.
ok
BooleanOptionalIf false, the request was unsuccessful.
Uninstall SMS Channel
Example Request
POST /api/channels/sms/uninstall HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
{
"sender": "12345",
"msisdn": "15035551212"
}Example Response
HTTP/1.1 202 Accepted
Content-type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}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, insight reports, or other information from the uninstalled SMS channel.
Request Body
application/json
Type: Object
msisdn
StringRequiredThe 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
StringRequiredA number the app is configured to send from, provided by Airship. Must be numeric characters only.
Response
202 Accepted
The SMS channel and all information associated with the msisdn is uninstalled.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, the operation was successful.
400 Bad Request
The request body is not valid.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
details
ObjectOptionalerror
StringOptionalSpecific error message that explains why the request was unsuccessful.
error
StringOptionalReturned with 40x responses; explains why the request was unsuccessful.
error_code
IntegerOptionalThe 5-digit Airship error code, pointing to a more specific error than the HTTP Status.
ok
BooleanOptionalIf false, the request was unsuccessful.
SMS Channel Lookup
Example Request
GET /api/channels/sms/15035551212/55555 HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Data-Attribute: channel
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"channel": {
"channel_id": "84e36d69-873b-4ffe-81cd-e74c9f002057",
"device_type": "sms",
"installed": true,
"push_address": null,
"named_user_id": null,
"alias": null,
"tags": [],
"tag_groups": {
"ua_channel_type": [
"sms"
],
"ua_sender_id": [
"12345"
],
"ua_opt_in": [
"true"
]
},
"created": "2018-04-27T22:06:21",
"opt_in": true,
"last_registration": "2018-05-14T19:51:38"
}
}}Lookup an SMS channel by msisdn and sender.
Request Parameters
msisdn path
IntegerRequiredThe 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 path
IntegerRequiredA number the app is configured to send from, provided by Airship. Must be numeric characters only.
Response
200 ok
Returns an SMS channel object. An SMS channel object includes tag groups for
ua_channel_type,ua_sender_id, andua_opt_in.Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
Describes a channel.
ok
BooleanOptionalSuccess.
404 Not Found
A
channel_iddoes not exist for themsisdnandsender.Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
error
StringOptionalReturned with 40x responses; explains why the request was unsuccessful.
error_code
IntegerOptionalThe 5-digit Airship error code, pointing to a more specific error than the HTTP Status.
ok
BooleanOptionalIf false, the request was unsuccessful.
Custom SMS Response
Example Request
POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <bearer token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
{
"sms" : {
"alert": "Your balance is $1234.56"
},
"mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "f3d0993e-e3e1-4aae-b1c0-864a715bfaff",
"push_id": "7502abe6-e6ea-4f2b-906f-ebbab612c69e"
}Respond to a mobile originated message based on a keyword consumed by your custom-response webhook, using a mobile-originated ID. See
This endpoint requires a bearer authorization.
Security:
Request Parameters
X-UA-Appkey header
StringRequiredThe application key.
Request Body
application/json
Type: Object
mobile_originated_id
StringRequiredThe 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_idis valid for 10 minutes from thereceived_timestampin the payload sent to your webhook server's/inbound-smsendpoint.Format:
uuid.sms
ObjectRequiredalert
StringRequiredYour custom SMS message.
Response
200 OK
The operation was successful.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf
true, your request was successful.operation_id
StringOptionalA unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
Format:
uuid.push_id
StringOptionalA unique identifier for a push operation.
Format:
uuid.
404 Not Found
The mobile_originated_id could not be found.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
error
StringOptionalA plain-text explanation of the error.
ok
BooleanOptionalIf false, your request was unsuccessful.
operation_id
StringOptionalA 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
Example Request
GET /api/named_users/?id=(named_user_id) HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response with
idquery (named user lookup)
{
"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"
}
}
]
}
}Example Response without
idquery (list named users)
HTTP/1.1 200 OK
Data-Attribute: named_users
Link: <https://go.urbanairship.com/api/named_users?start=user-1234>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3;
{
"next_page": "https://go.urbanairship.com/api/named_users?start=user-1234",
"named_users": [
{
"named_user_id": "user-id-1234",
"tags": {
"crm": ["tag1", "tag2"]
},
"channels": [
{
"channel_id": "ABCD",
"device_type": "ios",
"installed": true,
"opt_in": true,
"push_address": "FFFF",
"created": "2013-08-08T20:41:06",
"last_registration": "2014-05-01T18:00:27",
"alias": "xxxx",
"tags": ["asdf"],
"ios": {
"badge": 0,
"quiettime": {
"start": "22:00",
"end": "06:00"
},
"tz": "America/Los_Angeles"
}
}
]
}
]
}Return a list of named users or lookup a single named user by named_user_id.
Security:
Request Parameters
id query
StringOptionalThe
named_user_idyou want to look up. When querying anamed_user_id, the response contains a singlenamed_userobject. If you do not query a specificnamed_user_id, the response returns an array ofnamed_users, in which each object represents an individual named user.
Response
200 OK
Returns OK for success.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
- One of:
Type: Any
Response for a single
named_user_idquery.The response body for named user lookup, including tags and channels associated with the named user.
ok
BooleanOptionalSuccess.
Type: Any
Response returned when performing this operation without a query.
next_page
StringOptionalThere 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
BooleanOptionalSuccess.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: 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
Example Request - associate an iOS channel with a named user
POST /api/named_users/associate HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
"device_type": "ios",
"named_user_id": "user-id-1234"
}Example Request - associate a web channel with named user (do not declare device type)
POST /api/named_users/associate HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"channel_id": "wf6a6b50-9843-0304-d5a5-743f246a4946",
"named_user_id": "user-id-1234"
}Example request — associate an email channel with named user
POST /api/named_users/associate HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"email_address": "monopoly.man@boardwalk.com",
"named_user_id": "user-id-1234"
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}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.
If a channel has an assigned named user and you make an additional call to associate that same channel with a new named user, the original named user association will be removed and the new named user and associated data will take its place. Additionally, all tags associated to the original named user cannot be used to address this channel unless they are also associated with the new named user.
Security:
Request Body
Named user association requires a channel_id or email_address. Do not provide both in the same request.
application/json
Type: Any
- One of:
Type: Object
channel_id
StringRequiredThe channel ID you want to associate with a named user.
Format:
uuid.device_type
StringOptionalThe device type of the channel, e.g.,
ios,android,amazon. Do not specifydevice_typefor web, email, sms, or open channels.Possible values:
ios,android,amazon.named_user_id
StringRequiredA 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_idwith it.Pattern:
^[^\s].{1,125}\S$. Max length: 128. Min length: 1.
Type: Object
email_address
StringRequiredThe email address you want to associate with a named user.
Format:
email.named_user_id
StringRequiredA 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_idwith it.Pattern:
^[^\s].{1,125}\S$. Max length: 128. Min length: 1.
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: 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
Example Request
POST /api/named_users/disassociate HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
"device_type": "ios",
"named_user_id": "user-id-1234"
}Example request — disassociate an email channel from named user
POST /api/named_users/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@gotojail.com",
"named_user_id": "user-id-1234"
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}Disassociate a channel or an email address from a named_user_id.
Security:
Request Body
application/json
Type: Object
channel_id
StringOptionalThe channel or email address you want to disassociate from the
named_user_id. The schema should include one ofemail_addressorchannel_id, but not both.Format:
uuid.email_address
StringOptionalThe email address you want to disassociate from the
named_user_id.Format:
email.named_user_id
StringOptionalThe named user that you want to remove the channel from.
Pattern:
^[^\s].{1,125}\S$. Max length: 128. Min length: 1.
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: 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 Tags
Example Request
POST /api/named_users/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"named_user_id": ["user-1", "user-2", "user-3"]
},
"add": {
"crm": ["tag1", "tag2", "tag3"],
"loyalty": ["tag1", "tag4", "tag5"]
},
"remove": {
"loyalty": ["tag6", "tag7"]
}
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}Add, remove, or set tags on a named user. A single request body may contain add and/or remove objects, or a single set field. At least one of the add, remove, or set objects must be present in a request.
A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response.
While we support billions of named users, testing a named user by repeatedly updating its tags can cause latency and service interruptions.
We support up to 1000 tags per named user. Adding more than 1000 tags per named user can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per named user, and they will help you find an alternative.
Security:
Request Body
application/json
Type: Object
Add the list of tags to the named user(s), but do not remove any. If the tags are already present, they are not modified.
audience
ObjectRequiredThe named user(s) you want to associate/disassociate tags with.
Remove the list of tags from the named user(s), but do not remove any others. If the tags are not currently present, nothing happens.
Set these tags for the audience; any tags previously associated with the audience tags that are not in this current list are removed.
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey will appear in the top-most object, outside the verbose response.400 Bad Request
Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 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.
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.
Response Body
application/json
Type: 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 Uninstall
Example Request - deletes all users and their associated channels
POST /api/named_users/uninstall HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"named_user_id": ["user-id-1234","user-id-5678"]
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}Disassociate and delete all channels associated with the named_user_id(s) and also delete the named_user_id(s). This call removes all channels associated with a named user from Airship systems in compliance with GDPR.
Uninstalling channels also removes accompanying analytic data (including Insight) from the system.
See Data Subject Rights Support Under GDPR for more information about GDPR compliance.
Channel uninstallation, like channel creation, is an asynchronous operation, and may take some time to complete.
Security:
Request Body
application/json
Type: Object
named_user_id
Array<String>RequiredArray of strings representing the named_userid(s) you wish to be uninstalled. Must have between 1 to 100 items in the array with a 128 character/byte maximum per item.
Max items: 100. Min items: 1.
Pattern:
^[^\s].{1,125}\S$. Max length: 128. Min length: 1. All items must be unique.
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Tags
Operations to assign or unassign tags for Channels and Named Users. Tags belong to tag groups and can help you organize channels using identifiers relevant to your operations. See the Tag Groups Tutorial for information about, and strategies for using, tag groups.
If you previously used the /api/tags endpoint to set tags, it is strongly recommended that you transition to the endpoints and methods specified in this document.
Email Tags
Example Request
POST /api/channels/email/tags HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"email_address": "name@example.com"
},
"add": {
"my_fav_tag_group1": ["tag1", "tag2", "tag3"],
"my_fav_tag_group2": ["tag1", "tag2", "tag3"],
"my_fav_tag_group3": ["tag1", "tag2", "tag3"]
}
}Add, remove, or set tags for a single email channel.
A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response. While we support billions of channels, testing a channel by repeatedly updating its tags can cause latency and service interruptions. We support up to 1000 tags per channel. Adding more than 1000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per channel, and they will help you find an alternative.
Security:
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.
application/json
Type: Object
Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
audience
ObjectRequiredSpecifies the email address you want to perform tag operations against. Must contain a single
email_addresskey.Max properties: 1.
Removes the specified tags from the channel.
Assigns a list of tags exactly; any previously set tags that are not in this current list are removed.
Response
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.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey will appear in the top-most object, outside the verbose response.400 Bad Request
Bad Request. Parsing or validating the request failed. If a tag is present in both the add and remove fields, a HTTP 400 response will be returned.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the app does not permit associations from the device. Secure tag groups require master secret to modify tags, otherwise a 403 Forbidden response is returned.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Open Channel Tags
Example Request
POST /api/channels/open/tags HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"address": "Number Six",
"open_platform_name": "cylon"
},
"add": {
"my_fav_tag_group1": ["tag1", "tag2", "tag3"],
"my_fav_tag_group2": ["tag1", "tag2", "tag3"],
"my_fav_tag_group3": ["tag1", "tag2", "tag3"]
}
}Example Response
HTTP/1.1 200 Accepted
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"ok":true
}Manipulate a single open channel’s tags. Open channels are identified by address, not by thier channel_id.
A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response.
While we support billions of channels, testing a channel by repeatedly updating its tags can cause latency and service interruptions.
We support up to 1000 tags per channel. Adding more than 1000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per channel, and they will help you find an alternative.
Security:
Request Body
application/json
Type: Object
Add, remove, or set tags on a channel. A single request body may contain add and/or remove objects, or a single set field. At least one of the add, remove, or set objects must be present in a request.
Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
audience
ObjectRequiredThe request body containing an address and open_platform_name.
Removes the specified tags from the channel.
Assigns a list of tags exactly; any previously set tags that are not in this current list will be removed.
Response
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.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey will appear in the top-most object, outside the verbose response.400 Bad Request
Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Returned in cases when the app does not permit associations from the device. Secure tag groups require master secret to modify tags.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Channel Tags
Example Request
POST /api/channels/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881",
"android_channel": "13863b3c-f860-4bbf-a9f1-4d785379b8a2"
},
"add": {
"my_fav_tag_group1": ["tag1", "tag2", "tag3"],
"my_fav_tag_group2": ["tag1", "tag2", "tag3"],
"my_fav_tag_group3": ["tag1", "tag2", "tag3"]
}
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"warnings": ["The following tag groups do not exist: my_fav_tag_group2", "The following tag groups are deactivated: my_fav_tag_group3"]
}Add, remove, or set tags on a channel.
A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response.
While we support billions of channels, testing a channel by repeatedly updating its tags can cause latency and service interruptions.
We support up to 1000 tags per channel. Adding more than 1000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per channel, and they will help you find an alternative.
Security:
Request Body
application/json
Type: Object
A single request body may contain add and/or remove objects, or a single set object. At least one of the add, remove, or set objects must be present in a request.
Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
audience
ObjectRequiredSpecifies one or more channels that you want to apply tag operations to.
Removes the specified tags from the channel.
Assigns a list of tags exactly; any previously set tags that are not in this current list will be removed.
Response
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.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, your request was processed normally.
warnings
Array<String>OptionalReturned 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
Bad Request. Parsing or validating the request failed. You will get this error if a tag is present in both the add and remove fields.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Returned in cases when the app does not permit associations from the device. Secure tag groups require master secret to modify tags.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Named Users Tags
Example Request
POST /api/named_users/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"named_user_id": ["user-1", "user-2", "user-3"]
},
"add": {
"crm": ["tag1", "tag2", "tag3"],
"loyalty": ["tag1", "tag4", "tag5"]
},
"remove": {
"loyalty": ["tag6", "tag7"]
}
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}Add, remove, or set tags on a named user. A single request body may contain add and/or remove objects, or a single set field. At least one of the add, remove, or set objects must be present in a request.
A tag must be < 128 characers. A request with one or more tags longer than 128 characters will return a 400 response.
While we support billions of named users, testing a named user by repeatedly updating its tags can cause latency and service interruptions.
We support up to 1000 tags per named user. Adding more than 1000 tags per named user can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using Custom Events when appropriate. Please contact Support if you believe your use case requires more than 1000 tags per named user, and they will help you find an alternative.
Security:
Request Body
application/json
Type: Object
Add the list of tags to the named user(s), but do not remove any. If the tags are already present, they are not modified.
audience
ObjectRequiredThe named user(s) you want to associate/disassociate tags with.
Remove the list of tags from the named user(s), but do not remove any others. If the tags are not currently present, nothing happens.
Set these tags for the audience; any tags previously associated with the audience tags that are not in this current list are removed.
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey will appear in the top-most object, outside the verbose response.400 Bad Request
Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 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.
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.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Segments
Segments are portions of your audience that have arbitrary metadata (e.g. tags, location data, etc) attached. You can create, delete, update, or request information on a segment via the /api/segments/ endpoint. Pushing to a segment is done through the /api/push/ endpoint (see the Audience Selection section for more information).
Segment Listing
Example Request
GET /api/segments/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Link: <https://go.urbanairship.com/api/segments?limit=1&sort=id&order=asc&start=3832cf72-cb44-4132-a11f-eafb41b82f64>;rel=next
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"next_page": "https://go.urbanairship.com/api/segments?limit=1&sort=id&order=asc&start=3832cf72-cb44-4132-a11f-eafb41b82f64",
"segments": [
{
"creation_date": 1346248822221,
"display_name": "A segment",
"id": "00c0d899-a595-4c66-9071-bc59374bbe6b",
"modification_date": 1346248822221
}
]
}List all segments for the application.
Security:
Response
200 OK
Returned on success a JSON object containing segments.
Response Headers
Link
StringA link to the next page of results. If present, follow this URL to the next page of segments. Also available in the
next_pagevalue in the response body.Format:
uri.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
next_page
StringOptionalAn optional relative URL which can be used to retrieve the next page of results. If no more results are available, next_page will be absent.
segments
Array<Object>RequiredAn array of segments for the application.
creation_date
IntegerRequiredThe original creation date of segment in epoch milliseconds.
display_name
StringRequiredThe segment display name.
id
StringRequiredA unique identifier for the segment.
Format:
uuid.modification_date
IntegerRequiredLatest modification date of the segment in epoch milliseconds.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
Create Segment
Example Request
POST /api/segments HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"display_name": "News but not sports",
"criteria": {
"and": [
{"tag": "news"},
{"not":
{"tag": "sports"}
}
]
}
}Example Response
HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/segments/f35da41d-59c1-4106-a192-9594bd480cb6
Content-Type: application/vnd.urbanairship+json;version=3
{
"ok": true,
"segment_id": "f35da41d-59c1-4106-a192-9594bd480cb6",
"operation_id": "1d154121-951f-45b9-896d-e70718b5865b"
}Create a new segment.
Security:
Request Body
A single segment object.
application/json
Type: Object
A set of audience selection criteria that you can reuse as a segment.
criteria
ObjectRequiredDefines the set of devices to send notifications to.
criteriais a JSON expression containing the same information as the audience selector with the limitation that the only atomic selectors supported aretag,location, andstatic_list. See Audience Selection for more information.- One of:
Type: Compound Selector
Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.
Type: Atomic Selector
Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a channel ID or metadata that maps to the device (or multiple devices) such as a tag.
display_name
StringRequiredHuman readable name for this segment. This will be used in the dashboard.
Response
201 Created
The segment was created.
Response Headers
Location
StringThe newly created segment.
Format:
uri.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
ok
BooleanOptionalIf true, the operation completed successfully and returns expected results.
operation_id
StringOptionalA unique string identifying an API call, and can be used to identify operations in reporting and troubleshooting logs.
Format:
uuid.segment_id
StringOptionalThe ID of the newly created segment.
Format:
uuid.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Segment Lookup
Example Request
GET /api/regions/?limit=100&start=100 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"criteria": {
"and": [
{
"tag": "ipad"
},
{
"not": {
"tag": "foo"
}
}
]
},
"display_name": "A segment"
}Lookup a segment.
Security:
Request Parameters
segment_id path
StringRequiredThe segment you want to retrieve.
Response
200 OK
Returns OK for success.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
A set of audience selection criteria that you can reuse as a
segment.criteria
ObjectRequiredDefines the set of devices to send notifications to.
criteriais a JSON expression containing the same information as the audience selector with the limitation that the only atomic selectors supported aretag,location, andstatic_list. See Audience Selection for more information.- One of:
Type: Compound Selector
Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.
Type: Atomic Selector
Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a channel ID or metadata that maps to the device (or multiple devices) such as a tag.
display_name
StringRequiredHuman readable name for this segment. This will be used in the dashboard.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Update Segment
Example Request
PUT /api/segments/00c0d899-a595-4c66-9071-bc59374bbe6b HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"display_name": "Entertainment but not sports",
"criteria": {
"and": [
{"tag": "news"},
{"not":
{"tag": "entertainment"}
}
]
}
}Example Response
HTTP/1.1 200 OK
Content-Length: 65
Content-Type: application/vnd.urbanairship+json;version=3
{
"ok": true,
"operation_id": "1f93ca85-b8fd-4833-8d1a-6e2b7f4ceea9"
}Change the definition of the segment.
When editing a segment, be mindful of any scheduled pushes that target that segment. If you have a scheduled push that targets a segment, and you edit that segment some time after the push's creation, the push audience will not be updated to match the new segment. The scheduled push will be sent to the version of the segment that existed when the push was created, rather than the updated version.
Security:
Request Parameters
segment_id path
StringRequiredThe segment you want to retrieve.
Request Body
A single segment object.
application/json
Type: Object
A set of audience selection criteria that you can reuse as a segment.
criteria
ObjectRequiredDefines the set of devices to send notifications to.
criteriais a JSON expression containing the same information as the audience selector with the limitation that the only atomic selectors supported aretag,location, andstatic_list. See Audience Selection for more information.- One of:
Type: Compound Selector
Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors.
Type: Atomic Selector
Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a channel ID or metadata that maps to the device (or multiple devices) such as a tag.
display_name
StringRequiredHuman readable name for this segment. This will be used in the dashboard.
Response
200 OK
Returned if the segment has been succesfully updated.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Delete Segment
Example Request
DELETE /api/segments/00c0d899-a595-4c66-9071-bc59374bbe6b HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 204 No ContentRemove the segment.
Security:
Request Parameters
segment_id path
StringRequiredThe segment you want to retrieve.
Response
204 No Content
The delete operation was successful.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 204
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.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Segment Locations
You can configure segments based on user location and location history. The following endpoints return location information to help you determine the locations and time frames for location-based segments.
Location Lookup
Example Request for Location by Name
GET /api/location/?q=San%20Francisco&type=city HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"features": [
{
"bounds": [
37.758749999999999,
-122.477411,
37.778851000000003,
-122.428426
],
"centroid": [
37.769751999999997,
-122.448239
],
"id": "191QgPcnG1Um9MW06h1fa6",
"properties": {
"aliases": {
"us_zip": "94117"
},
"boundary_type": "postalcode",
"boundary_type_string": "Postal/ZIP Code",
"name": "94117",
"source": "tiger.census.gov"
},
"type": "Feature"
}
]
}Search for a location boundary by name and type. See Boundary Types and Aliases Catalog for a list of available types. Because there are over 2.5M location boundaries available in Segments, we recommend you provide a type parameter along with your search to increase the chance you find the polygon you're looking for. If you are not getting satisfactory results with searching for a location by name, you may want to consider searching for Locations by coordinates or bounding box.
Due to contractual obligations we do not return proprietary datasets such as Maponics Neighborhood Boundaries or Nielsen DMA© in this endpoint. You can, however, search for those locations using the web interface.
Request Parameters
q query
StringOptionalThe name of the boundary you want to search for. Use in conjunction with the
typequery.type query
StringOptionalThe type of boundary you want to search for. Use in conjunction with the
qquery string.
Response
200
Success
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
Contains an array of location results.
Find Location by Alias
Example Request for Location by Alias
GET /api/location/from-alias?us_state=CA&us_state=OR&us_state=WA HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response for Location by Alias with 1 Result
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"bounds": [
32.528832,
-124.482003,
42.009517,
-114.131211
],
"centroid": [
37.215297,
-119.663837
],
"id": "5LajTWicgiQKuX1RBBLDRI",
"properties": {
"abbr": "CA",
"aliases": {
"fips_10-4": "US06",
"hasc": "US.CA",
"state": "US06",
"us_state": "CA"
},
"boundary_type": "province",
"boundary_type_string": "State/Province",
"name": "California",
"source": "tiger.census.gov"
},
"type": "Feature"
}Find locations using any of the keys appearing in the alias object. See the Boundary Types and Aliases Catalog for a list of supported aliases.
Request Parameters
from-alias query
ObjectOptionalSearch using any of the keys supported by the
aliasesobject.
Response
200 OK
Success
Response Body
application/json
Type: Any
- One of:
Type: Object
If your query returns multiple results, they are contained in the
featuresarray.Type: Location Object
If your query returns a single result, the
featuresarray is absent.
Location by Coordinates
Example Request
GET /api/location/37.7749295,-122.4194155?type=city HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"features": [
{
"bounds": [
37.63983,
-123.173825,
37.929824,
-122.28178
],
"centroid": [
37.759715,
-122.693976
],
"id": "4oFkxX7RcUdirjtaenEQIV",
"properties": {
"boundary_type": "city",
"boundary_type_string": "City/Place",
"context": {
"us_state": "CA",
"us_state_name": "California"
},
"name": "San Francisco",
"source": "tiger.census.gov"
},
"type": "Feature"
}
]
}Find a location using coordinates. Airship will search for a location containing the coordinates you provide.
Request Parameters
latitude_1 path
NumberRequiredLatitude to search for.
longitude_1 path
NumberRequiredLongitude to search for.
type query
StringOptionalThe type of location you want to return.
Response
200
Success
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
Location by Coordinates or bounding box
Example Request
GET /api/location/37.805172690644405,-122.44863510131836,37.77654930110633,-122.39404678344727?type=postalcode HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"features": [
{
"bounds": [
37.758749999999999,
-122.477411,
37.778851000000003,
-122.428426
],
"centroid": [
37.769751999999997,
-122.448239
],
"id": "191QgPcnG1Um9MW06h1fa6",
"properties": {
"aliases": {
"us_zip": "94117"
},
"boundary_type": "postalcode",
"boundary_type_string": "Postal/ZIP Code",
"name": "94117",
"source": "tiger.census.gov"
},
"type": "Feature"
}
]
}Find locations within a bounding box. Provide two sets of coordinates representing opposing corners of a rectangular search area, and this endpoint will return locations that are at least partially contained within the bounding box. Use the type query to find specific types of locations within the bounding box.
Request Parameters
latitude_1 path
NumberRequiredLatitude to search for the first corner of the bounding box.
longitude_1 path
NumberRequiredLongitude for the first corner of the bounding box.
latitude_2 path
NumberRequiredLatitude for the opposing corner of the bounding box.
longitude_2 path
NumberRequiredLongitude for the oposing corner of the bounding box.
type query
StringRequiredThe type of location you want to search for inside the boundary
Response
200
Success
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
Location Polygon Lookup
Example Request
GET /api/location/1H4pYjuEW0xuBurl3aaFZS?zoom=1 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"type": "Feature",
"id": "1H4pYjuEW0xuBurl3aaFZS",
"properties": {
"source": "tiger.census.gov",
"boundary_type_string": "City/Place",
"name": "Portland",
"context": {
"us_state_name": "Oregon",
"us_state": "OR"
},
"boundary_type": "city"
},
"bounds": [
45.432393,
-122.83675,
45.653272,
-122.472021
],
"centroid": [
45.537179,
-122.650037
],
"geometry": {
"coordinates": [
[
[
[
-122.586136,
45.462439
],
[
"..."
]
]
]
],
"type": "MultiPolygon"
}
}Lookup a polygonal location by ID. The response including the coordinates defining the geometric shape of the location in the geometry object.
Request Parameters
polygon_id path
StringRequiredThe ID of the polygon you want to return.
zoom query
IntegerOptionalDetermines the level of detail of the coordinates returned. The higher the zoom, the more detailed the polygon in the response (reflected by more coordinates defining the shape of the polygon in the
geometryobject).Max: 20. Min: 1.
Response
200
Success
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
bounds
Array<Number>OptionalThe latitudinal and longitudinal coordinate values representing the boundaries of the search or location.
centroid
Array<Number>OptionalThe latitude and longitude representing the center point of the location.
geometry
ObjectOptionalContains the coordinates defining the geometric shape of a location.
coordinates
Array<Array<Array<Array<Number>>>>OptionalContains the coordinates for all the points in the geometric shape using arrays of arrays to represent the sides of the shape. Arrays containing coordinates contain latitudinal, lognitudinal pairs.
type
StringOptionalGeometric type, typically
MultiPolygon.Possible values:
MultiPolygon.
id
StringOptionalA unique identifier for the location.
properties
ObjectOptionalabbr
StringOptionalAn abbreviation for the location, if applicable.
aliases
ObjectOptionalAliases for the location name.
boundary_type
StringOptionalThe type of geographical location -- city, province, etc.
boundary_type_string
StringOptionalA normalized type of geographical location -- State/Province, etc.
context
ObjectOptionalContains key-value pairs to help identify the location, frequently including parents of the location. For example, if the location is a city in the US,
contextmight listus_stateand other keys.name
StringOptionalThe common name for the location, if applicable.
source
StringOptionalThe source defining the location.
type
StringOptionalThe location type. May be "Feature" as in the coordinates are drawn outside the service, or
MultiPolygon, representing a location drawn by a user through the Airship Segments Builder.
Location Date Ranges
Example Request
GET /api/segments/dates/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
[
{
"unit": "hours",
"cutoff": "2018-08-07 18"
},
{
"unit": "days",
"cutoff": "2018-06-10"
},
{
"unit": "weeks",
"cutoff": "2018-W22"
},
{
"unit": "months",
"cutoff": "2014-08"
},
{
"unit": "years",
"cutoff": "2008"
}
]Retrieve cutoff dates for each time granularity. When creating segments, you can identify location events that happened in the past with maximum values changing based on the unit of time. For example, you can search back up to 10 years using yearly granularity, but only up to 4 years using monthly granularity. This endpoint lists the cutoff dates and times (where applicable) for different units of time. You can create location segments using the following units of time, going back:
- 48 hours ago * 60 days ago * 10 weeks ago * 48 months ago * 10 years ago
Response
200
Success
Response Body
application/vnd.urbanairship+json; version=3;
Type: Array<Object>
Type: Object
cutoff
StringOptionalThe farthest date/time in the past you can use when creating segments based on location using the specified granularity. Hours are represented from 0-23, weeks as
w0-w51.unit
StringOptionalPossible values:
hours,days,weeks,months,years.
Static Lists
With the Static List API endpoint, you can easily target and manage lists of devices that are defined in your systems outside of Airship. Any list or grouping of devices for which the canonical source of data about the members is elsewhere is a good candidate for Static Lists, e.g., members of a customer loyalty program.
All Lists
Example Request
GET /api/lists HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Data-Attribute: lists
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true,
"lists" : [
{
"name" : "platinum_members",
"description" : "loyalty program platinum members",
"extra" : { "key" : "value" },
"created" : "2013-08-08T20:41:06",
"last_modified" : "2014-05-01T18:00:27",
"channel_count": 3145,
"status": "ready"
},
{
"name": "gold_members",
"description": "loyalty program gold member",
"extra": { "key": "value" },
"created": "2013-08-08T20:41:06",
"last_updated": "2014-05-01T18:00:27",
"channel_count": 678,
"status": "ready"
}
]
}Retrieve information about all static lists. This call returns a list of metadata that will not contain the actual lists of users. Optionally, provide the type of lists that you want to retrieve.
Security:
Request Parameters
type query
StringOptionalThe type of lists to retrieve, defaults to
userwhich is all user-generated lists.allspecifies that all lists are returned. Other values will return specific types of generated lists. Valid types:user,all,lifecycle.
Response
200 OK
Lists metadata retrieved successfully.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
An array of List Objects.
ok
BooleanOptionalSuccess.
401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
Create List
Example Request
POST /api/lists HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name" : "platinum_members",
"description" : "loyalty program platinum members",
"extra" : {
"key" : "value"
}
}Example Response
HTTP/1.1 200 OK
Location: https://go.urbanairship.com/api/lists/platinum_members
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true
}Create a static list. The body of the request will contain several of the list object parameters, but the actual list content will be provided by a second call to the upload endpoint.
Content-Encoding: gzip is supported (and recommended) on this endpoint to reduce network traffic.
Security:
Request Body
application/json
Type: Static List Object
Contains all user-specified data about a static list (metadata), but does not contain CSV list contents. Use the /api/lists/{name}/csv endpoints to upload or download list contents.
Response
201 Created
Returns OK for success.
Response Headers
Location
StringThe URI of the list, used for later updates.
Format:
uri.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: 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 app has reached the maximum number of allowed lists (error_code 40906). A list with that name already exists (error_code 40907). List is already processing recently uploaded CSV (error_code 40910).
Response Body
application/vnd.urbanairship+json; version=3;
Type: 409
The request conflicts with another request.
Get a Single List
Example Request
GET /api/lists/platinum_members/ HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 200 OK
Data-Attribute: static_list
Link: <https://go.urbanairship.com/api/platinum_members/list/?start=uuid101&limit=100>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true,
"name" : "platinum_members",
"description" : "loyalty program platinum members",
"extra" : { "key" : "value" },
"created" : "2013-08-08T20:41:06",
"last_updated" : "2014-05-01T18:00:27",
"channel_count" : 1000,
"status" : "ready"
}Retrieve information about one static list, specified in the URL. When looking up lists, the returned information may actually be a combination of values from both the last uploaded list and the last successfully processed list. If you create a list successfully, and then you update it and the processing step fails, then the list status will read failed, but the channel_count and last_modified fields will contain information on the last successfully processed list.
Security:
Request Parameters
name path
StringRequiredThe name of the list.
Response
200 OK
Returns OK for success.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Static List Object
Contains all user-specified data about a static list (metadata), but does not contain CSV list contents. Use the
/api/lists/{name}/csvendpoints to upload or download list contents.401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Update list metadata
Example Request
PUT /api/lists/platinum_members HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name" : "platinum_members",
"description" : "loyalty program platinum members",
"extra" : {
"key" : "value"
}
}Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true
}Update the metadata (description, extras, etc.) of a static list.
If you are trying to update the list contents, please see the list upload endpoint. The update endpoint is used to update a list's metadata rather than the actual list of device identifiers.
Security:
Request Parameters
name path
StringRequiredThe name of the list.
Request Body
The body of the request will contain a list object, though you can omit the name attribute. If present, it must match the name provided in the URL. You cannot change the name of a list; it is the primary identifier for the list.
application/json
Type: Static List Object
Contains all user-specified data about a static list (metadata), but does not contain CSV list contents. Use the /api/lists/{name}/csv endpoints to upload or download list contents.
Response
200 OK
The list metadata was updated successfully.
400 Bad Request
Bad Request. Parsing or validating the request failed. error_code 40001: Attempted list rename. List renaming is not allowed.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the API may not be used to create or modify lists with “ua_” prefixed name.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Delete a List
Example Request
DELETE /api/lists/platinum_members HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;Example Response
HTTP/1.1 204 No ContentDelete a list. If you are attempting to update a current list by deleting it and then recreating it with new data, stop and go to the upload endpoint. There is no need to delete a list before uploading a new CSV file. Moreover, once you delete a list, you will be unable to create a list with the same name as the deleted list.
If you are attempting to update a current list by deleting it and then recreating it with new data, stop and go to the upload endpoint. There is no need to delete a list before uploading a new CSV file. Moreover, once you delete a list, you will be unable to create a list with the same name as the deleted list.
Security:
Request Parameters
name path
StringRequiredThe name of the list.
Response
204 NoContent
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.
403 Forbidden
You cannot delete or modify lists with a "ua_" prefixed
name.Response Body
application/vnd.urbanairship+json; version=3;
Type: 403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Download a list of channels
Example Request
GET /api/lists/foobar/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+csv; version=3Example Response
HTTP/1.1 200 OK
Content-Type: text/csv
ios_channel,6d56ab7e-2c78-4ba9-ab11-d9b664ca2b32
ios_channel,d5ebe607-a3e6-4601-b97e-83ec604223fe
ios_channel,fa599af7-43e4-4862-a570-1470bf6f53ff
android_channel,0e91d0f2-c65d-4b40-b968-b9f8e8b0c987
android_channel,c346a3ce-5754-4d02-8ee5-500ce470a0b7
android_channel,e9a01369-5f74-4167-b660-df84014a2e57
amazon_channel,0356d138-d1d9-4572-b321-e1b67f4cd658
amazon_channel,24dc9a76-45fe-4b17-8ed7-841f96b658ad
amazon_channel,4d6b59f8-6d8c-4151-8b13-cd58d6ac8c6eAllows you to download the contents of a static list (as opposed to a GET /api/lists/{name} which will return metadata about the list). When you upload a list, alias and named_user entries are resolved to channels. Therefore, the CSV output from this endpoint will be in the same format as the uploaded list, but will only contain ios_channel, android_channel and amazon_channel entries.
Security:
Request Parameters
name path
StringRequiredThe
nameof the list you want to retrieve or update.
Response
200 OK
Returns a CSV list of channels.
Response Body
text/csv
Type: String
Update list contents
Example Request
PUT /api/lists/platinum_members/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: text/csv
alias,stevenh
alias,marianb
ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634
named_user,SDo09sczvJkoiu
named_user,"gates,bill"Example Response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true
}Replace the contents of an existing static list via CSV file upload. Uploads must be newline delimited identifiers (text/CSV) with commas as the delimiter.
The CSV format is two columns: identifier_type and identifier. The identifier is the associated identifier you wish to send to. The identifier_type
must be one of:
named_userios_channelandroid_channelamazon_channelsmsemailopen_channel
The maximum number of identifier_type,identifier pairs that may be uploaded to a list is 10 million. Content-Encoding: gzip is supported (and recommended) on this endpoint to reduce network traffic.
If an attempt to upload a list times out due to a poor connection, you must re-upload the list from scratch. Because we want to ensure that the entirety of a given list is successfully uploaded, we do not support partial list uploads.
Security:
Request Parameters
name path
StringRequiredThe
nameof the list you want to retrieve or update.
Request Body
text/csv
Type: String
Format: binary.
Response
202 Accepted
The request has been accepted for processing.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey will appear in the top-most object, outside the verbose response.400 Bad Request
Bad Request. Parsing or validating the request failed. error_code 40002: CSV contains too many identifiers. error_code 40003: CSV contains an entry with a column count other than 2. error_code 40004: CSV contains an invalid
identifier_type. error_code 40005: CSV contains a channelidentifierthat is not a valid UUID.Response Body
application/vnd.urbanairship+json; version=3;
Type: 400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.401 Unauthorized
Authentication information (the app key & secret) was either incorrect or missing.
403 Forbidden
Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g. the API may not be used to create or modify lists with “ua_” prefixed name.
Response Body
application/vnd.urbanairship+json; version=3;
Type: 403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
404 Not Found
The requested resource doesn't exist.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Create and Send
Simultaneously send a notification to an audience of SMS, email, or open channel addresses and register channels for new addresses in your audience. Create and send can help you immediately notify new open::, email, or sms contacts without having to wait for channel registration.
While create and send can help you quickly register new channels, you can use these endpoints for existing channels as well. Addresses in the audience that are not yet associated with channels are registered as new channels. Addresses in the payload that are already registered to opted-in channel_ids will still receive notifications, but are not registered as new channels.
You cannot update channel information or opt-in status from these endpoints. If you want to update channels, refer to the appropriate email, sms, or open channel endpoints.
Create and Send
Example Create and Send Using Email
POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
{
"audience": {
"create_and_send" : [
{
"ua_address": "new@email.com",
"ua_commercial_opted_in": "2018-11-29T10:34:22",
},
{
"ua_address" : "ben@icetown.com",
"ua_commercial_opted_in": "2018-11-29T12:45:10",
}
]
},
"device_types" : [ "email" ],
"notification" : {
"email": {
"subject": "Welcome to the Winter Sale! ",
"html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
"plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
"message_type": "commercial",
"sender_name": "Airship",
"sender_address": "team@urbanairship.com",
"reply_to": "no-reply@urbanairship.com"
}
},
"campaigns": {
"categories": ["winter sale", "west coast"]
}
}Example with Inline Template
POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
{
"audience": {
"create_and_send" : [
{
"ua_address": "new@email.com",
"ua_commercial_opted_in": "2018-11-29T10:34:22",
"name": "New Person, Esq.",
"location": "City, State"
},
{
"ua_address" : "ben@icetown.com",
"ua_commercial_opted_in": "2018-11-29T12:45:10",
"name": "Ben Wyatt",
"location": "Pawnee, IN"
}
]
},
"device_types" : [ "email" ],
"notification" : {
"email": {
"message_type": "commercial",
"sender_name": "Airship",
"sender_address": "team@urbanairship.com",
"reply_to": "no-reply@urbanairship.com",
"template": {
"variable_details": [
{
"key": "name",
"default_value": "you"
}
],
"fields": {
"subject": "Hi there, {{name}}",
"plaintext_body": "Hope you're enjoying our store in {{location}} [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]"
}
}
}
}
}Example Response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3
{
"ok": true,
"operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
"push_ids": [
"c0eead17-333b-4f86-8a42-9fb7be1ed627"
],
"message_ids": [],
"content_urls": []
}Send a notification to an audience of SMS, email, or open channel addresses and simultaneously register new addresses in the audience as new channels. Addresses that are not yet associated with channels are registered as new channels. Addresses in the payload that are already registered to a channel_id will still receive the notification, but are not associated with new channels.
The payload is modeled after a push object, but has specialized audience requirements and is limited to a single device_type (one of email, sms, mms or open::<open_channel_name>).
Duplicate addresses in the create-and-send array might receive redundant notifications. You should remove duplicate addresses from your request before sending a create-and-send notification.
Security:
Request Body
application/json
Type: Any
- One of:
Type: Create and Send to Email Channels
The payload for a create and send operation to email channels. When registering and sending to email channels,
device_typesmust be set toemail.Type: Create and Send to SMS Channels
The payload for a create and send operation to SMS channels. When registering and sending to SMS channels,
device_typesmust be set tosms.Type: Create and Send MMS Notification
The payload for a create and send operation that registers SMS channels and sens a multimedia payload (MMS). When sending an MMS payload,
device_typesmust be set tomms.Type: Create and Send to Open Channels
When registering and sending to open channels, the
device_typemust be set toopen::<open_channel_name>.
Response
202 Accepted
Because this operation sends messages, a successful response is nearly identical to a
/api/pushresponse.Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
A push response contains a list of identifiers for the notifications sent in the request.
content_urls
Array<String>OptionalAn array of URLs where the push payload contains a landing page action.
Max items: 100. Min items: 1.
Format:
uri. Pattern:^https.*:\/\/.+.message_ids
Array<String>OptionalAn array of message IDs, each uniquely identifying a Message Center message.
ok
BooleanOptionalSuccess.
operation_id
StringOptionalA unique string identifying the operation, useful for reporting and troubleshooting.
Format:
uuid.push_ids
Array<String>OptionalAn array of push IDs, each uniquely indentifying a push.
Max items: 100. Min items: 1.
Format:
uuid.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Validate Create and Send Payload
Example Validating Create-and-send Payload
POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
{
"audience": {
"create_and_send" : [
{
"ua_address": "new@email.com",
"ua_commercial_opted_in": "2018-11-29T10:34:22",
},
{
"ua_address" : "ben@icetown.com",
"ua_commercial_opted_in": "2018-11-29T12:45:10",
}
]
},
"device_types" : [ "email" ],
"notification" : {
"email": {
"subject": "Welcome to the Winter Sale! ",
"html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
"plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
"message_type": "commercial",
"sender_name": "Airship",
"sender_address": "team@urbanairship.com",
"reply_to": "no-reply@urbanairship.com"
}
},
"campaigns": {
"categories": ["winter sale", "west coast"]
}
}Example Validation Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true
}Validate a create-and-send payload. This endpoint will not create channels or send notifications; it only parses and validates your payload.
Security:
Request Body
application/json
Type: Any
- One of:
Type: Create and Send to Email Channels
The payload for a create and send operation to email channels. When registering and sending to email channels,
device_typesmust be set toemail.Type: Create and Send to SMS Channels
The payload for a create and send operation to SMS channels. When registering and sending to SMS channels,
device_typesmust be set tosms.Type: Create and Send MMS Notification
The payload for a create and send operation that registers SMS channels and sens a multimedia payload (MMS). When sending an MMS payload,
device_typesmust be set tomms.Type: Create and Send to Open Channels
When registering and sending to open channels, the
device_typemust be set toopen::<open_channel_name>.
Response
200 OK
Everything worked as expected.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Ok Response
Returned with 2xx Responses. At a minumum, successful calls return
truefor theokkey. If your call includes a verbose response (as withGETrequests, etc), theokkey 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
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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 Create and Send Operation
Example Scheduled Create and Send
POST /api/schedules/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json
{
"schedule": {
"scheduled_time" : "2018-11-11T12:00:00"
},
"name" : "scheduled winter sale email",
"push" : {
"audience": {
"create_and_send" : [
{
"ua_address": "new@email.com",
"ua_commercial_opted_in": "2018-11-29T10:34:22",
},
{
"ua_address" : "ben@icetown.com",
"ua_commercial_opted_in": "2018-11-29T12:45:10",
}
]
},
"device_types" : [ "email" ],
"notification" : {
"email": {
"subject": "Welcome to the Winter Sale! ",
"html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
"plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
"message_type": "commercial",
"sender_name": "Airship",
"sender_address": "team@urbanairship.com",
"reply_to": "no-reply@urbanairship.com"
}
},
"campaigns": {
"categories": ["winter sale", "west coast"]
}
}Example Response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3
{
"ok": true,
"operation_id": "67c65146-c27f-431f-b54a-83aca694fdd3",
"schedule_urls": [
"http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109"
],
"schedules": [
{
"url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
"schedule": {
"scheduled_time" : "2018-11-11T12:00:00"
},
"push": {
"audience": {
"create_and_send" : [
{
"ua_address": "new@email.com",
"ua_commercial_opted_in": "2018-11-29T10:34:22",
},
{
"ua_address" : "ben@icetown.com",
"ua_commercial_opted_in": "2018-11-29T12:45:10",
}
]
},
"device_types" : [ "email" ],
"notification" : {
"email": {
"subject": "Welcome to the Winter Sale! ",
"html_body": "<h1>Seasons Greetings</h1><p>Check out our winter deals!</p><p><a data-ua-unsubscribe=\"1\" title=\"unsubscribe\" href=\"http://unsubscribe.urbanairship.com/email/success.html\">Unsubscribe</a></p>",
"plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]",
"message_type": "commercial",
"sender_name": "Airship",
"sender_address": "team@urbanairship.com",
"reply_to": "no-reply@urbanairship.com"
},
"campaigns": {
"categories": ["winter sale", "west coast"]
}
}
}
],
"push_ids": ["8cf8b2a5-7655-40c2-a500-ff498e60453e"]
}Schedule a notification to an audience of SMS, email, or open channel addresses and simultaneously register those addresses as new channels. Addresses that are not yet associated with channels are registered as new channels. Addresses in the payload that are already registered to a channel_id will still receive the notification, but are not associated with new channels.
Duplicate addresses in the create-and-send array might receive redundant notifications. You should remove duplicate addresses from your request before scheduling a create-and-send notification.
Security:
Request Body
The request is much like other create-and-send operations, with a leading schedule object. The standard create-and-send payload sits inside a push object.
application/json
Type: Object
name
StringOptionalA name for the schedule.
push
AnyRequired- One of:
Type: Create and Send to Email Channels
The payload for a create and send operation to email channels. When registering and sending to email channels,
device_typesmust be set toemail.Type: Create and Send to SMS Channels
The payload for a create and send operation to SMS channels. When registering and sending to SMS channels,
device_typesmust be set tosms.Type: Create and Send MMS Notification
The payload for a create and send operation that registers SMS channels and sens a multimedia payload (MMS). When sending an MMS payload,
device_typesmust be set tomms.Type: Create and Send to Open Channels
When registering and sending to open channels, the
device_typemust be set toopen::<open_channel_name>.
schedule
ObjectRequiredSimilar to other schedule objects. However, create-and-send requests support
scheduled_timeonly.scheduled_time
StringRequiredThe date and time when you want to perform your create-and-send operation. Users will receive the notification as soon as possible after the specified datetime.
Format:
datetime.
Response
202 Accepted
Because this operation sends messages, a successful response is nearly identical to a
/api/pushresponse.Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
A push response contains a list of identifiers for the notifications sent in the request.
content_urls
Array<String>OptionalAn array of URLs where the push payload contains a landing page action.
Max items: 100. Min items: 1.
Format:
uri. Pattern:^https.*:\/\/.+.message_ids
Array<String>OptionalAn array of message IDs, each uniquely identifying a Message Center message.
ok
BooleanOptionalSuccess.
operation_id
StringOptionalA unique string identifying the operation, useful for reporting and troubleshooting.
Format:
uuid.push_ids
Array<String>OptionalAn array of push IDs, each uniquely indentifying a push.
Max items: 100. Min items: 1.
Format:
uuid.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
Reports
The Airship Reports APIs are available in only certain account plans. Please contact Support or your Account Manager if you are unable to use them for an app key that you believe is on an appropriate plan.
The Statistics API at /api/push/stats is available to all customers.
Devices Report
Example Request
GET /api/reports/devices HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"total_unique_devices": 13186,
"date_closed": "2018-08-28 00:00:00",
"date_computed": "2018-08-29 13:30:45",
"counts": {
"ios": {
"unique_devices": 231,
"opted_in": 142,
"opted_out": 89,
"uninstalled": 2096
},
"android": {
"unique_devices": 11795,
"opted_in": 226,
"opted_out": 11569,
"uninstalled": 1069
},
"amazon": {
"unique_devices": 29,
"opted_in": 22,
"opted_out": 7,
"uninstalled": 9
},
"sms": {
"unique_devices": 26,
"opted_in": 23,
"opted_out": 3,
"uninstalled": 17
}
}
}Get an app's opted-in and installed device counts by device type.
Security:
Request Parameters
date query
StringOptionalAll device events counted occurred before this ISO formatted timestamp.
Response
200 OK
Returned on success, with the JSON representation of the device counts in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for the device report.
counts
ObjectOptionalThe counts for each device type.
amazon
ObjectOptionalThe count object for a device type.
opted_in
IntegerOptionalOpted in to receiving push notifications.
opted_out
IntegerOptionalOpted out of receiving push notifications.
uninstalled
IntegerOptionalDevices for which Reports has seen an uninstall event.
unique_devices
IntegerOptionalDevices considered by Airship Reports to have the app installed.
android
ObjectOptionalThe count object for a device type.
opted_in
IntegerOptionalOpted in to receiving push notifications.
opted_out
IntegerOptionalOpted out of receiving push notifications.
uninstalled
IntegerOptionalDevices for which Reports has seen an uninstall event.
unique_devices
IntegerOptionalDevices considered by Airship Reports to have the app installed.
ios
ObjectOptionalThe count object for a device type.
opted_in
IntegerOptionalOpted in to receiving push notifications.
opted_out
IntegerOptionalOpted out of receiving push notifications.
uninstalled
IntegerOptionalDevices for which Reports has seen an uninstall event.
unique_devices
IntegerOptionalDevices considered by Airship Reports to have the app installed.
date_closed
StringOptionalAll device events counted occurred before this date and time.
Format:
date-time.date_computed
StringOptionalThe date and time the device event data was tallied and stored.
Format:
date-time.total_unique_devices
IntegerOptionalSum of the unique devices for every device type.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: 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 Detail Listing
Example Request
GET /api/reports/events HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"total_value": 2,
"total_count": 709,
"next_page": "https://go.urbanairship.com/api/reports/events?start=2018-08-01T10:00:00.000Z&end=2018-08-15T20:00:00.000Z&precision=MONTHLY&page_size=20&page=2",
"events": [
{
"name": "banner_image",
"conversion": "indirect",
"location": "ua_mcrap",
"count": 1,
"value": 1
},
{
"name": "bounce",
"conversion": "direct",
"location": "custom",
"count": 23,
"value": 0
},
{
"name": "button-click-Do it ",
"conversion": "direct",
"location": "in_app_message",
"count": 1,
"value": 0
},
{
"name": "button-click-Get Notifications",
"conversion": "unattributed",
"location": "in_app_message",
"count": 3,
"value": 0
},
{
"name": "button-click-RATE NOW",
"conversion": "direct",
"location": "in_app_message",
"count": 1,
"value": 0
},
{
"name": "button-click-Rate the app.",
"conversion": "direct",
"location": "in_app_message",
"count": 1,
"value": 0
}
]
}Get a summary of custom event counts and values, by custom event, within the specified time period.
Security:
Request Parameters
start query
StringRequiredAn ISO formatted timestamp for start of report.
end query
StringRequiredAn ISO formatted timestamp for end of report.
precision query
StringRequiredGranularity of results to return.
Possible values:
HOURLY,DAILY,MONTHLY.page query
IntegerOptionalIdentifies the desired page number. Defaults to 1. If page is given a negative or out of bounds value, the default value will be used.
page_size query
IntegerOptionalSpecifies how many results to return per page. Has a default value of 25 and a maximum value of 100.
Response
200 OK
Returned on success, with the JSON representation of the events in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for custom events detail listing.
events
Array<Object>OptionalAn array of custom events and its details.
conversion
StringOptionalCan be one of direct or indirect.
count
IntegerOptionalNumber of instances of this event.
location
StringOptionalThe source from which the event originates, e.g. Message Center, Landing Page, custom, etc.
name
StringOptionalThe name of the custom event.
value
IntegerOptionalThe value generated by the event.
next_page
StringOptionalThere 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
BooleanOptionalSuccess.
prev_page
StringOptionalLink to the previous page, if available.
Format:
url.total_count
IntegerOptionalSum of all the count fields in the above array.
total_value
IntegerOptionalSum of all the value fields in the above array.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Experiment Variant Report
Example Request
GET /api/reports/experiment/detail/b43ae1b2-3ff6-4c02-adb2-79deac0bbb19/2 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"app_key": "some_app_key",
"experiment_id": "a7806815-6483-4cb9-9d74-bc3b4f3dc1b8",
"push_id": "cf8a3c64-568e-4ace-8d12-c494e14c3e73",
"created": "2016-02-25 23:03:12",
"variant": 2,
"variant_name": "thing_two",
"sends": 64,
"direct_responses": 3,
"influenced_responses": 1,
"platforms": {
"android": {
"direct_responses": 0,
"influenced_responses": 0,
"sends": 22
},
"ios": {
"direct_responses": 0,
"influenced_responses": 1,
"sends": 36
},
"amazon": {
"direct_responses": 0,
"influenced_responses": 0,
"sends": 0
},
"web": {
"direct_responses": 3,
"indirect_responses": 0,
"sends": 6
}
}
}Returns statistics and metadata about a specific variant in an experiment (A/B Test).
Security:
Request Parameters
push_id path
StringRequiredThe
push_idof the requested experiment.Format:
uuid.variant_id path
IntegerRequiredThe specific variant you want to return results for.
Max: 26. Min: 1.
Response
200 OK
Returned on success.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
app_key
StringOptionalThe app key for the given
push_id.created
StringOptionalThe date and time when the variant was created.
Format:
date-time.direct_responses
IntegerOptionalThe number of direct responses to the variant.
experiment_id
StringOptionalID of the experiment that the variant belongs to.
Format:
uuid.influenced_responses
IntegerOptionalThe total number of influenced responses to the variant.
platforms
ObjectOptionalamazon
ObjectOptionaldirect_responses
IntegerOptionalThe number of direct responses (clicks/app opens) to the variant notification on this platform as measured by the SDK.
influenced_responses
IntegerOptionalThe number of opens or clicks resulting from your notification (directly or indirectly).
sends
IntegerOptionalThe total number of audience members that accounted the variant on the specified platform.
android
ObjectOptionaldirect_responses
IntegerOptionalThe number of direct responses (clicks/app opens) to the variant notification on this platform as measured by the SDK.
influenced_responses
IntegerOptionalThe number of opens or clicks resulting from your notification (directly or indirectly).
sends
IntegerOptionalThe total number of audience members that accounted the variant on the specified platform.
ios
ObjectOptionaldirect_responses
IntegerOptionalThe number of direct responses (clicks/app opens) to the variant notification on this platform as measured by the SDK.
influenced_responses
IntegerOptionalThe number of opens or clicks resulting from your notification (directly or indirectly).
sends
IntegerOptionalThe total number of audience members that accounted the variant on the specified platform.
web
ObjectOptionaldirect_responses
IntegerOptionalThe number of direct responses (clicks/app opens) to the variant notification on this platform as measured by the SDK.
influenced_responses
IntegerOptionalThe number of opens or clicks resulting from your notification (directly or indirectly).
sends
IntegerOptionalThe total number of audience members that accounted the variant on the specified platform.
push_id
StringOptionalThe specific push_id that the variant belonged to.
Format:
uuid.variant
IntegerOptionalThe individual variaint you want to return results for. Variants are ordered 1-26 in the order that they are arranged in the
variantsarray when you created the experiment.Max: 26. Min: 1.
variant_name
StringOptionalThe name of the variant specified in the endpoint.
Experiment Overview Report
Example Request
GET /api/reports/experiment/overview/b43ae1b2-3ff6-4c02-adb2-79deac0bbb19 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"app_key": "some_app_key",
"experiment_id": "a7806815-6483-4cb9-9d74-bc3b4f3dc1b8",
"push_id": "cf8a3c64-568e-4ace-8d12-c494e14c3e73",
"created": "2016-02-25 23:03:12",
"sends": 532,
"direct_responses": 50,
"influenced_responses": 60,
"web_clicks": 6,
"web_sessions": 8,
"variants": [
{
"id" : 0,
"name": "call to action",
"audience_pct": 45.0,
"sends": 238,
"direct_responses": 32,
"direct_response_pct": 13.44,
"indirect_responses": 0,
"indirect_response_pct": 0.0
},
{
"id" : 1,
"name": "gentle reminder",
"audience_pct": 45.0,
"sends": 251,
"direct_responses": 20,
"direct_response_pct": 7.97,
"indirect_responses": 4,
"indirect_response_pct": 1.59
}
],
"control": {
"audience_pct": 10.0,
"sends": 50,
"responses": 1,
"response_rate_pct": 2.0
}
}Returns statistics and metadata about an experiment (A/B Test).
Security:
Request Parameters
push_id path
StringRequiredThe
push_idof the requested experiment.Format:
uuid.
Response
200 OK
Returned on success.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Any
app_key
StringOptionalThe app key for the given
push_id.control
ObjectOptionalJSON object describing the control group, i.e., those devices that receive no notification, for the experiment.
audience_pct
NumberOptionalThe percentage of the total audience belonging to the control group.
response_rate_pct
NumberOptionalThe response rate from the control group.
responses
IntegerOptionalThe number of responses from the control group.
sends
IntegerOptionalThe number of pushes sent to native mobile platforms, e.g., iOS. Exclusive of
open_channel_sends, which are broken out underopen_channel_sends.
direct_responses
IntegerOptionalThe number of direct responses to the experiment.
experiment_id
StringOptionalID for the requested experiment.
Format:
uuid.influenced_responses
IntegerOptionalThe number of influenced responses to the experiment.
variants
ObjectOptionalSingle variant reporting object or array of variant reporting objects, including associated metadata, audience percentage and response statistics.
audience_pct
NumberOptionaldirect_responce_pct
NumberOptionalThe percentage direct responses to the notification measured by the SDK.
direct_responses
IntegerOptionalThe number of direct responses to the variant measured by the SDK.
id
IntegerOptionalindirect_responce_pct
NumberOptionalThe percentage indirect responses to the notification measured by the SDK.
indirect_responses
IntegerOptionalThe number of indirect responses to the variant measured by the SDK.
name
StringOptionalsends
IntegerOptionalThe number of pushes sent SDK-supporting platforms, e.g., iOS, Android, and Web. Exclusive of
open_channel_sends, which are broken out underopen_channel_sends.
web_clicks
IntegerOptionalThe number of web notifications that the audience clicked on.
web_sessions
IntegerOptionalThe total number of web sessions that resulted in a notification. Use in conjunction with
web_clicksto determine the effectiveness of your web notification experiments.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
App Opens Report
Example Request
GET /api/reports/opens?start=2018-08-01%2010:00&end=2018-08-15%2020:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"opens": [
{
"date": "2018-08-01 00:00:00",
"ios": 350,
"android": 250
}
]
}Get the number of users who have opened your app within the specified time period.
Security:
Request Parameters
start query
StringRequiredAn ISO formatted timestamp for start of report.
end query
StringRequiredAn ISO formatted timestamp for end of report.
precision query
StringRequiredGranularity of results to return.
Possible values:
HOURLY,DAILY,MONTHLY.
Response
200 OK
Returned on success, with the JSON representation of the app opens in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for app opens report.
next_page
StringOptionalThere 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.opens
Array<Object>OptionalAn array of App Opens Objects.
android
IntegerOptionalThe number of app opens for Android.
date
StringOptionalThe date and time of when the users opened your app.
Format:
date-time.ios
IntegerOptionalThe number of app opens for iOS.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Opt-in Report
Example Request
GET /api/reports/optins?start=2018-08-01%2010:00&end=2018-08-15%2020:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"optins": [
{
"android": 50,
"date": "2018-05-01 00:00:00",
"ios": 500
}
],
"next_page": "https://go.urbanairship.com/api/reports/..."
}Get the number of opted-in Push users who access the app within the specified time period.
Security:
Request Parameters
start query
StringRequiredAn ISO formatted timestamp for start of report.
end query
StringRequiredAn ISO formatted timestamp for end of report.
precision query
StringRequiredGranularity of results to return.
Possible values:
HOURLY,DAILY,MONTHLY.
Response
200 OK
Returned on success, with the JSON representation of the opt-ins in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for opt-in report.
next_page
StringOptionalThere 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.optins
Array<Object>OptionalAn array of OptIn Objects.
android
IntegerOptionalThe number of users who opt-in for Android.
date
StringOptionalThe date and time of when the users opt-in.
Format:
date-time.ios
IntegerOptionalThe number of users who opt-in for iOS.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Opt-out Report
Example Request
GET /api/reports/optouts?start=2018-08-01%2010:00&end=2018-08-15%2020:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"optouts": [
{
"android": 5,
"date": "2018-05-01 00:00:00",
"ios": 25
}
],
"next_page": "https://go.urbanairship.com/api/reports/..."
}Get the number of opted-out Push users who access the app within the specified time period.
Security:
Request Parameters
start query
StringRequiredAn ISO formatted timestamp for start of report.
end query
StringRequiredAn ISO formatted timestamp for end of report.
precision query
StringRequiredGranularity of results to return.
Possible values:
HOURLY,DAILY,MONTHLY.
Response
200 OK
Returned on success, with the JSON representation of the opt-outs in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for opt-out report.
next_page
StringOptionalThere 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.optouts
Array<Object>OptionalAn array of OptOut Objects.
android
IntegerOptionalThe number of users who opt-out for Android.
date
StringOptionalThe date and time of when the users opt-out.
Format:
date-time.ios
IntegerOptionalThe number of users who opt-out for iOS.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Response Report
Example Request
GET /api/reports/responses?start=2018-05-01%2010:00&end=2018-05-30%2010:00&precision=MONTHLY HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"next_page": "https://go.urbanairship.com/api/reports/...",
"responses": [
{
"android": {
"direct": 25,
"influenced": 118
},
"date": "2018-05-01 00:00:00",
"ios": {
"direct": 16,
"influenced": 87
}
}
]
}Get the number of direct and influenced opens of your app.
Security:
Request Parameters
start query
StringRequiredAn ISO formatted timestamp for start of report.
end query
StringRequiredAn ISO formatted timestamp for end of report.
precision query
StringRequiredGranularity of results to return.
Possible values:
HOURLY,DAILY,MONTHLY.
Response
200 OK
Returned on success, with the JSON representation of the responses in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for response report.
next_page
StringOptionalThere 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.responses
Array<Object>OptionalAn array of Response Objects.
android
ObjectOptionaldirect
IntegerOptionalThe number of direct opens of your app.
influenced
IntegerOptionalThe number of influenced opens of your app.
date
StringOptionalThe date and time for direct and influenced opens.
Format:
date-time.ios
ObjectOptionaldirect
IntegerOptionalThe number of direct opens of your app.
influenced
IntegerOptionalThe number of influenced opens of your app.
400 Bad Request
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.Response Body
application/json
Type: 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.
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.
Response Body
application/json
Type: Error Response
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Response Listing
Example Request
GET /api/reports/responses/list?start=2018-08-01%2010:00&end=2018-08-15%2010:00&limit=20 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3Example Response
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"next_page": "https://go.urbanairship.com/api/reports/responses/list?start=2018-08-01+10%...",
"pushes": [
{
"push_uuid": "f4db3752-a982-4a2b-994e-7b5fd1c7f02f",
"push_time": "2018-08-15 02:12:22",
"push_type": "UNICAST_PUSH",
"group_id": "4e768dc7-4ebc-4206-890a-60b5627763a7",
"direct_responses": 0,
"sends": 1,
"open_channels_sends": {
"platforms": []
}
},
{
"push_uuid": "5a4ade58-fbd3-43a2-ac3c-e834ee190151",
"push_time": "2018-08-14 19:58:15",
"push_type": "UNICAST_PUSH",
"group_id": "c5664e1f-106e-4616-9820-7d9ecce8a3f3",
"direct_responses": 1,
"sends": 2,
"open_channels_sends": {
"platforms": []
}
}
]
}Get a listing of all pushes, plus basic response information, in a given timeframe. Start and end date times are required parameters.
Security:
Request Parameters
start query
StringRequiredAn ISO formatted timestamp for start of report.
end query
StringRequiredAn ISO formatted timestamp for end of report.
limit query
IntegerOptionalNumber of results to return at one time (for pagination).
Min: 1.
Response
200 OK
Returned on success, with the JSON representation of the listing in the body of the response.
Response Body
application/vnd.urbanairship+json; version=3;
Type: Object
The response body for response listing.
next_page
StringOptionalThere 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.pushes
Array<Object>OptionalAn array of all pushes and its basic response information.
direct_responses
IntegerOptionalThe number of direct responses to the notification measured by the SDK.
group_id
StringOptionalAn identifier set by the server to logically group a set of related pushes, e.g., in a push to local time.
Format:
uuid.open_channel_sends
ObjectOptionalContains an array of the number of send counts per open platform. If there were no open channels sends associated with the push ID, an empty result will be returned.
platforms
Array<Object>OptionalAn array of objects indicating the total sends by open platform.
id
StringOptionalThe key representing the canonical identifier in the Airship system for the given open platform.
sends
IntegerOptionalThe number of sends for the given push ID and the given open platform.
push_time
StringOptionalThe ISO 8601 timestamp in UTC indicating the time that the push was initially sent.
Format:
date-time.push_type
StringOptionalThis string describes the push operation, which is often comparable to the audience selection.
Possible values:
BROADCAST_PUSH,TAG_PUSH,SCHEDULED_PUSH,SEGMENTS_PUSH,UNICAST_PUSH.push_uuid
StringOptionalThe UUID for the requested push.
Format:
uuid.