Airship API
Airship’s REST APIs for messaging, content personalization and audience management.
Libraries
Airship maintains open source server libraries to support your integrations with our APIs in multiple languages. Click below for library documentation.
Introduction
Airship provides a number of REST API endpoints collectively known as the Airship API Version 3, in support of our messaging product lines and related features. Version 3 is the current and only supported version of the Airship API.
API Request Format
All API requests are HTTP requests. For all requests with a body, the body may be in JSON
format or other formats like CSV as specified for the endpoint. The proper Content-Type for
JSON is application/json and the proper content type for CSV is text/csv.
Version Syntax
You must specify the version of the API you are using with the Accept HTTP header. If you do not specify an API version in the Accept header, a 406: is returned.
The content type used is a vendor-specific media type
(see RFC 4288), and must be specified as follows: application/vnd.urbanairship+json; version=3;.
Transport Layer Security
As of October 6, 2020, Airship supports only TLS (Transport Layer Security) version 1.2 and 1.3 in our APIs, in accordance with PCI Security Standards Council recommendations.
If your API integration utilizes TLS 1.0 or 1.1, contact our Support team for assistance migrating to TLS 1.2 or 1.3.
Delivery Speed Options
The Airship push API is designed for extremely high throughput to ensure delivery to your entire audience as fast as possible. Depending on the size and/or complexity of your audience and the urgency of the message, you may find that you need to either slow down or speed up the delivery. To that end, we offer the following add-on services: Boost and Throttling.
If you are interested in enabling push boost or throttling for your app, please contact support@urbanairship.com.
Boost
Boost optimizes your segmented messages through parallel processing. Consider adding Boost if your notifications are extremely time-sensitive. Boost is a paid add-on. Contact your Account Manager for details.
Throttling
For less time-sensitive messages, our standard delivery speed may cause undue pressure on your internal systems or APIs, e.g., when millions of users open your app at the same time. Throttling allows you to tune delivery to a level that doesn’t put strain on those systems.
Base URL
Select the domain (.com or .eu/asnapieu.com) associated with your Airship project.
- The base URL for Airship’s North American cloud site.
- The base URL for Airship’s European cloud site.
Authentication
HTTP Authentication
Basic App AuthAuthorization header containing the wordBasicfollowed by a space and a Base64-encoded string generated from your app key and app secret inappKey:appSecretformat, e.g.,Basic YXBwX2tleTphcHBfc2VjcmV0.HTTP Authentication
Basic AuthAuthorization header containing the wordBasicfollowed by a space and a Base64-encoded string generated from your app key and master secret inappKey:masterSecretformat, e.g.,Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0.HTTP Authentication
Bearer AuthA bearer token generated from the Airship dashboard. You can generate tokens for different roles; if your role does not grant you access to a feature, the endpoint will respond with a 401. Tokens can be revoked at will.
Push
Send notifications or rich messages to supported channels, or validate JSON payloads.
Send a Push
Example
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" ]
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
PushPayload payload = PushPayload.newBuilder()
.setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
.setNotification(Notifications.alert("Hello!"))
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
.build();
PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
push = airship.create_push()
push.audience = ua.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
push.notification = ua.notification(alert='Hello!')
push.device_types = ua.device_types('ios')
push.send()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
push = airship.create_push
push.audience = UA.or( UA.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5'))
push.notification = UA.notification(alert: 'Hello!')
push.device_types = UA.device_types(['ios'])
push.send_pushHTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
"push_ids": [
"9d78a53b-b16a-c58f-b78d-181d5e242078"
]
}Example Push with Localizations
POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"device_types": [ "ios", "android" ],
"audience": {
"tag": "needs_a_greeting",
"group": "new_customer"
},
"notification": {
"alert": "Hi!"
},
"localizations": [
{
"language": "de",
"country": "AT",
"notification": {
"alert": "Grüss Gott"
}
},
{
"language": "de",
"country": "DE",
"notification": {
"alert": "Guten Tag"
}
}
]
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
Localization localization = Localization.newBuilder()
.setCountry("AT")
.setLanguage("de")
.setNotification(Notifications.alert("Grüss Gott"))
.build();
PushPayload payload = PushPayload.newBuilder()
.setAudience(Selectors.or(Selectors.tagWithGroup("needs_a_greeting", "new_customer")))
.addLocalization(localization)
.setNotification(Notifications.alert("Hi!"))
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
.build();
PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
push = airship.create_push
push.audience = UA.tag("needs_a_greeting", group:'new_customer')
push.notification = UA.notification(alert: 'Hi!')
push.device_types = UA.device_types(['ios'])
push.localizations = {
"language": "de",
"country": "AT",
"notification": {
"alert": "Grüss Gott"
}
}
push.send_pushHTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
"push_ids": [
"9d78a53b-b16a-c58f-b78d-181d5e242078",
"1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6",
"939c3796-a755-413b-a36b-3026b1f92df8"
],
"localized_ids": [
"1a38a2ba-c174-d32f-d01b-481a5d241934"
]
}This operation is not currently supported by the Python Library.POST /api/push
Send a push notification to a specified audience. The body of the request must be a Push Object or an array of Push Objects.
Security:
Request Body
A single push object or an array of push objects.
Content-Type: application/json
One ofPush Object
A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.
Array of Push Objects. : Array [Push Object]
Max items: 100 Min items: 1
Responses
202
The push notification has been accepted for processing. The response contains
push_id,message_id, and/orcontent_urlarrays based on the type of push.RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
A push response contains a list of identifiers for the notifications sent in the request.
OBJECT PROPERTIEScontent_urls : Array [String]
An array of URLs where the push payload contains a landing page action. Max items: 100
localized_ids : Array [String]
An array of identifiers used for reporting. Each ID represents a localized message (push object with
localizationsarray).message_ids : Array [String]
An array of message IDs, each uniquely identifying a Message Center message.
ok : Boolean
Success.
operation_id : String
A unique string identifying the operation, useful for reporting and troubleshooting. Format:
uuidpush_ids : Array [String]
An array of push IDs, each uniquely indentifying a push. Max items: 100 Min items: 1
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
The request included a payload larger than the maximum size of 5MiB.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Validate Push
Example
POST /api/push/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
},
"notification": {
"alert": "Hello!"
},
"device_types": [ "ios" ]
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
PushPayload payload = PushPayload.newBuilder()
.setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
.setNotification(Notifications.alert("Hello!"))
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
.build();
PushRequest request = PushRequest.newRequest(payload).setValidateOnly(true);
Response<PushResponse> response = client.execute(request);HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.POST /api/push/validate
Accept the same range of payloads as POSTing to /api/push, but parse and validate only, without sending any pushes. The body of the request must be a Push Object or an array of Push Objects.
Security:
Request Body
A single push object or an array of push objects.
Content-Type: application/json
One ofPush Object
A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.
Array of Push Objects. : Array [Push Object]
Max items: 100 Min items: 1
Responses
200
Everything worked as expected.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
The request included a payload larger than the maximum size of 5MiB.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Delete Message from Inbox
Example
DELETE /api/user/messages/(push_id) HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.DELETE /api/user/messages/{push_id}
Delete a Message Center message completely, removing it from every user’s inbox. This is an asynchronous call; a success response means that the deletion has been queued for processing.
This delete call will work with either the message_id or the push_id of the accompanying push notification.
This endpoint will not work with a group_id from an automated message or a push to local time delivery. To delete a rich message that was part of an automated or local time delivery, you must use the relevant push_id from the operation.
For time-sensitive messages you should consider including an expiry time, as detailed in the In-App Message Object. Setting an expiry value will prevent you from having to manually remove messages.
Security:
path PARAMETERSpush_id : String Required
The
push_idormessage_idof the Rich Message you want to delete from users` inboxes.Format:
uuid
Responses
202
The request has been accepted for processing.
RESPONSE BODYContent-Type: application/json
Returned with 2xx Responses. At a minimum, 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
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Schedules
Schedule notifications.
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
GET /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
ScheduleListingRequest request = ScheduleListingRequest.newRequest();
Response<ListAllSchedulesResponse> response = client.execute(request);
List<SchedulePayloadResponse> schedules = response.getBody().get().getSchedules();import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
for schedule in ua.ScheduledList(airship):
print(
schedule.name, schedule.url, schedule.push_ids,
schedule.schedule, schedule.push
)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
scheduled_push_list = UA::ScheduledPushList.new(client: airship)
scheduled_push_list.each do |schedule|
puts(schedule)
endHTTP/1.1 200 OK
Count: 2
Data-Attribute: schedules
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"count": 2,
"total_count": 4,
"next_page": "https://go.urbanairship.com/api/schedules/?start=5c69320c-3e91-5241-fad3-248269eed104&limit=2&order=asc",
"schedules": [
{
"url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
"schedule": { },
"push": { }
},
{
"url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed10A",
"schedule": { },
"push": { }
}
]
}GET /api/schedules
List all existing schedules. Returns an array of schedule objects in the schedules attribute.
Security:
query PARAMETERSstart : String
An optional string ID of the starting element for paginating results.
limit : Integer
An optional integer as maximum number of elements to return.
Responses
200
Returned on success, with the JSON representation of the scheduled pushes in the body of the response.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIEScount : Integer
next_page : String
There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results. Format:
urlok : Boolean
Success.
schedules : Array [Schedule Object]
An array of Schedule Objects.
total_count : Integer
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Schedule a Notification
Example
POST /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
[
{
"name": "Morning People",
"schedule": {
"scheduled_time": "2020-06-03T09:15:00"
},
"push": {
"audience": { "tag": "earlyBirds" },
"notification": { "alert": "Good Day Sunshine" },
"device_types": [ "ios", "android" ]
}
},
{
"name": "Everybody Else",
"schedule": {
"best_time": {
"send_date": "2020-06-03"
}
},
"push": {
"audience": { "tag": "normalPeople" },
"notification": { "alert": "Stay Up Late" },
"device_types": [ "ios", "android" ]
}
}
]UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
SchedulePayload schedulePayload = SchedulePayload.newBuilder()
.setName("Morning People")
.setSchedule(Schedule.newBuilder()
.setScheduledTimestamp(DateTime.parse("2020-06-03T09:15:00Z"))
.build())
.setPushPayload(PushPayload.newBuilder()
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
.setNotification(Notifications.alert("Good Day Sunshine"))
.setAudience(Selectors.tag("earlyBirds"))
.build())
.build();
ScheduleRequest scheduleRequest = ScheduleRequest.newRequest(schedulePayload);
Response<ScheduleResponse> response = client.execute(scheduleRequest);import datetime
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
sched = airship.create_scheduled_push()
sched.name = 'Morning People'
sched.schedule = ua.scheduled_time(
datetime.datetime.utcnow() + datetime.timedelta(minutes=60)
)
sched.push = airship.create_push()
sched.push.audience = ua.tag('earlyBirds')
sched.push.notification = ua.notification(alert='Good Day Sunshine')
sched.push.device_types = ['ios', 'android']
sched.send()
response = sched.send()
print ('Created schedule. URL:', response.schedule_url)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
push = airship.create_push
push.audience = UA.tag('earlyBirds')
push.notification = UA.notification(alert: 'Morning People')
push.device_types = UA.device_types(['ios','android'])
schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "Morning People"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)Example schedule with localizations
POST /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
[
{
"name": "Greetings",
"schedule": {
"best_time": {
"send_date": "2020-11-15"
}
},
"push": {
"device_types": [
"ios",
"android"
],
"audience": {
"tag": "needs_a_greeting",
"group": "new_customer"
},
"notification": {
"alert": "Hi!"
},
"localizations": [
{
"language": "de",
"country": "AT",
"notification": {
"alert": "Grüss Gott"
}
},
{
"language": "de",
"country": "DE",
"notification": {
"alert": "Guten Tag"
}
}
]
}
}
]UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
Localization one = Localization.newBuilder()
.setCountry("AT")
.setLanguage("de")
.setNotification(Notifications.alert("Grüss Gott"))
.build();
Localization two = Localization.newBuilder()
.setCountry("DE")
.setLanguage("de")
.setNotification(Notifications.alert("Guten Tag"))
.build();
SchedulePayload schedulePayload = SchedulePayload.newBuilder()
.setName("Greetings")
.setSchedule(Schedule.newBuilder()
.setBestTime(BestTime.newBuilder()
.setSendDate(DateTime.parse("2020-11-15T00:00:00Z"))
.build())
.build())
.setPushPayload(PushPayload.newBuilder()
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
.setNotification(Notifications.alert("Hi!"))
.setAudience(Selectors.tagWithGroup("needs_a_greeting", "new_customer"))
.addLocalization(one)
.addLocalization(two)
.build())
.build();
ScheduleRequest scheduleRequest = ScheduleRequest.newRequest(schedulePayload);
Response<ScheduleResponse> response = client.execute(scheduleRequest);require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
push = airship.create_push
push.audience = UA.tag('needs_a_greeting', group:'new_customer')
push.notification = UA.notification(alert: 'Hi!')
push.device_types = UA.device_types(['ios', 'android'])
push.localizations = {
"language": "de",
"country": "AT",
"notification": {
"alert": "Grüss Gott"
}
}
schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "Greetings"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)HTTP/1.1 201 Created
Data-Attribute: schedule_urls
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
"schedule_urls": [
"https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
"https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
],
"schedule_ids": [
"eac2ace6-349a-41a2-b874-5496d7bf0100",
"6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
],
"schedules": [
{
"url": "https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
"schedule": {
"scheduled_time": "2020-06-03T09:15:00"
},
"name": "Morning People",
"push": {
"audience": { "tag": "earlyBirds" },
"notification": { "alert": "Good Day Sunshine" },
"device_types": [ "ios", "android" ]
},
"push_ids": [ "83046227-9b06-4114-9f23-0df349792bbd" ]
}
{
"url": "https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e",
"schedule": {
"best_time": {
"send_date": "2020-06-03"
}
},
"name": "Everybody Else",
"push": {
"audience": { "tag": "normalPeople" },
"notification": { "alert": "Stay Up Late" },
"device_types": [ "ios", "android" ]
},
"push_ids": [ "8438e81-bb31-82a9-5feb-e7fd5b21ca7e" ]
}
]
}This operation is not currently supported by the Python Library.POST /api/schedules
Scheduled notifications are created by POSTing to the schedule URI. The body of the request must be one of a single schedule object or an array of one or more schedule objects.
Security:
Request Body
A single schedule object or an array of schedule objects.
Content-Type: application/json
One ofArray [Schedule Object]
Schedule Object
A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.
Responses
201
The response body will contain an array of response objects with the created resource URIs.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
Success.
operation_id : String
A unique string which identifies a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs. Format:
uuidschedule_ids : Array [String]
An array of schedule IDs, each string uniquely identifying a schedule. Max items: 100 Min items: 1
schedule_urls : Array [String]
An array of schedule URLs. Max items: 100
schedules : Array [Schedule Object]
An array of schedule objects.
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
The number of schedules in the array exceeded the maximum amount (error_code 41301). The request included a payload larger than the maximum size of 5MiB. (error_code 41307)
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
List a Specific Schedule
Example
GET /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
ScheduleListingRequest request = ScheduleListingRequest.newRequest("5cde3564-ead8-9743-63af-821e12337812");
Response<ListAllSchedulesResponse> response = client.execute(request);
SchedulePayloadResponse schedule = response.getBody().get().getSchedules().get(0);
// Get the schedule's name
Optional<String> name = schedule.getName();
// Get the push IDs
Set<String> pushIds = schedule.getPushIds();
// Get the scheduled time
Schedule sched = schedule.getSchedule();
// Get the associated push payload
PushPayload payload = schedule.getPushPayload();
// Get the URL
Optional<String> url = schedule.getUrl();require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
schedule = airship.create_scheduled_push
scheduled_push = UA::ScheduledPush.new(airship)
schedule_details = scheduled_push.list(schedule_id: '5cde3564-ead8-9743-63af-821e12337812')
puts(schedule_details)HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"name": "I would like to subscribe to your newsletter",
"schedule": {
"scheduled_time": "2020-04-01T18:45:30"
},
"push": {
"audience": {
"tag": [
"intriguing",
"ideas" ]
},
"notification": {
"alert": "Check your inbox!"
},
"device_types": [ "ios", "android" ]
}
}This operation is not currently supported by the Python Library.GET /api/schedules/{schedule_id}
Fetch the current definition of a single schedule resource. Returns a single schedule object.
Security:
path PARAMETERSschedule_id : String Required
The ID of a schedule.
Responses
200
Returned on success, with the JSON representation of the scheduled push in the body of the response.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Update Schedule
Example
PUT /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "I would like to subscribe to your newsletter",
"schedule": {
"scheduled_time": "2020-04-01T18:45:30"
},
"push": {
"audience": {
"tag": [
"intriguing",
"ideas",
"thought_leadership"
]
},
"notification": {
"alert": "Check your inbox!"
},
"device_types": [ "ios", "android" ]
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
SchedulePayload schedulePayload = SchedulePayload.newBuilder()
.setName("I would like to subscribe to your newsletter")
.setSchedule(Schedule.newBuilder()
.setScheduledTimestamp(DateTime.parse("2020-04-01T18:45:00Z"))
.build())
.setPushPayload(PushPayload.newBuilder()
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
.setNotification(Notifications.alert("Check your inbox!"))
.setAudience(Selectors.tag("intriguing"))
.build())
.build();
ScheduleRequest scheduleRequest = ScheduleRequest.newUpdateRequest(schedulePayload, "5cde3564-ead8-9743-63af-821e12337812");
Response<ScheduleResponse> response = client.execute(scheduleRequest);import datetime
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
schedule = ua.ScheduledPush.from_url(airship, 'https://go.urbanairship.com/api/schedules/5cde3564-ead8-9743-63af-821e12337812')
# change scheduled time to tomorrow
schedule.schedule = ua.scheduled_time(
datetime.datetime.utcnow() + datetime.timedelta(days=1))
resp = schedule.update()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
schedule = airship.create_scheduled_push
schedule = UA::ScheduledPush.from_url(client: airship, url: 'https://go.urbanairship.com/api/schedules/5cde3564-ead8-9743-63af-821e12337812')
# change scheduled time to tomorrow
schedule.schedule = UA.scheduled_time(Time.now.utc + (60 * 60 * 24))
schedule.updateHTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "7c56d013-5599-d66d-6086-6205115d85e2",
"schedule_urls": [ "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e" ],
"schedules": [
{
"url": "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e",
"schedule": {
"scheduled_time": "2020-04-01T18:45:30"
},
"name": "I would like to subscribe to your newsletter",
"push": {
"audience": {"tag": ["intriguing", "ideas", "thought_leadership"] },
"notification": {"alert": "Check your inbox!"},
"device_types": [ "ios", "android" ]
},
"push_ids": [ "48fb8e8a-ee51-4e2a-9a47-9fab9b13d846" ]
}
]
}PUT /api/schedules/{schedule_id}
Update the state of a single schedule resource. The body must contain a single schedule object. A PUT cannot be used to create a new schedule; it can only be used to update an existing one.
Security:
path PARAMETERSschedule_id : String Required
The ID of a schedule.
Request Body
A single schedule object.
Content-Type: application/json
Schedule Object
A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.
Responses
200
Returned if the scheduled push has been successfully updated.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
Success.
operation_id : String
A unique string which identifies a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs. Format:
uuidschedule_urls : Array [String]
An array of schedule URLs. Max items: 100
schedules : Array [Schedule Object]
An array of schedule objects.
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
The request included a payload larger than the maximum size of 5MiB.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Delete Schedule
Example
DELETE /api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
ScheduleDeleteRequest request = ScheduleDeleteRequest.newRequest("b384ca54-0a1d-9cb3-2dfd-ae5964630e66");
Response<String> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
schedule = ua.ScheduledPush.from_url(airship, 'https://go.urbanairship.com/api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66')
# Cancel schedule
schedule.cancel()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
schedule = airship.create_scheduled_push
schedule = UA::ScheduledPush.from_url(client: airship, url: 'https://go.urbanairship.com/api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66')
schedule.cancelHTTP/1.1 204 No ContentDELETE /api/schedules/{schedule_id}
Delete a schedule resource, which will result in no more pushes being sent. If the resource is successfully deleted, the response does not include a body.
Security:
path PARAMETERSschedule_id : String Required
The ID of a schedule.
Responses
204
The delete operation was successful.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Pause a schedule
Example
POST /api/schedules/5cde3564-ead8-9743-63af-821e12337812/pause HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.POST /api/schedules/{schedule_id}/pause
Pause a recurring scheduled message, preventing Airship from sending messages on a recurring scheduled message interval. Use the /resume endpoint to resume a schedule.
Paused schedules bear a "paused": true boolean.
Security:
path PARAMETERSschedule_id : String Required
The ID of the schedule you want to pause.
Request Body
A pause request is empty.
Content-Type: application/json
Object
Responses
204
The pause operation was successful.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
500
Occurs if a schedule fails to pause. The error includes a list of
failed_triggers, detailing the schedule triggers that caused this operation to failRESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESerror : String
A description of the error.
error_code : Integer
An error code representing the HTTP status and a more specific Airship error, if known.
failed_triggers : Array [Object]
ARRAY ITEM- OBJECT PROPERTIES
id : String
The list of failed schedule triggers Format:
uuidstate : String
The reason that the operation failed. Possible values:
BLOCKED,FAILED
- OBJECT PROPERTIES
ok : Boolean
If false, an error occurred.
Resume a schedule
Example
POST /api/schedules/5cde3564-ead8-9743-63af-821e12337812/resume HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.POST /api/schedules/{schedule_id}/resume
Resume a recurring schedule that you previously paused, beginning with the next scheduled interval.
Paused schedules bear a "paused": true boolean.
Security:
path PARAMETERSschedule_id : String Required
The ID of the schedule you want to resume.
Request Body
A resume request is empty.
Content-Type: application/json
Object
Responses
204
The operation was successful.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
500
Occurs if a schedule fails to resume. The error includes a list of
failed_triggers, detailing the specific schedule IDs that caused the operation to fail.RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESerror : String
A description of the error.
error_code : Integer
An error code representing the HTTP status and a more specific Airship error, if known.
failed_triggers : Array [Object]
ARRAY ITEM- OBJECT PROPERTIES
id : String
The list of failed schedule triggers Format:
uuidstate : String
The reason that the operation failed. Possible values:
BLOCKED,FAILED
- OBJECT PROPERTIES
ok : Boolean
If false, an error occurred.
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
GET /api/pipelines/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
for automation in ua.Automation(airship).list_automations():
print(automation)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
automation = UA::Automation.new(client: airship)
automation.limit = 5
automation.list_automationsHTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"pipelines": [
{
"creation_time": "2020-03-20T18:37:23",
"enabled": true,
"immediate_trigger": {
"tag_added": { "tag": "bought_shoes" }
},
"last_modified_time": "2020-03-20T19:35:12",
"name": "Shoe buyers",
"outcome": {
"push": {
"audience": "triggered",
"device_types": [ "android" ],
"notification": { "alert": "So you like shoes, huh?" }
}
},
"status": "live",
"uid": "3987f98s-89s3-cx98-8z89-89adjkl29zds",
"url": "https://go.urbanairship.com/api/pipelines/3987f98s-89s3-cx98-8z89-89adjkl29zds"
},
{
"..."
}
]
}This operation is not currently supported by the Java Library.GET /api/pipelines
List existing pipelines. Pipelines are ordered by creation_date from newest to oldest.
Security:
query PARAMETERSlimit : Integer
The maximum number of results to return; this is effectively the page size for the response.
Min: 1
enabled : Boolean
If true, limits the listing to enabled pipelines (
"enabled": true). If false or ommitted, lists all pipelines, whetherenabledistrueorfalse.offset : Integer
The first result you want to return. This parameter assists in pagination.
Responses
200
Returned on success, with a JSON representation of pipelines matching your query parameters.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
The response body for a pipelines request.
OBJECT PROPERTIESnext_page : String
An 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 : Boolean
Success.
operation_id : String
A unique string identifying a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs. Format:
uuidpipeline_ids : Array [String]
An array of pipeline IDs.
pipeline_urls : Array [String]
An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.
pipelines : Array [Pipeline Object]
A list of pipeline objects.
prev_page : String
An URI that points to the previous page of pipelines. The page size is specified by the
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 : Integer
The total count of pipelines.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Create Pipeline (Automated Message)
Example
POST /api/pipelines HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name":"The Darkest Pipeline",
"enabled":true,
"immediate_trigger":"first_open",
"outcome":{
"push":{
"audience":"triggered",
"device_types":[
"ios",
"android",
"web"
],
"notification":{
"alert":"Cool goatee, Abed"
}
}
},
"timing":{
"delay":{
"seconds":7200
},
"schedule":{
"type":"local",
"miss_behavior":"wait",
"dayparts":[
{
"days_of_week":[
"thursday"
],
"allowed_times":[
{
"preferred":"21:30:00"
}
]
}
]
}
}
}import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
automation = ua.Automation(airship)
pipeline = ua.Pipeline(
name='The Darkest Pipeline',
enabled=True,
immediate_trigger=['first_open'],
outcome={
'audience': 'triggered',
'device_types': ua.device_types('ios', 'android', 'web'),
'notification': ua.notification(alert='Cool goatee, Abed')
},
timing={
delay': {'seconds': 7200},
'schedule': {
'type': 'local',
'miss_behavior': 'wait',
'dayparts': [{
'days_of_week': ['thursday'],
'allowed_times': [
{'preferred': '21:30:00'}
]
}]
}
}
)
response = automation.create(pipeline.payload)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = "first_open"
pipeline.outcome = {
"push": {
"audience": "triggered",
"device_types": ['ios','android','web'],
"notification": {
"alert": "Cool goatee, Abed"
}
}
}
automation = UA::Automation.new(client: airship)
automation.pipeline_object = pipeline.payload
details = automation.create_automation
puts(details)HTTP/1.1 201 Created
Content-Length: 123
Data-Attribute: pipeline_urls
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
"pipeline_urls": [
"https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
]
}This operation is not currently supported by the Java Library.POST /api/pipelines
Create one or more pipelines. You can provide a single pipeline object or an array of pipeline objects.
Security:
Request Body
A single pipeline object or an array of pipeline objects.
Content-Type: application/json
One ofPipeline 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.Array [Pipeline Object]
Responses
201
If creating more than one pipeline, pipeline URIs are returned in the same order as the pipeline objects in the request.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
The response body for a pipelines request.
OBJECT PROPERTIESnext_page : String
An 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 : Boolean
Success.
operation_id : String
A unique string identifying a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs. Format:
uuidpipeline_ids : Array [String]
An array of pipeline IDs.
pipeline_urls : Array [String]
An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.
pipelines : Array [Pipeline Object]
A list of pipeline objects.
prev_page : String
An URI that points to the previous page of pipelines. The page size is specified by the
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 : Integer
The total count of pipelines.
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.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
409
The application has exceeded the maximum number of active or total pipelines. In order to increase pipeline maximum, contact Airship Support.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
The request included a payload larger than the maximum size of 5MiB.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
List Deleted Pipelines
Example
GET /api/pipelines/deleted/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
response = ua.Automation(airship).list_deleted_automations()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
automation = UA::Automation.new(client: airship)
automation.start = 2020-11-23
automation.list_deleted_automationsHTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"pipelines": [
{
"deletion_time": "2020-03-31T20:54:45",
"pipeline_id": "0sdicj23-fasc-4b2f-zxcv-0baf934f0d69"
},
{
"..."
}
]
}This operation is not currently supported by the Java Library.GET /api/pipelines/deleted
Produces a list of all deleted pipelines starting with the most recently deleted entry.
Security:
query PARAMETERSstart : String
Timestamp of the starting element for paginating results.
Responses
200
Returns an array of deleted pipeline objects.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
Success.
pipelines : Array [Object]
ARRAY ITEM- OBJECT PROPERTIES
deletion_time : String
An ISO 8601 UTC timestamp indicating the date and time that the pipeline was deleted.
pipeline_id : String
The unique identifier for a pipeline. Format:
uuid
- OBJECT PROPERTIES
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Validate Pipeline
Example
POST /api/pipelines/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name":"The Darkest Pipeline",
"enabled":true,
"immediate_trigger":"first_open",
"outcome":{
"push":{
"audience":"triggered",
"device_types":[
"ios",
"android"
],
"notification":{
"alert":"Cool goatee, Abed"
}
}
},
"timing":{
"delay":{
"seconds":7200
},
"schedule":{
"type":"local",
"miss_behavior":"wait",
"dayparts":[
{
"days_of_week":[
"thursday"
],
"allowed_times":[
{
"preferred":"21:30:00"
}
]
}
]
}
}
}import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
automation = ua.Automation(airship)
pipeline = ua.Pipeline(
name='The Darkest Pipeline',
enabled=True,
immediate_trigger=['first_open'],
outcome={
'audience': 'triggered',
'device_types': ua.device_types('ios', 'android', 'web'),
'notification': ua.notification(alert='Cool goatee, Abed')
},
timing={
delay': {'seconds': 7200},
'schedule': {
'type': 'local',
'miss_behavior': 'wait',
'dayparts': [{
'days_of_week': ['thursday'],
'allowed_times': [
{'preferred': '21:30:00'}
]
}]
}
}
)
response = automation.validate(pipeline.payload)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = "first_open"
pipeline.outcome = {
"push": {
"audience": "triggered",
"device_types": ['ios','android','web'],
"notification": {
"alert": "Cool goatee, Abed"
}
}
}
automation = UA::Automation.new(client: airship)
automation.pipeline_object = pipeline.payload
automation.validate_automationHTTP/1.1 200 OK
Content-Length: 11
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}This operation is not currently supported by the Java Library.POST /api/pipelines/validate
This endpoint accepts the same range of payloads as a POST to /api/pipelines, but only parses and validates the payload, without creating the pipeline. The body of the request must be a single pipeline object or an array of pipeline objects.
Security:
Request Body
A single pipeline object or an array of pipeline objects.
Content-Type: application/json
One ofPipeline 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.Array of Push Templates : Array [Pipeline Object]
Responses
200
Everything worked as expected.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
The request included a payload larger than the maximum size of 5MiB.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Individual Pipeline Lookup
Example
GET /api/pipelines/4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
response = ua.Automation(airship).lookup('4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4')require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
automation = UA::Automation.new(client: airship)
automation.pipeline_id = '4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4'
automation.lookup_automationHTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"pipeline": {
"creation_time": "2020-02-14T19:19:19",
"enabled": true,
"immediate_trigger": { "tag_added": "new_customer" },
"last_modified_time": "2020-03-01T12:12:54",
"name": "New customer",
"outcome": {
"push": {
"audience": "triggered",
"device_types": [ "ios", "android" ],
"notification": { "alert": "Hello new customer!" }
}
},
"status": "live",
"uid": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
"url": "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
}
}This operation is not currently supported by the Java Library.GET /api/pipelines/{pipeline_id}
Fetch a single pipeline resource. Returns an array containing a single pipeline object in the pipelines attribute.
Security:
path PARAMETERSpipeline_id : String Required
The pipeline you want to return or modify.
Responses
200
Returned on success, with the JSON representation of the pipeline in the body of the response.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
The response body for a pipelines request.
OBJECT PROPERTIESnext_page : String
An 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 : Boolean
Success.
operation_id : String
A unique string identifying a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs. Format:
uuidpipeline_ids : Array [String]
An array of pipeline IDs.
pipeline_urls : Array [String]
An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.
pipelines : Array [Pipeline Object]
A list of pipeline objects.
prev_page : String
An URI that points to the previous page of pipelines. The page size is specified by the
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 : Integer
The total count of pipelines.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Update Pipeline
Example
PUT /api/pipelines/0f927674-918c-31ef-51ca-e96fdd234da4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json;
{
"enabled": true,
"immediate_trigger": {
"tag_added": "new_customer"
},
"outcome": {
"push": {
"audience": "triggered",
"device_types": [
"ios"
],
"notification": {
"alert": "Hello new customer!"
}
}
}
}import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
automation = ua.Automation(airship)
pipeline = ua.Pipeline(
enabled=True,
immediate_trigger={
'tag_added': 'new_customer'
},
outcome={
'audience': 'triggered',
'device_types': ua.device_types('ios'),
'notification': ua.notification(alert='Hello new customer!')
}
)
response = automation.update(
pipeline_id='0f927674-918c-31ef-51ca-e96fdd234da4',
pipeline=pipeline.payload
)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = {
"tag_added": {
"tag": "new_customer",
"group": "crm"
}
}
pipeline.outcome = {
"push": {
"audience": "triggered",
"device_types": ["ios"],
"notification": {
"alert": "Hello new customer!"
}
}
}
automation = UA::Automation.new(client: airship)
automation.pipeline_id = '0f927674-918c-31ef-51ca-e96fdd234da4'
automation.pipeline_object = pipeline.payload
automation.update_automationHTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}This operation is not currently supported by the Java Library.PUT /api/pipelines/{pipeline_id}
Update the state of a single pipeline resource. You must include the complete payload from a POST response, with changes you want to make to the resource. You cannot provide a partial payload. If you omit optional fields during this operation that were already set for the pipeline, they will be nullified.
Security:
path PARAMETERSpipeline_id : String Required
The pipeline you want to return or modify.
Request Body
A single pipeline object or an array of pipeline objects.
Content-Type: application/json
Pipeline Object
A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of
immediate_triggerorhistorical_triggermust be supplied.
Responses
200
Everything worked as expected.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
409
The application has exceeded the maximum number of active or total pipelines. In order to increase pipeline maximum, contact Airship Support.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
413
The request included a payload larger than the maximum size of 5MiB.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Delete Pipeline
Example
DELETE /api/pipelines/0f927674-918c-31ef-51ca-e96fdd234da4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
response = ua.Automation(airship).delete('0f927674-918c-31ef-51ca-e96fdd234da4')require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
automation = UA::Automation.new(client: airship)
automation.pipeline_id = '0f927674-918c-31ef-51ca-e96fdd234da4'
automation.delete_automationHTTP/1.1 204 No ContentThis operation is not currently supported by the Java Library.DELETE /api/pipelines/{pipeline_id}
Delete a pipeline.
Security:
path PARAMETERSpipeline_id : String Required
The pipeline you want to return or modify.
Responses
204
An API request was successful, but there is no response body to return.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
A/B Tests
Create A/B Tests using the /api/experiments endpoint. An experiment or A/B test is a set of distinct push notification variants sent to subsets of an audience. You can create up to 26 notification variants and send each variant to an audience subset.
Experiment Listing
Example
GET /api/experiments HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
ab_test = ua.ABTest(airship)
response = ab_test.list_experiments()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
ab_test = UA::AbTest.new(client: airship)
ab_test.limit = 5
ab_test.list_ab_testHTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiments
Count: 2
Total-Count: 2
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"count" : 2,
"total_count" : 2,
"experiments" : [{
"name" : "Experiment 1",
"control" : 0.33,
"audience" : "all",
"device_types": [ "ios", "android" ],
"variants" : [{
"push" : {
"notification" : {
"alert" : "message 1"
}
},
"id" : 0,
},
{
"push" : {
"notification" : {
"alert" : "message 2"
}
},
"id" : 1,
}],
"id" : "b5bc3dd1-9ea4-4208-b5f1-9e7ac3fe0502",
"created_at" : "2020-03-03T21:08:05",
"push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
}, {
"name" : "Experiment 2",
"description" : "The second experiment",
"audience" : "all",
"device_types": [ "ios", "android" ],
"variants" : [{
"push" : {
"notification" : {
"alert" : "message 1"
}
},
"id" : 0,
},
{
"push" : {
"notification" : {
"alert" : "message 2"
}
},
"id" : 1,
}],
"id" : "e464aa7e-be40-4994-a290-1bbada7187d8",
"created_at" : "2020-03-03T21:08:05",
"push_id" : "07cec298-6b8c-49f9-8e03-0448a06f4aac"
}]
}This operation is not currently supported by the Java Library.GET /api/experiments
List experiments, sorted by created_at date/time from newest to oldest. Responses are paginated. Use optional limit and offset parameters to navigate results.
Security:
query PARAMETERSlimit : Integer
Positive maximum number of elements to return per page. The default
limitis 10 entries with a maximum of 100 entries.Max: 100 Min: 1
offset : Integer
A zero-based integer offset into the result set. If you do not use an offset, results will begin with the most recently sent experiment. If
offsetis greater than the number of queryable experiments, an empty result will be returned.
Responses
200
Returned on success, with the JSON representation of the experiments in the body of the response.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIEScount : Integer
The number of items returned in this page of results.
experiments : Array [Experiment Object]
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 : String
A relative URL leading to the next page of results. If there are no more results, next_page is absent.
ok : Boolean
If true, the call was successful.
total_count : Integer
The total number of results.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Create Experiment (A/B Test)
Example
POST /api/experiments HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "Experiment 1",
"audience": {"tag": "earlyBirds"},
"device_types": [ "ios", "android" ],
"variants": [
{
"push": {
"notification": {
"alert": "message 1"
}
}
},
{
"push": {
"notification": {
"alert": "message 2"
}
}
}
]
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
Schedule schedule = Schedule.newBuilder()
.setScheduledTimestamp(DateTime.now().plusMinutes(5))
.build();
Variant variantOne = Variant.newBuilder()
.setPushPayload(VariantPushPayload.newBuilder()
.setNotification(Notification.newBuilder()
.setAlert("message 1")
.build()
)
.build())
.setSchedule(schedule)
.build();
Variant variantTwo = Variant.newBuilder()
.setPushPayload(VariantPushPayload.newBuilder()
.setNotification(Notification.newBuilder()
.setAlert("message 2")
.build()
)
.build())
.setSchedule(schedule)
.build();
Experiment experiment = Experiment.newBuilder()
.setName("Experiment 1")
.setDescription("Testing description")
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
.setAudience(Selectors.tag("earlyBirds"))
.addVariant(variantOne)
.addVariant(variantTwo)
.build();
ExperimentRequest request = ExperimentRequest.newRequest(experiment);
Response<ExperimentResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
push_1 = airship.create_push()
push_1.notification = ua.notification(alert='message 1')
push_2 = airship.create_push()
push_2.notification = ua.notification(alert='message 2')
variants = [
ua.Variant(push=push_1),
ua.Variant(push=push_2)
]
experiment = ua.Experiment(
audience=ua.tag('earlyBirds'),
name='Experiment 1',
device_types=ua.device_types('ios', 'android'),
variants=variants
)
ab_test = ua.ABTest(airship=airship)
response = ab_test.create(experiment=experiment)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
variant_one = UA::Variant.new(client: airship)
variant_one.push = {
"notification": {
"alert": "message 1"
}
}
variant_two = UA::Variant.new(client: airship)
variant_two.push = {
"notification": {
"alert": "message 2"
}
}
experiment = UA::Experiment.new(client: airship)
experiment.name = 'Experiment 1'
experiment.description = 'Example experiment'
experiment.audience = UA.tag('earlyBirds')
experiment.device_types = ['ios','android']
experiment.variants << variant_one.payload
experiment.variants << variant_two.payload
ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_object = experiment.payload
ab_test.create_ab_testHTTP/1.1 201 Created
Content-Length: 123
Location: https://go.urbanairship.com/api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4",
"experiment_id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
"push_id" : "7e13f060-594c-11e4-8ed6-0800200c9a66"
}POST /api/experiments
Create an experiment. The body of the request should consist of a single experiment object. The experiment is processed and sent immediately unless a schedule is present.
Security:
Request Body
Content-Type: application/json
Experiment Object
An experiment object describes an A/B test, including the audience and variant portions.
Responses
201
The experiment was created.
RESPONSE HEADERSLocation : String
The newly created experiment.
Format:
uri
RESPONSE BODYContent-Type: application/json
The response body for an experiment request.
OBJECT PROPERTIESexperiment_id : String
Unique identifier for an experiment. Format:
uuidok : Boolean
If true, the expeiment was successfully created. If false, the expriment was not created.
operation_id : String
A unique string that represents a single API call, used to identify the operation or side-effects in reporting and troubleshooting logs. Format:
uuidpush_id : String
Unique identifier for a push. Format:
uuid
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Scheduled Experiment Listing
Example
GET /api/experiments/scheduled HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
ab_test = UA::AbTest.new(client: airship)
ab_test.list_scheduled_ab_testHTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiments
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": "true",
"count": 2,
"total_count": 2,
"experiments": [
{
"id": "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
"name": "Experiment 1",
"audience": "all",
"device_types": [ "ios", "android" ],
"variants": [
{
"id": 0,
"schedule": {
"scheduled_time": "2020-11-17T20:58:00Z"
},
"push": {
"notification": {
"alert": "message 1"
}
}
},
{
"id": 1,
"schedule": {
"scheduled_time": "2020-11-17T20:58:00Z"
},
"push": {
"notification": {
"alert": "message 2"
}
}
}
]
},
{
"id": "29705c10-5951-11e4-8ed6-0800200c9a66",
"name": "Experiment 2",
"audience": "all",
"device_types": [ "ios", "android" ],
"variants": [
{
"id": 0,
"schedule": {
"scheduled_time": "2020-12-17T20:58:00Z"
},
"push": {
"notification": {
"alert": "message 1"
}
}
},
{
"id": 1,
"schedule": {
"scheduled_time": "2020-12-17T20:58:00Z"
},
"push": {
"notification": {
"alert": "message 2"
}
}
}
]
}
]
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.GET /api/experiments/scheduled
List scheduled experiments in order, from closest to the current date-time to farthest (i.e. the experiments scheduled to occur soonest will appear at the top of the list). Responses are paginated, using optional limit and offset parameters.
Security:
query PARAMETERSlimit : Integer
Positive maximum number of elements to return per page. The default
limitis 10 entries with a maximum of 100 entries.Max: 100 Min: 1
offset : Integer
A zero-based integer offset into the result set. If you do not use an offset, results will begin with experiment scheduled to begin at the soonest date-time. If the
offsetis greater than the number of queryable experiments, the result set will be empty.
Responses
200
Returned on success, with the JSON representation of the experiments in the body of the response.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIEScount : Integer
The number of items in this page of results.
experiments : Array [Experiment Object]
Experiments listed by
scheduled_timein ascending time order. The number of objects will never exceed thelimitspecified in the request.next_page : String
A relative URL leading to the next page of results. If there are no more results, next_page is absent.
ok : Boolean
If true, the operation completed successfully and returns an expected result set.
total_count : Integer
The total number of results.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Delete Experiment
Example
DELETE /api/experiments/scheduled/0f7704e9-5dc0-4f7d-9964-e89055701b0a HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
ExperimentDeleteRequest request = ExperimentDeleteRequest.newRequest("0f7704e9-5dc0-4f7d-9964-e89055701b0a");
Response<ExperimentResponse> response = client.execute(request);require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_id = '0f7704e9-5dc0-4f7d-9964-e89055701b0a'
ab_test.delete_ab_testHTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}This operation is not currently supported by the Python Library.DELETE /api/experiments/scheduled/{experiment_id}
Delete a scheduled experiment. You can only delete experiments before they start; attempting to delete an experiment that has already started or completed will return an HTTP 405 response (“Method not allowed”).
Security:
path PARAMETERSexperiment_id : String Required
The unique identifier of the experiment.
Responses
200
Returned if the experiment has been succesfully deleted.
RESPONSE BODYContent-Type: application/json
The response body for a pipelines deletion request.
OBJECT PROPERTIESok : Boolean
Success.
operation_id : String
A unique string that represents a single API call, used to identify the operation or side-effects in reporting and troubleshooting logs. Format:
uuid
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
405
Experiments can only be deleted before they start; afterwards, a HTTP 405 is returned.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Validate Experiment
Example
POST /api/experiments/validate HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "Experiment 1",
"audience": {"tag": "earlyBirds"},
"device_types": [ "ios", "android" ],
"variants": [
{
"push": {
"notification": {
"alert": "message 1"
}
}
},
{
"push": {
"notification": {
"alert": "message 2"
}
}
}
]
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
Schedule schedule = Schedule.newBuilder()
.setScheduledTimestamp(DateTime.now().plusMinutes(5))
.build();
Variant variantOne = Variant.newBuilder()
.setPushPayload(VariantPushPayload.newBuilder()
.setNotification(Notification.newBuilder()
.setAlert("message 1")
.build()
)
.build())
.setSchedule(schedule)
.build();
Variant variantTwo = Variant.newBuilder()
.setPushPayload(VariantPushPayload.newBuilder()
.setNotification(Notification.newBuilder()
.setAlert("message 2")
.build()
)
.build())
.setSchedule(schedule)
.build();
Experiment experiment = Experiment.newBuilder()
.setName("Experiment 1")
.setDescription("Testing description")
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
.setAudience(Selectors.tag("earlyBirds"))
.addVariant(variantOne)
.addVariant(variantTwo)
.build();
ExperimentRequest request = ExperimentRequest.newRequest(experiment).setValidateOnly(true);
Response<ExperimentResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
push_1 = airship.create_push()
push_1.notification = ua.notification(alert='message 1')
push_2 = airship.create_push()
push_2.notification = ua.notification(alert='message 2')
variants = [
ua.Variant(push=push_1),
ua.Variant(push=push_2)
]
experiment = ua.Experiment(
audience=ua.tag('earlyBirds'),
name='Experiment 1',
device_types=ua.device_types('ios', 'android'),
variants=variants
)
ab_test = ua.ABTest(airship=airship)
response = ab_test.validate(experiment=experiment)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
variant_one = UA::Variant.new(client: airship)
variant_one.push = {
"notification": {
"alert": "message 1"
}
}
variant_two = UA::Variant.new(client: airship)
variant_two.push = {
"notification": {
"alert": "message 2"
}
}
experiment = UA::Experiment.new(client: airship)
experiment.name = 'Experiment 1'
experiment.description = 'Example experiment'
experiment.audience = UA.tag('earlyBirds')
experiment.device_types = ['ios','android']
experiment.variants << variant_one.payload
experiment.variants << variant_two.payload
ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_object = experiment.payload
ab_test.validate_ab_testHTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"operation_id" : "03ca94a3-2b27-42f6-be7e-41efc2612cd4"
}POST /api/experiments/validate
Accepts the same range of payloads as /api/experiments, but only parses and validates the payload without creating the experiment. This does the same amount of validation as the creation endpoint, including platform-specific validation, e.g., APNS byte limit checks. While this operation ensures the experiment is technically valid, it does not guarantee that a resulting push will succeed. An experiment may validate and still fail to be delivered. For example, you may have a valid experiment with no devices in your audience.
Security:
Request Body
A single experiment object.
Content-Type: application/json
Experiment Object
An experiment object describes an A/B test, including the audience and variant portions.
Responses
200
The experiment is valid.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESok : Boolean
If true, the operation completed successfully and returns an expected response.
operation_id : String
A unique string that represents a single API call, used to identify the operation or side-effects in reporting and troubleshooting logs. Format:
uuid
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Experiment Lookup
Example
GET /api/experiments/0f7704e9-5dc0-4f7d-9964-e89055701b0a HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3;import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
ab_test = ua.ABTest(airship)
response = ab_test.lookup(experiment_id='0f7704e9-5dc0-4f7d-9964-e89055701b0a')require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
ab_test = UA::AbTest.new(client: airship)
ab_test.experiment_id = '0f7704e9-5dc0-4f7d-9964-e89055701b0a'
ab_test.lookup_ab_testHTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: experiment
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : "true",
"experiment" : {
"id" : "0f7704e9-5dc0-4f7d-9964-e89055701b0a",
"push_id": "d00f07b0-594c-11e4-8ed6-0800200c9a66",
"name" : "Experiment 1",
"audience" : "all",
"device_types": [ "ios", "android" ],
"variants" : [{
"push" : {
"notification" : {
"alert" : "message 1"
}
},
"id" : 0,
},
{
"push" : {
"notification" : {
"alert" : "message 2"
}
},
"id" : 1,
}]
}
}This operation is not currently supported by the Java Library.GET /api/experiments/{experiment_id}
Look up an experiment (A/B Test).
Security:
path PARAMETERSexperiment_id : String Required
The ID of the experiment you want to look up.
Responses
200
Returned on success, with the JSON representation of the experiment in the body of the response.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESexperiment : Experiment Object
An experiment object describes an A/B test, including the audience and variant portions.
ok : Boolean
If true, the operation completed successfully and returns a result set.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Personalization
Use the /templates API to create templates and push templatized notifications.
Consider the /templates API deprecated. You should instead create templates in the Airship dashboard, and send using the /create-and-send or /pipelines APIs.
List Templates
Example
GET /api/templates HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
TemplateListingRequest request = TemplateListingRequest.newRequest();
Response<TemplateListingRequest> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
for template in ua.TemplateList(airship):
print (
template.template_id, template.created_at, template.modified_at,
template.last_used, template.name, template.description,
template.variables, template.push
)HTTP/1.1 200 OK
Data-Attribute: templates
Count: 1
Total-Count: 1
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true,
"count": 1,
"total_count": 1,
"templates": [
{
"id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"created_at": "2020-08-17T11:10:01Z",
"modified_at": "2020-08-17T11:10:01Z",
"last_used": null,
"name": "Welcome Message",
"description": "Our welcome message",
"variables": [
{
"key": "TITLE",
"name": "Title",
"description": "e.g. Mr, Ms, Dr, etc.",
"default_value": ""
},
{
"key": "FIRST_NAME",
"name": "First Name",
"description": "Given name",
"default_value": null
},
{
"key": "LAST_NAME",
"name": "Last Name",
"description": "Family name",
"default_value": null
}
],
"push": {
"notification": {
"alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
}
}
}
],
"next_page": null,
"prev_page": null
}This operation is not currently supported by the Ruby Library.GET /api/templates
List all existing templates. Returns an array of template objects in the templates attribute.
This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.
Security:
query PARAMETERSpage : Integer
Specifies the desired page number. Defaults to 1.
page_size : Integer
Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.
sort : String
Specifies the name of the field you want to sort results by. Defaults to
created_at.Possible values:
created_at,modified_at,last_usedorder : String
The direction of the sort, asc for ascending, and desc for descending. Defaults to asc.
Possible values:
asc,desc
Responses
200
Returned on success, with the JSON representation of the templates in the body of the response.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIEScount : Integer
The number of templates in the current response; this is effectively the page size.
next_page : String
There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results. Format:
urlok : Boolean
Success.
prev_page : String
Link to the previous page, if available. Format:
urltemplates : Array [Template Object]
An array of Template Objects.
total_count : Integer
The total number of templates.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Create Template
Example
POST /api/templates HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "Welcome Message",
"description": "Our welcome message",
"variables": [
{
"key": "TITLE",
"name": "Title",
"description": "e.g. Mr, Ms, Dr, etc.",
"default_value": ""
},
{
"key": "FIRST_NAME",
"name": "First Name",
"description": "Given name",
"default_value": null
},
{
"key": "LAST_NAME",
"name": "Last Name",
"description": "Family name",
"default_value": null
}
],
"push": {
"notification": {
"alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
}
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
TemplateVariable titleVariable = TemplateVariable.newBuilder()
.setKey("TITLE")
.setName("Title")
.setDescription("e.g. Mr, Ms, Dr, etc.")
.setDefaultValue("")
.build();
TemplateVariable firstNameVariable = TemplateVariable.newBuilder()
.setKey("FIRST_NAME")
.setName("First Name")
.setDescription("Given name")
.setDefaultValue(null)
.build();
TemplateVariable lastNameVariable = TemplateVariable.newBuilder()
.setKey("LAST_NAME")
.setName("Last Name")
.setDescription("Family name")
.setDefaultValue("")
.build();
PartialPushPayload partialPushPayload = PartialPushPayload.newBuilder()
.setNotification(Notification.newBuilder()
.setAlert("Hello {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!")
.build()
)
.build();
TemplateRequest request = TemplateRequest.newRequest()
.setName("Welcome Message")
.setDescription("Our welcome message")
.addVariable(titleVariable)
.addVariable(firstNameVariable)
.addVariable(lastNameVariable)
.setPush(partialPushPayload);
Response<TemplateResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
new_template = ua.Template(airship)
new_template.name = 'Welcome Message'
new_template.description = 'Our welcome message'
new_template.variables = [
{
'key': 'TITLE',
'name': 'Title',
'description': 'e.g. Mr., Ms., Dr., etc.',
'default_value': ''
},
{
'key': 'FIRST_NAME',
'name': 'First Name',
'description': 'Given name',
'default_value': None
},
{
'key': 'LAST_NAME',
'name': 'Last Name',
'description': 'Family name',
'default_value': None
}
]
new_template.push = {
'notification': {
'alert': 'Hello {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!'
}
}
new_template.create()
print (new_template.template_id) # To get the template ID for future useHTTP/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"
}This operation is not currently supported by the Ruby Library.POST /api/templates
Create a new template.
This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.
Security:
Request Body
A single template object.
Content-Type: application/json
Template Object
A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.
Responses
201
The template was created.
RESPONSE HEADERSLocation : String
The uri for the template, used for later updates or sends.
Format:
uri
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If
true, the operation completed successfully and returns an expected response.operation_id : String
A unique string identifying the operation, useful for reporting and troubleshooting. Format:
uuidtemplate_id : String
A unique string identifying the template, used to call the template for pushing and other operations. Format:
uuid
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Push to Template
Example
POST /api/templates/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json
{
"device_types": [ "ios" ],
"audience": {
"ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
},
"merge_data": {
"template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"substitutions": {
"FIRST_NAME": "Bob",
"LAST_NAME": "Smith",
"TITLE": ""
}
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
TemplatePushPayload payload = TemplatePushPayload.newBuilder()
.setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
.setMergeData(TemplateSelector.newBuilder()
.setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
.addSubstitution("FIRST_NAME", "Bob")
.addSubstitution("LAST_NAME", "Smith")
.addSubstitution("TITLE", "Mr.")
.build())
.build();
TemplatePushRequest request = TemplatePushRequest.newRequest()
.addTemplatePushPayload(payload);
Response<TemplateResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
push = airship.create_template_push()
push.audience = ua.ios_channel('b8f9b663-0a3b-cf45-587a-be880946e881')
push.device_types = ua.device_types('ios')
push.merge_data = ua.merge_data(
template_id='ef34a8d9-0ad7-491c-86b0-aea74da15161',
substitutions={
'FIRST_NAME': 'Bob',
'LAST_NAME': 'Smith',
'TITLE': ''
}
)
response = push.send()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"
]
}This operation is not currently supported by the Ruby Library.POST /api/templates/push
Send a push notification based on a template to a list of devices. The body of the request must be a single push template payload or an array of one or more push template payloads.
This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.
Security:
Request Body
A single push template payload or an array of push template payloads. Provide an override with any variable that has a null default value. For example, if you created a template with the variable FIRST_NAME, and that variable has null as a default value, you must provide a substitution for FIRST_NAME when pushing to that template.
Content-Type: application/json
One ofPush Template Payload
A push template payload defines a push by overriding the variables defined in a specific Template Object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.
Array of Push Templates : Array [Push Template Payload]
Responses
202
The push notification has been accepted for processing.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If true, the operation completed successfully and returns an expected response.
operation_id : String
A unique string identifying the operation, useful for reporting and troubleshooting. Format:
uuidpush_ids : Array [String]
An array of the push IDs for this operation. Max items: 100 Min items: 1
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Validate A Template
Example
POST /api/templates/push/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json
{
"device_types": [ "ios" ],
"audience": {
"ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
},
"merge_data": {
"template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"substitutions": {
"FIRST_NAME": "Bob",
"LAST_NAME": "Smith",
"TITLE": ""
}
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
TemplatePushPayload payload = TemplatePushPayload.newBuilder()
.setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
.setMergeData(TemplateSelector.newBuilder()
.setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
.addSubstitution("FIRST_NAME", "Bob")
.addSubstitution("LAST_NAME", "Smith")
.addSubstitution("TITLE", "Mr.")
.build())
.build();
TemplatePushRequest request = TemplatePushRequest.newRequest()
.addTemplatePushPayload(payload)
.setValidateOnly(true);
Response<TemplateResponse> response = client.execute(request);HTTP/1.1 200 OK
Content-Length: 123
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true
}This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.POST /api/templates/push/validate
This endpoint accepts the same range of payloads as /api/template/push, but only parses and validates the payload. It does not actually send a push.
Security:
Request Body
A single push template payload or an array of push template payloads.
Content-Type: application/json
One ofPush Template Payload
A push template payload defines a push by overriding the variables defined in a specific Template Object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.
Array [Push Template Payload]
Responses
200
Everything worked as expected.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Schedule a Templated Push
Example
POST /api/templates/schedules HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
[
{
"name": "Hello Bob",
"schedule": {
"scheduled_time": "2020-05-02T22:00:00Z"
},
"device_types": [ "ios" ],
"audience": {
"ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
},
"merge_data": {
"template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"substitutions": {
"FIRST_NAME": "Bob",
"LAST_NAME": "Takahashi",
"TITLE": null
}
}
},
{
"name": "Hello Joe",
"schedule": {
"scheduled_time": "2020-05-05T18:00:00Z"
},
"device_types": [ "android" ],
"audience": {
"android_channel": "df6a6b50-9843-0304-d5a5-743f246a4946"
},
"merge_data": {
"template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"substitutions": {
"FIRST_NAME": "Joe",
"LAST_NAME": "Smith",
"TITLE": "Sir"
}
}
}
]UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
TemplateScheduledPushPayload payload = TemplateScheduledPushPayload.newBuilder()
.setAudience(Selectors.iosChannel("b8f9b663-0a3b-cf45-587a-be880946e881"))
.setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
.setMergeData(TemplateSelector.newBuilder()
.setTemplateId("ef34a8d9-0ad7-491c-86b0-aea74da15161")
.addSubstitution("FIRST_NAME", "Bob")
.addSubstitution("LAST_NAME", "Takahashi")
.addSubstitution("TITLE", "Dr.")
.build())
.setSchedule(Schedule.newBuilder()
.setScheduledTimestamp(DateTime.parse("2020-05-05T18:00:00Z"))
.build())
.build();
TemplateScheduledPushRequest request = TemplateScheduledPushRequest.newRequest()
.addTemplateScheduledPushPayload(payload);
Response<ScheduleResponse> response = client.execute(request);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" ]
}
]
}This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.POST /api/templates/schedules
Schedule a push notification based on a template to a list of devices. Like a standard template-based push, the body of the request includes one or more push template payloads along with a schedule object determining when the template-based push should be sent.
Request Body
an array of scheduled pushes
Content-Type: application/json
Array [Object]
ARRAY ITEMA scheduled push template object defines a push by overriding the variables defined in a specific Template Object and the
OBJECT PROPERTIESscheduledetermining 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.audience : Audience SelectorRequired
The audience for the template.
campaigns : Campaigns Object
An object specifying custom campaign categories related to the notification.
device_types : Array [String]Required
An array containing one or more strings identifying targeted platforms. Accepted platforms are
ios,android,amazon,wns,web,sms,email, andopen::<open_platform_name>(using theopen_platform_namevalue of your open channel). Min items: 1merge_data : ObjectRequired
A template selector describing the template ID and variable substitutions to use with it.
OBJECT PROPERTIESsubstitutions : Object
An 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 : StringRequired
Specifies the template to override.
name : String
An optional name for the scheduled push operation.
schedule : Schedule SpecificationRequired
Determines when the push is sent.
Responses
202
The scheduled push has been accepted for processing.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
Success.
operation_id : String
A unique string which identifies a single API call, and can be used to group multiple entities or side-effects as related, in reporting and troubleshooting logs. Format:
uuidschedule_ids : Array [String]
An array of schedule IDs. Max items: 100 Min items: 1
schedule_urls : Array [String]
An array of schedule URLs. The URL for each schedule is the schedules endpoint, appended with the
schedule_idof the schedule. Max items: 100schedules : Array [Schedule Object]
An array of schedule objects.
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.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
406
Return when the client requests a version of the API which cannot be satisfied, because no compatible version is currently deployed.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Look up a Template
Example
GET /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
TemplateListingRequest request = TemplateListingRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161");
Response<TemplateListingResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
template = ua.Template(airship).lookup(template_id)
print (
template.template_id, template.created_at, template.modified_at,
template.last_used, template.name, template.description,
template.variables, template.push
)HTTP/1.1 200 OK
Data-Attribute: template
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok" : true,
"template": {
"id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
"created_at": "2020-08-17T11:10:02Z",
"modified_at": "2020-08-17T11:10:02Z",
"last_used": null,
"name": "Welcome Message",
"description": "Our welcome message",
"variables": [
{
"key": "TITLE",
"name": "Title",
"description": "e.g. Mr, Ms, Dr, etc.",
"default_value": ""
},
{
"key": "FIRST_NAME",
"name": "First Name",
"description": "Given name",
"default_value": null
},
{
"key": "LAST_NAME",
"name": "Last Name",
"description": "Family name",
"default_value": null
}
],
"push": {
"notification": {
"alert": "Hello {{FIRST_NAME}}, this is your welcome message!"
}
}
}
}This operation is not currently supported by the Ruby Library.GET /api/templates/{template_id}
Fetch the current definition of a single template.
This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.
Security:
path PARAMETERStemplate_id : String Required
A required string ID of the template.
Responses
200
Returned on success, with the JSON representation of the template in the body of the response.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If true, the operation completed successfully and returns an expected response.
template : Template Object
A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Update Template
Example
POST /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"name": "Welcome Message",
"description": "Our welcome message",
"push": {
"notification": {
"alert": "Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!"
}
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
PartialPushPayload partialPushPayload = PartialPushPayload.newBuilder()
.setNotification(Notification.newBuilder()
.setAlert("Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!")
.build()
)
.build();
TemplateRequest request = TemplateRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161")
.setName("Welcome Message")
.setDescription("Our welcome message")
.setPush(partialPushPayload);
Response<TemplateResponse> response = client.execute(request);HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
updated_template = ua.Template(airship)
updated_template.push = {
'notification': {
'alert': 'Hi {{FIRST_NAME}} {{LAST_NAME}}!'
}
}
response = updated_template.update(template_id)This operation is not currently supported by the Ruby Library.Alternatively, call the lookup function on your updated template:
import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
updated_template = ua.Template(airship).lookup(template_id)
updated_template.push = {
'notification': {
'alert': 'Greetings {{TITLE}} {{FIRST_NAME}} {{LAST_NAME}}!'
}
}
response = updated_template.update()POST /api/templates/{template_id}
Update a template. The request body is a partially-defined template object, containing the field(s) you want to change and their updated values.
This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.
Security:
path PARAMETERStemplate_id : String Required
A required string ID of the template.
Request Body
Content-Type: application/json
Object
A partially-defined template object. Provide only
OBJECT PROPERTIESvariablesandpushitems that you want to update.description : String
The description of the template.
name : StringRequired
The name of the template.
push : Template Push Object
A partial push object describing everything about a push notification, except for the
audienceanddevice_types(which are defined in the pushTemplatePayload object).variables : Array [Template Variables]
An array of Variable Specifications.
Responses
200
Returned if the template has been succesfully updated.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If true, the operation completed successfully and returns an expected response.
operation_id : String
A unique string identifying the operation, useful for reporting and troubleshooting. Format:
uuid
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Delete Template
Example
DELETE /api/templates/ef34a8d9-0ad7-491c-86b0-aea74da15161 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
TemplateDeleteRequest request = TemplateDeleteRequest.newRequest("ef34a8d9-0ad7-491c-86b0-aea74da15161");
Response<TemplateResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
template_id = 'ef34a8d9-0ad7-491c-86b0-aea74da15161'
# Delete via template lookup
response = ua.Template(airship).lookup(template_id).delete()
# OR, if you want to delete a template without fetching it from the API
response = ua.Template(airship).delete(template_id)HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "a6394ff8-8a65-4494-ad06-677eb8b7ad6a"
}This operation is not currently supported by the Ruby Library.DELETE /api/templates/{template_id}
Delete a template. If the template is successfully deleted, the response does not include a body.
This API is being replaced by new content templating features, currently available in the Airship UI. This API will not be removed until the new content templating feature supports all platforms, but we are no longer adding features to this API or its templating language.
Security:
path PARAMETERStemplate_id : String Required
A required string ID of the template.
Responses
200
The template with given ID has been succesfully deleted.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If true, the operation completed successfully and returns an expected response.
operation_id : String
A unique string identifying the operation, useful for reporting and troubleshooting. Format:
uuid
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Regions
The Region API endpoints provide a listing and detail for all of your defined entry/exit regions, including custom shapes (polygons) and circles (point/radius).
Region Listing
Example
GET /api/regions/?limit=100&start=100 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;HTTP/1.1 200 OK
Data-Attribute: regions
Link: <https://go.urbanairship.com/api/regions?limit=100&start=100>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3
{
"ok": true,
"next_page": "https://go.urbanairship.com/api/regions?limit=100&start=100",
"count": 100,
"regions": [
{
"region_id": "abe5deb3-01d0-436e-8c5d-94b6421a01e0",
"name": "My Favorite Place",
"created_at": "2020-06-09T12:34:56",
"updated_at": "2020-06-09T12:34:56",
"geofence": {
"type": "POLYGON",
"points": [
{
"latitude": 90.0,
"longitude": 120.0
},
{
"latitude": 45.0,
"longitude": 120.0
},
{
"latitude": 0.0,
"longitude": 0.0
}
]
},
"beacons": [
{
"name": "entryway",
"id": "VLSHZAOEXOFCMLDVTKFQ"
},
{
"name": "Exhibit A",
"id": "ZAQYMNOZKRFCRPYEUCZI"
}
],
"attributes": {
"store_name": "Tonali's Donuts"
},
"source_info": {
"source": "GIMBAL",
"region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
"vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
}
}
]
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.GET /api/regions
Get a paginated list regions. The result is an array of Region Objects under the “regions” key.
Security:
query PARAMETERSlimit : Integer
Determines 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 : Integer
A zero-based integer offset into the ordered list of regions, useful for addressing pages directly.
Responses
200
Returns OK for success.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIEScount : Integer
The total number of regions returned.
next_page : String
There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results. Format:
urlok : Boolean
Success.
regions : Array [Region Object]
An array of Region Objects.
400
returned when
limitis greater than 1000.RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Region Lookup
Example
GET /api/regions/7d4d9a5c-eff5-40f2-b648-4352c166e878 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;HTTP/1.1 200 OK
Data-Attribute: region
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"region": {
"region_id": "7dbd9a5c-eff5-40f2-b648-4352c1668878",
"created_at": "2020-08-24T23:15:22.900",
"updated_at": "2020-08-24T23:15:22.900",
"name": "Alberta Park",
"source_info": {
"source": "GIMBAL",
"region_id": "C56654BC0C3243D6A4B7A3673560D6F8",
"vendor_href": "https://manager.gimbal.com/api/v2/places/C56654BC0C3243D6A4B7A3673560D6F8"
},
"geofence": {
"type": "CIRCLE",
"center": {
"latitude": 45.56447530000002,
"longitude": -122.64461097354126
},
"radius": 200
},
"attributes": {
"park_name": "alberta",
"type": "park"
}
}
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.GET /api/regions/{region_id}
Get details for a specific region.
Security:
path PARAMETERSregion_id : String Required
The region you want to lookup.
Responses
200
Returns OK for success.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
if true, indicates success.
region : Region Object
A Region object describes a geographical boundary or set of hardware identifiers and associated attributes that correspond to a physical location of relevance to the application or application owner.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Custom Events
User events that occur outside of your app can be submitted to Airship for inclusion in analytics reporting, as triggers for Automation, or for export via Connect. These events can take place on the web, e.g., your website, social media, or in your back office systems such as CRM or POS software. Any event that can be associated with a mobile app user can be submitted as an Airship custom event. The events that you submit are associated with channels and are available to use as custom event triggers.
Add Custom Events
Example
POST /api/custom-events HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <application key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json
[
{
"occurred": "2020-05-02T02:31:22",
"user": {
"named_user_id": "hugh.manbeing"
},
"body": {
"name": "purchased",
"value": 239.85,
"transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a",
"interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
"interaction_type": "url",
"properties": {
"description": "Sneaker purchase",
"brand": "Victory Sneakers",
"colors": [
"red",
"blue"
],
"items": [
{
"text": "New Line Sneakers",
"price": "$ 79.95"
},
{
"text": "Old Line Sneakers",
"price": "$ 79.95"
},
{
"text": "Blue Line Sneakers",
"price": "$ 79.95"
}
],
"name": "Hugh Manbeing",
"userLocation": {
"state": "CO",
"zip": "80202"
}
},
"session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
}
}
]UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.setBearerToken("<bearer token>")
.build();
CustomEventUser customEventUser = CustomEventUser.newBuilder()
.setNamedUserId("hugh.manbeing")
.build();
CustomEventPropertyValue customEventProperty = CustomEventPropertyValue.of("Victory Sneakers");
List<CustomEventPropertyValue> items = new ArrayList<>();
items.add(CustomEventPropertyValue.of("New Line Sneakers"));
items.add(CustomEventPropertyValue.of("Old Line Sneakers"));
DateTime occurred = new DateTime(2020, 05, 02, 02, 31, 22, DateTimeZone.UTC);
CustomEventBody customEventBody = CustomEventBody.newBuilder()
.setName("purchased")
.addPropertiesEntry("brand", customEventProperty)
.addPropertiesEntry("items", CustomEventPropertyValue.of(items))
.build();
CustomEventPayload customEventPayload = CustomEventPayload.newBuilder()
.setCustomEventBody(customEventBody)
.setCustomEventUser(customEventUser)
.setOccurred(occurred)
.build();
CustomEventRequest customEventRequest = CustomEventRequest.newRequest(customEventPayload);
Response<CustomEventResponse> response = client.execute(customEventRequest);HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3
{
"ok": true,
"operation_id": "8c61c0c4-95b0-45a6-bc38-733f7fcb8979"
}This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.POST /api/custom-events
Submit an externally-generated custom event, associated with a channel ID or named user, to Airship. You can use these events as custom event triggers for Automation or Journeys and can use handlebars to personalize messages using custom event properties (information in the body.properties object).
- 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 Body
An array of custom event objects.
Content-Type: application/json
Array [Custom Event object]
Max items: 100 Min items: 1
Responses
200
Returned on success.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
Success.
operation_id : String
A unique string identifying the API interaction. You can use the
operation_idin support requests if something goes wrong. Format:uuid
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.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Channels
Channels are Airship’s unique identifiers for addressing applications on iOS, Android, Amazon, and web devices.
Channel Listing
Example
GET /api/channels HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
ChannelRequest request = ChannelRequest.newRequest();
Response<ChannelResponse> response = client.execute(request);
ChannelView channels = response.getBody().get().getChannelView().get();import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
channel_id = None
for channel in ua.ChannelList(airship):
channel_id = channel.channel_id
print (channel.channel_id, channel.device_type, channel.tags,
channel.push_address, channel.named_user_id, channel.opt_in)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
channel_list = UA::ChannelList.new(client: airship)
channel_list.each do |channel|
puts(channel)
end
puts(channel_list.count)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": "android",
"push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
"opt_in": true,
"installed": true,
"background": true,
"created": "2020-03-06T18:52:59",
"last_registration": "2020-10-07T21:28:35",
"named_user_id": "some_id_that_maps_to_your_systems",
"alias": "null",
"tags": [
"tag1",
"tag2"
],
"tag_groups": {
"tag_group_1": ["tag1", "tag2"],
"tag_group_2": ["tag1", "tag2"]
},
"device_attributes": {
"ua_device_os": "10",
"ua_country": "US",
"ua_device_model": "SM-G973U",
"ua_local_tz": "America/Los_Angeles",
"ua_app_version": "2020-02-01T002322-goat",
"ua_location_settings": "true",
"ua_language": "en",
"ua_sdk_version": "12.2.0",
"ua_carrier": "Verizon "
},
"attributes": {
"first_name": "Cool",
"last_name": "Person",
"birthdate": "1983-03-15T00:00:00",
}
},
{
"channel_id": "bd36e8c7-5a73-47c0-9716-99fd3d4197d5",
"device_type": "ios",
"push_address": null,
"opt_in": false,
"installed": true,
"background": true,
"created": "2020-03-06T18:52:59",
"last_registration": "2020-10-07T21:28:35",
"named_user_id": "some_id_that_maps_to_your_systems",
"alias": "null",
"tags": [
"tag1",
"tag2"
],
"tag_groups": {
"tag_group_1": ["tag1", "tag2"],
"tag_group_2": ["tag1", "tag2"]
},
"ios": {
"badge": 0,
"quiettime": {
"start": null,
"end": null
},
"tz": null
}
}
]
}GET /api/channels
List all channels registered to this app key, along with associated data and metadata.
Security:
Responses
200
Returns OK for success with the JSON response.
RESPONSE HEADERSLink : String
provides the URL to the current page of results. The query within the URL contains the
limit(the number of results on the page) andstart(the firstchannel_idin the result set) parameters.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESchannels : Array [Channel Object]
An array of Channel Objects.
next_page : String
If there is more than one page of results, use this link to get the next page of results. Format:
urlok : Boolean
Success.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Set or Remove Attributes on Channels
Example
POST /api/channels/attributes HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"android_channel": ["13863b3c-f860-4bbf-a9f1-4d785379b8a2"]
},
"attributes": [
{
"action": "set",
"key": "major_league",
"value": "sf_giants"
},
{
"action": "remove",
"key": "minor_league"
},
{
"action": "set",
"key": "position",
"value": "LF"
}
]
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
Attribute setMajorLeague = Attribute.newBuilder()
.setAction(AttributeAction.SET)
.setKey("major_league")
.setValue("sf_giants")
.build();
Attribute removeMinorLeague = Attribute.newBuilder()
.setAction(AttributeAction.REMOVE)
.setKey("minor_league")
.build();
Attribute setPosition = Attribute.newBuilder()
.setAction(AttributeAction.SET)
.setKey("position")
.setValue("LF")
.build();
ChannelAttributesPayload payload = ChannelAttributesPayload.newBuilder()
.addAttribute(setMajorLeague)
.addAttribute(removeMinorLeague)
.addAttribute(setPosition)
.setAudience(AttributeAudience.newBuilder()
.addDeviceId(AttributeAudienceType.ANDROID_CHANNEL, "13863b3c-f860-4bbf-a9f1-4d785379b8a2")
.build())
.build();
ChannelAttributesRequest request = ChannelAttributesRequest.newRequest(payload);
Response<ChannelAttributesResponse> response = client.execute(request);require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
channel_info = UA::ChannelInfo.new(client: airship)
channel_info.audience = {"android_channel": '13863b3c-f860-4bbf-a9f1-4d785379b8a2'}
channel_info.attributes = {
"action": "set",
"key": "major_league",
"value": "sf_giants"
}
channel_info.set_attributesThis operation is not currently supported by the Python Library.Example Request with Dates and Numbers
POST /api/channels/attributes HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"android_channel": ["13863b3c-f860-4bbf-a9f1-4d785379b8a2"]
},
"attributes": [
{
"action": "set",
"key": "birthday",
"value": "1983-03-15 10:00:00"
},
{
"action": "set",
"key": "fav_number",
"value": 42
},
{
"action": "remove",
"key": "another_attribute"
}
]
}POST /api/channels/attributes
Set or remove attributes on a channel. Aside from Airship’s default attributes, you must define attributes in the Airship dashboard before you can set them on channels.
Use named_user_id instead of named_user as the audience selector key if you are targeting named users with this endpoint. We will add support for named_user in an upcoming release.
Security:
Request Body
Content-Type: application/json
Include an audience selector and an array of attributes objects in your request.
All ofAudience Selector
An audience selector forms the expression that determines the set of channels to target.
Array of Attributes Objects : Array [Attribute Assignment]
Responses
200
The operation was successful.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If true, your request was successful.
warning : String
Alerts you if your request could not be processed. You may receive a 200 with a warning if you provide a
valuethat does not match your attribute type. For example, an attribute that expects a numeric value will allow a value of “25”, but fail if you input “twenty-five”.
400
Parsing or validating the request failed.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Subscribe or Unsubscribe Channels to/from Subscription Lists
Example
POST /api/channels/subscription_lists HTTP/1.1
Authorization: Basic <App Auth>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"subscription_lists": [
{
"action":"subscribe",
"list_id":"intriguing_ideas"
},
{
"action":"unsubscribe",
"list_id":"animal_facts"
}
],
"audience": {
"ios_channel": [
"b8f9b663-0a3b-cf45-587a-be880946e881"
],
"email_address": [
"homer@springfield.net",
"nick@nite.org"
]
}
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.POST /api/channels/subscription_lists
Subscribe or unsubscribe channels to/from Subscription lists.
You must first create a Subscription list in the dashboard, then refer to its ID when subscribing users. When subscribing users, if the list has not already been created in the dashboard, then the list will be created at the same time but will not be accessible from the dashboard; the list will available for API use only.
Security:
Request Body
Content-Type: application/json
The request payload must be a JSON object with the following fields.
All ofAudience Selector
An audience selector forms the expression that determines the set of channels to target.
subscription_lists : Array [String]
An array of subscription list IDs.
ARRAY ITEMMax length: 32 Min length: 1
Responses
202
The request has been accepted for processing.
RESPONSE BODYContent-Type: application/json
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Channel Tags
Example
POST /api/channels/tags HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"audience": {
"ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881",
"android_channel": "13863b3c-f860-4bbf-a9f1-4d785379b8a2"
},
"add": {
"my_fav_tag_group1": ["tag1", "tag2", "tag3"],
"my_fav_tag_group2": ["tag1", "tag2", "tag3"],
"my_fav_tag_group3": ["tag1", "tag2", "tag3"]
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
ChannelTagRequest request = ChannelTagRequest.newRequest()
.addIOSChannel("b8f9b663-0a3b-cf45-587a-be880946e881")
.addAndroidChannel("13863b3c-f860-4bbf-a9f1-4d785379b8a2")
.addTags("my_fav_tag_group1", ImmutableSet.of("tag1", "tag2", "tag3"))
.addTags("my_fav_tag_group2", ImmutableSet.of("tag1", "tag2", "tag3"))
.addTags("my_fav_tag_group3", ImmutableSet.of("tag1", "tag2", "tag3"));
Response response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
channel_tags = ua.devices.ChannelTags(airship)
ios_audience = ['b8f9b663-0a3b-cf45-587a-be880946e881']
android_audience = ['13863b3c-f860-4bbf-a9f1-4d785379b8a2']
channel_tags.set_audience(ios_audience, android_audience
)
channel_tags.add('my_fav_tag_group1', ['tag1', 'tag2', 'tag3'])
channel_tags.remove('my_fav_tag_group2', 'tag4')
channel_tags.send()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
channel_tags = UA::ChannelTags.new(client: airship)
ios_audience = 'b8f9b663-0a3b-cf45-587a-be880946e881'
android_audience = '13863b3c-f860-4bbf-a9f1-4d785379b8a2'
channel_tags.set_audience(
ios: ios_audience,
android: android_audience
)
channel_tags.add(group_name: 'my_fav_tag_group1', tags: ['tag1', 'tag2', 'tag3'])
channel_tags.remove(group_name: 'my_fav_tag_group2', tags: 'tag4')
channel_tags.send_requestHTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"warnings": ["The following tag groups do not exist: my_fav_tag_group2", "The following tag groups are deactivated: my_fav_tag_group3"]
}POST /api/channels/tags
Add, remove, or set tags on a channel.
A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response. We support up to 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
Content-Type: application/json
Object
A single request body may contain add and/or remove objects, or a single set object. At least one of the add, remove, or set objects must be present in a request.
OBJECT PROPERTIESadd : Tag Group Object
Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
audience : ObjectRequired
Specifies one or more channels that you want to apply tag operations to.
OBJECT PROPERTIESamazon_channel : Array [String]
The unique channel identifier for an Amazon device. Max items: 1000 Min items: 1
android_channel : Array [String]
The unique channel identifier for an Android device. Max items: 1000 Min items: 1
channel : Array [String]
The unique channel identifier for
email,sms,open, orwebdevice types. Max items: 1000 Min items: 1ios_channel : Array [String]
The unique channel identifier for an iOS device. Max items: 1000 Min items: 1
remove : Tag Group Object
Removes the specified tags from the channel.
set : Tag Group Object
Assigns a list of tags exactly; any previously set tags that are not in this current list will be removed.
Responses
200
Returns OK for success. If a tag request is partially valid, i.e. at least one tag group exists and is active, a 200 is returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If true, your request was processed normally.
warnings : Array [String]
Returned when some tag groups could not be updated. Contains a string indicating each tag group that could not be updated and the reason the update failed.
400
Bad Request. Parsing or validating the request failed. You will get this error if a tag is present in both the add and remove fields.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Returned in cases when the app does not permit associations from the device. Secure tag groups require master secret to modify tags.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Uninstall Channels
Example
POST /api/channels/uninstall HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
[
{
"channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881",
"device_type": "ios"
},
{
"channel_id": "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
"device_type": "android"
}
]import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
channel_uninstall = ua.ChannelUninstall(airship)
channel = {
"channel_id": 'b8f9b663-0a3b-cf45-587a-be880946e881',
"device_type": "ios"
}
channel_uninstall.uninstall(channel)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
cu = UA::ChannelUninstall.new(client: airship)
chans = [{"channel_id" => "b8f9b663-0a3b-cf45-587a-be880946e881",
"device_type" => "ios"},
{"channel_id" => "13863b3c-f860-4bbf-a9f1-4d785379b8a2",
"device_type" => "android"}]
cu.uninstall(channels: chans)HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"ok": true
}This operation is not currently supported by the Java Library.POST /api/channels/uninstall
Uninstalls a channel, removing it and all accompanying analytic data (including Performance Analytics) from Airship systems in accordance with data privacy law compliance.
Uninstallation is handled automatically by the Airship SDK and push systems. If a user decides to opt in to communications again (either by using your app or other user preferences), they will create a new channel and a new set of analytic data. The value of a channel ID may be the same as before however none of the associated metadata will persist when a user opts in again. A new channel ID will be created if the user clears their browser’s cookies and data, deletes and reinstalls the app, etc.
See Individual Data Privacy Rights Under Data Privacy Laws for more information about data privacy law compliance.
Channel uninstallation, like channel creation, is an asynchronous operation, and may take some time to complete.
Security:
Request Body
Content-Type: application/json
Array [Object]
Max items: 1000 Min items: 1
ARRAY ITEMspecifies the channel ID and device type you want to uninstall.
OBJECT PROPERTIESchannel_id : StringRequired
The channel ID.
device_type : StringRequired
The device type of the channel. Valid values are ‘ios’, ‘amazon’, ‘android’, ‘web’, ‘open’. Possible values:
ios,android,amazon,web,open
Responses
202
The request has been accepted for processing.
RESPONSE BODYContent-Type: application/json
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Channel Lookup
Example
GET /api/channels/9c36e8c7-5a73-47c0-9716-99fd3d4197d5 HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
ChannelRequest request = ChannelRequest.newRequest("9c36e8c7-5a73-47c0-9716-99fd3d4197d5");
Response<ChannelResponse> response = client.execute(request);
ChannelView channel = response.getBody().get().getChannelView().get();import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
channel = ua.ChannelInfo(airship).lookup('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
print (channel.channel_id, channel.device_type, channel.tags,
channel.push_address, channel.named_user_id, channel.opt_in)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
channel_client = UA::ChannelInfo.new(client: airship)
channel_info = channel_client.lookup(uuid: '9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
puts(channel_info)HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"ok": true,
"channel": {
"channel_id": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5",
"device_type": "ios",
"installed": true,
"opt_in": false,
"background": true,
"push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660",
"created": "2020-08-08T20:41:06",
"last_registration": "2020-05-01T18:00:27",
"named_user_id": "some_id_that_maps_to_your_systems",
"alias": null,
"tags": [
"tag1",
"tag2"
],
"tag_groups": {
"tag_group_1": ["tag1", "tag2"],
"tag_group_2": ["tag1", "tag2"]
},
"ios": {
"badge": 0,
"quiettime": {
"start": null,
"end": null
},
"tz": "America/Los_Angeles"
}
}
}GET /api/channels/{channel_id}
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:
path PARAMETERSchannel_id : String Required
The channel you want to look up.
Responses
200
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 BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESchannel : Channel Object
A channel object.
ok : Boolean
Success.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Open Channels
Open Channels are custom communication channels that you can configure for messaging, using the same segmentation and scheduling tools available on natively-supported platforms (iOS, Android, etc). With Open Channels, you define a new open platform, e.g., SMS, Slack, Acme™ Smart Toasters, and register the new platform with Airship. If you are sending through the push API, platform overrides for open platforms are covered in the Open Channels Platform Overrides section.
Register New / Update Channel
Example
POST /api/channels/open HTTP/1.1
Authorization: Basic <master secret authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"channel": {
"type": "open",
"opt_in": true,
"address": "Number Four",
"tags": [
"toaster",
"caprica"
],
"timezone": "America/Los_Angeles",
"locale_country": "US",
"locale_language": "en",
"open": {
"open_platform_name": "cylon",
"identifiers": {
"model": "4"
}
}
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
OpenChannel openChannel = OpenChannel.newBuilder()
.setOpenPlatformName("cylon")
.setOldAddress("Number Four")
.addIdentifier("model", "4")
.build();
Channel channel = Channel.newBuilder()
.setOpenChannel(openChannel)
.setChannelType(ChannelType.OPEN)
.setOptIn(true)
.setAddress("Number Four")
.setTags(true)
.addTag("toaster")
.setTimeZone("America/Los_Angeles")
.setLocaleCountry("US")
.setLocaleLanguage("en")
.build();
OpenChannelPayload payload = new OpenChannelPayload(channel);
OpenChannelRequest request = OpenChannelRequest.newRequest(payload);
Response<OpenChannelResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
my_channel = ua.OpenChannel(airship)
my_channel.address = 'Number Four'
my_channel.open_platform = 'cylon'
my_channel.opt_in = True
resp = my_channel.create()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
open_channel = UA::OpenChannel.new(client: airship)
open_channel.opt_in = true
open_channel.address = 'Number Four'
open_channel.open_platform = 'cylon'
open_channel.create()HTTP/1.1 200 OK
Location: https://go.urbanairship.com/api/channels/df6a6b50-9843-0304-d5a5-743f246a4946
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946"
}POST /api/channels/open
Create a new open channel, or update an existing open channel.
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.
Content-Type: application/json
Object
OBJECT PROPERTIESchannel : ObjectRequired
Properties of the open channel object.
OBJECT PROPERTIESaddress : StringRequired
Where 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 : String
The two-letter country locale short code. Will set the
ua_locale_countrytag group to the specified value.locale_language : String
The two-letter language locale short code. Will set the
ua_locale_languagetag group to the specified value.open : ObjectRequired
Open channel-specific properties.
OBJECT PROPERTIESidentifiers : Object
Optional object with string-to-string key:value pairs that represent non-segmentable identifiers for the channel in your delivery systems. Delivered as part of webhook payloads. If present, the value will overwrite (not union with) existing identifier records. Max items: 100
OBJECT PROPERTIES* : String
open_platform_name : StringRequired
The name of the open platform to which you are registering this channel.
opt_in : BooleanRequired
If false, no payloads will be delivered for the channel.
tags : Array [String]
A list of strings used for audience targeting. When used for this endpoint, operates like the
tags { set {}}operation; specified tags are applied, and all other tags are removed. Max items: 1000 Min items: 1timezone : String
An IANA tzdata identifier for the timezone as a string, e.g.,
"America/Los_Angeles". Will set the timezone tag group tag with the specified value.type : StringRequired
Required string. The only acceptable value for an open channel is
open. Possible values:open
Responses
200
Returned if the new channel is created successfully or if an existing channel was found for the specified open_platform_name and address.
RESPONSE HEADERSLocation : String
Used for later API calls for this channel.
Format:
uri
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESchannel_id : String
Identifies the new open channel or the open channel you successfully updated. Format:
uuidok : Boolean
Success.
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.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
429
Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Open Channel Tags
Example
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 Four",
"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"]
}
}import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
my_channel = ua.OpenChannel(airship).lookup(
'df6a6b50-9843-0304-d5a5-743f246a4946'
)
my_channel.tags = ['tag1', 'tag2']
resp = my_channel.update()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
open_channel = UA::OpenChannel.new(client: airship)
open_channel.opt_in = true
open_channel.address = 'Number Four'
open_channel.open_platform = 'cylon'
open_channel.channel_id = 'df6a6b50-9843-0304-d5a5-743f246a4946'
open_channel.tags = ['tag1', 'tag2', 'tag3']
open_channel.update(set_tags: true)HTTP/1.1 200 Accepted
Content-Type: application/vnd.urbanairship+json; version=3; charset=utf-8
{
"ok":true
}This operation is not currently supported by the Java Library.POST /api/channels/open/tags
Manipulate a single open channel’s tags. Open channels are identified by address, not by thier channel_id.
A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response. We support up to 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
Content-Type: application/json
Object
Add, remove, or set tags on a channel. A single request body may contain add and/or remove objects, or a single set field. At least one of the add, remove, or set objects must be present in a request.
OBJECT PROPERTIESadd : Tag Group Object
Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
audience : ObjectRequired
The request body containing an address and open_platform_name.
OBJECT PROPERTIESaddress : StringRequired
Where 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 : StringRequired
An alphanumeric string that must be the name of a pre-created open platform object. Max length: 128 Min length: 1
remove : Tag Group Object
Removes the specified tags from the channel.
set : Tag Group Object
Assigns a list of tags exactly; any previously set tags that are not in this current list will be removed.
Responses
200
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 BODYContent-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Returned in cases when the app does not permit associations from the device. Secure tag groups require master secret to modify tags.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Uninstall Open Channels
Example
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"
}import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
my_channel = ua.OpenChannel(airship).lookup(
'df6a6b50-9843-0304-d5a5-743f246a4946'
)
resp = my_channel.uninstall()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
cu = UA::OpenChannelUninstall.new(client: airship)
cu.uninstall(address: 'Number Four', open_platform: 'cylon')HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}This operation is not currently supported by the Java Library.POST /api/channels/open/uninstall
Uninstall a channel needing to know its channel ID. You cannot send notifications to, or get channel information for, an uninstalled channel.
Security:
Request Body
An address and the open_platform_name you want to uninstall the address from.
Content-Type: application/json
Open Channel Identifier : Object
The request body containing an address and open_platform_name.
OBJECT PROPERTIESaddress : StringRequired
Where 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 : StringRequired
An alphanumeric string that must be the name of a pre-created open platform object. Max length: 128 Min length: 1
Responses
202
The request has been accepted for processing.
RESPONSE BODYContent-Type: application/json
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Register email channels, set opt-in status, and manipulate tags on email channels.
Create Email Attachment
Example: Create email attachment
POST /attachments HTTP/1.1
Authorization: Bearer <authorization token>
Content-Type: application/json
Accept: application/vnd.urbanairship+json; version=3;
{
"filename": "rickroll.png",
"content_type": "text/plain; charset=\"UTF-8\"",
"data": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAIAAADTED8xAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyhpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8..."
}HTTP/1.1 201 Accepted
Data-Attribute: attachment_id
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"attachment_ids": [
"b0c46a8d-b701-441b-9d6e-147c183b28ca"
]
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.POST /api/attachments
Create attachments by POSTing to the attachments URI. The body of the request must be a JSON object describing and including the contents of a file to attach.
Attachments can be used for
transactionalsends only, notcommercial.Attachments cannot be used in Automations.
Attachment size is limited to 2.5MB per attachment, with a 20MB content size limit on each message, including content body and all attachments.
Attachment count is limited to 10 per email.
Sending attachments with malicious content is strictly prohibited. This is enforced in part by blocking file types with .bat and .exe extensions.
Attachments have a TTL (Time To Live) of 60 days.
Security:
Request Body
Content-Type: application/json
Object
OBJECT PROPERTIEScontent_type : StringRequired
The mimetype of the uploaded file including the charset parameter, if needed. Example:
"text/plain; charset=\"UTF-8\""Max length: 100
data : StringRequired
Base64-encoded bytes of the file contents representing a maximum of 2.5 MiB of data when decoded. Padding with “=” chars is optional.
filename : StringRequired
The name of the uploaded file (max 255 UTF-8 bytes). Multiple files with the same name are allowed in separate requests.
Responses
201
The email attachment was created. The response body will contain the IDs of the created attachments.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
The response body for an email attachment creation request.
OBJECT PROPERTIESattachment_id : Array [String]
The attachment ID for a newly-created attachment. Reference this ID in the
attachmentslist in the Email override.ok : Boolean
Either
trueorfalse. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
The application does not have the proper entitlement to create attachments.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Register Email Channel
Example
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": "2020-10-28T10:34:22",
"address": "name@example.com",
"timezone" : "America/Los_Angeles",
"locale_country" : "US",
"locale_language" : "en"
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
RegisterEmailChannel emailChannel = RegisterEmailChannel.newBuilder()
.setAddress("name@example.com")
.setEmailOptInLevel(OptInLevel.EMAIL_COMMERCIAL_OPTED_IN, "2020-10-28T10:34:22")
.build();
RegisterEmailChannelRequest request = RegisterEmailChannelRequest.newRequest(emailChannel);
Response<EmailChannelResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
email = ua.Email(airship=airship,
address='name@example.com',
commercial_opted_in='2020-10-28T10:34:22',
timezone='America/Los_Angeles',
locale_country='US',
locale_language='en')
resp = email.register()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
email_channel = UA::Email.new(client: airship)
email_channel.type = 'email'
email_channel.commercial_opted_in = '2020-10-28T10:34:22'
email_channel.address = 'name@example.com'
email_channel.timezone = 'America/Los_Angeles'
email_channel.locale_country = 'US'
email_channel.locale_language = 'en'
email_channel.registerHTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/channels/251d3318-b3cb-4e9f-876a-ea3bfa6e47bd
Content-Type: application/json
{
"ok": true,
"channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd"
}POST /api/channels/email
Create a new email channel or update an existing channel. If you provide the email address of an existing channel, the call is treated as a PUT.
If you want to update the address of an existing channel, see the Update email channel endpoint.
Security:
Request Body
A single email channel object.
Content-Type: application/json
Email Channel Object : Object
An email channel object is the object used to create or update channels.
There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal noticies, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out).
Each channel uses
opted_inandopted_outkeys 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 noopted_inoropted_outvalues 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
OBJECT PROPERTIEScommercial_opted_inandcommercial_opted_outvalues; if the opt-in date is prior to the opt-out date, the user will not receive commercial emails from you.channel : ObjectRequired
OBJECT PROPERTIESaddress : StringRequired
The email address being registered.
commercial_opted_in : String
The date-time when a user gave explicit permission to receive commercial emails.
commercial_opted_out : String
The date-time when a user explicitly denied permission to receive commercial emails.
locale_country : String
The device property tag related to locale country setting.
locale_language : String
The device property tag related to locale language setting.
timezone : String
The device property tag related to timezone setting.
transactional_opted_in : String
The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.
transactional_opted_out : String
The date-time when a user explicitly denied permission to receive transactional emails.
type : StringRequired
The type of channel you are registering. For email channels, this value must be
email. Possible values:email
Responses
201
The email channel was created.
RESPONSE HEADERSLocation : String
The newly created email channel.
Format:
uri
RESPONSE BODYContent-Type: text/plain
The response body for an email channel request.
OBJECT PROPERTIESchannel_id : String
A unique string identifying the email channel. Format:
uuidok : Boolean
Either
trueorfalse. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Email Tags
Example
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"]
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
EmailTagRequest request = EmailTagRequest.newRequest();
emailTagRequest.addEmailChannel("name@example.com")
.addTags("my_fav_tag_group1", ImmutableSet.of("tag1", "tag2", "tag3"))
.addTags("my_fav_tag_group2", ImmutableSet.of("tag1", "tag2", "tag3"))
.addTags("my_fav_tag_group3", ImmutableSet.of("tag1", "tag2", "tag3"));
Response<EmailChannelResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
# replaces all existing tags on an email channel
email_tags = ua.EmailTags(airship=airship,
address='name@example.com')
email_tags.set(group='my_tag_group',
tags=['one', 'two', 'three'])
email_tags.send()
# adds and removes tags from an email channel
email_tags = ua.EmailTags(airship=airship,
address='name@example.com')
email_tags.remove(group='my_tag_group',
tags=['one', 'two', 'three'])
email_tags.add(group='my_tag_group',
tags=['some', 'new', 'tags'])
email_tags.send()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
email_tags = UA::EmailTags.new(client: airship)
#set an audience
email_tags.set_audience(email_address: 'name@example.com')
#add a tag
email_tags.add(group_name: 'my_fav_tag_group1', tags: 'tag2')
#remove a tag
email_tags.remove(group_name: 'my_fav_tag_group1', tags: 'tag1')
email_tags.send_requestPOST /api/channels/email/tags
Add, remove, or set tags for a single email channel.
A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response. We support up to 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.
Content-Type: application/json
Object
OBJECT PROPERTIESadd : Tag Group Object
Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
audience : ObjectRequired
Specifies the email address you want to perform tag operations against. Must contain a single
OBJECT PROPERTIESemail_addresskey. Max properties: 1email_address : StringRequired
The email address you want to modify tags for. Accepts a single string value representing an email address.
remove : Tag Group Object
Removes the specified tags from the channel.
set : Tag Group Object
Assigns a list of tags exactly; any previously set tags that are not in this current list are removed.
Responses
200
Returns OK for success. If a tag request is partially valid, i.e. at least one tag group exists and is active, a 200 will be returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be csv format.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, 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. If a tag is present in both the add and remove fields, a HTTP 400 response will be returned.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Uninstall Email Channel
Example
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"
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
UninstallEmailChannel uninstallEmailChannel = UninstallEmailChannel.newBuilder()
.setEmailAddress("name@example.com")
.build();
UninstallEmailChannelRequest request = UninstallEmailChannelRequest.newRequest(uninstallEmailChannel);
Response<EmailChannelResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
email = ua.Email(airship=airship,
address='name@example.com')
resp = email.uninstall()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
email_channel = UA::Email.new(client: airship)
email_channel.address = 'name@example.com'
email_channel.uninstallHTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}POST /api/channels/email/uninstall
Removes an email address from Airship. Use with caution. If the uninstalled email address opts-in again, it might generate a new channel_id. If a user generates a new channel_id when they opt-in again, the new channel_id cannot be reassociated with any opt-in information, tags, named users, Performance Analytics reports, or other information from the that belonged to the previously-uninstalled email channel.
Security:
Request Body
An email address of the channel to uninstall.
Content-Type: application/json
Object
OBJECT PROPERTIESemail_address : StringRequired
The email address of the channel to uninstall.
Responses
202
The request has been accepted for processing.
RESPONSE BODYContent-Type: application/json
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Lookup an Email Address
Example
GET /api/channels/email/name%40domain.com HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/jsonrequire 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
email_channel = UA::Email.new(client: airship)
email_channel.address = 'name@domain.com'
email_channel.lookupHTTP/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": "2020-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": "2020-10-28T10:34:22",
"commercial_opted_out": "2020-06-03T09:15:00",
"transactional_opted_in": "2020-10-28T10:34:22",
"last_registration": "2020-05-01T18:00:27"
}
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.GET /api/channels/email/{email}
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:
path PARAMETERSemail : String Required
The email address of the channel you want to look up.
Responses
200
A channel exists for the email address
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Describes a channel.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Update an Email Channel
Example: 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"
}
}require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
email_channel = UA::Email.new(client: airship)
email_channel.channel_id = '251d3318-b3cb-4e9f-876a-ea3bfa6e47bd'
email_channel.type = 'email'
email_channel.address = 'new.name@new.domain.com'
email_channel.updateHTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"channel_id": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd"
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.PUT /api/channels/email/{email}
Update an email channel. You can use this endpoint to update the email address associated with a channel and subscription/unsubscription values.
Security:
path PARAMETERSemail : String Required
The email
channel_idyou want to modify.
Request Body
Content-Type: application/json
Email Channel Object : Object
An email channel object is the object used to create or update channels.
There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal noticies, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out).
Each channel uses
opted_inandopted_outkeys 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 noopted_inoropted_outvalues 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
OBJECT PROPERTIEScommercial_opted_inandcommercial_opted_outvalues; if the opt-in date is prior to the opt-out date, the user will not receive commercial emails from you.channel : ObjectRequired
OBJECT PROPERTIESaddress : StringRequired
The email address being registered.
commercial_opted_in : String
The date-time when a user gave explicit permission to receive commercial emails.
commercial_opted_out : String
The date-time when a user explicitly denied permission to receive commercial emails.
locale_country : String
The device property tag related to locale country setting.
locale_language : String
The device property tag related to locale language setting.
timezone : String
The device property tag related to timezone setting.
transactional_opted_in : String
The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.
transactional_opted_out : String
The date-time when a user explicitly denied permission to receive transactional emails.
type : StringRequired
The type of channel you are registering. For email channels, this value must be
email. Possible values:email
Responses
200
The email channel was updated.
RESPONSE HEADERSLocation : String
The updated email channel.
Format:
uri
RESPONSE BODYContent-Type: text/plain
The response body for an email channel request.
OBJECT PROPERTIESchannel_id : String
A unique string identifying the email channel. Format:
uuidok : Boolean
Either
trueorfalse. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.
400
There was a parsing or validation error in the request. Bad Request errors typically include
pathandlocationin the response, to help you find the cause of the error.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
SMS
Register and manage SMS channels. See SMS Platform Information to get started with SMS notifications.
Register SMS Channel
Example
POST /api/channels/sms HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"msisdn" : "15035556789",
"sender": "US:12345",
"opted_in": "2020-02-13T11:58:59",
"timezone": "America/Los_Angeles",
"locale_country": "US",
"locale_language": "en"
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
SmsRegistrationRequest request = SmsRegistrationRequest
.newRegistrationRequest("12345", "15035556789", DateTime.parse("2020-02-13T11:58:59Z"));
Response<SmsRegistrationResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
sms = ua.Sms(airship, sender='12345', msisdn='15035556789')
response = sms.register(opted_in='2020-02-13T11:58:59')require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.opted_in = '2020-02-13T11:58:59'
sms_channel.registerExample Response (With ‘opted_in’)
HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/channels/7c5d7328-9bb4-4ff7-86b0-96a5f1da5868
Content-Type: application/json
{
"ok": true,
"operation_id": "62077236-d032-11e9-af71-ab156113d166",
"channel_id": "7c5d7328-9bb4-4ff7-86b0-96a5f1da5868"
}Example Response (Without ‘opted_in’)
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"ok": true,
"operation_id": "62077236-d032-11e9-af71-ab156113d166",
"push_id": "26350f60-d033-11e9-80e3-33def0e528d1",
"channel_id": "79fbe330-d033-11e9-adfb-df10b89c5e04",
"status": "pending"
}Example Response (Project not configured with sender)
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"ok": false,
"errors": "Unable to retrieve details for sender 12345 with app_key <application key>"
}POST /api/channels/sms
Create an SMS channel. If the channel has not opted in yet (the request did not contain opted_in), Airship creates the channel with opt_in set to false and the user receives a message prompting them to complete the opt-in flow; you can assign assign tags and organize pending channels before the user has finished the opt-in process, but you cannot send messages to channels until they opt in to your audience.
SMS notifications require a sender - a number that recipients will receive SMS notifications from. Contact Airship Support or your Account Manager to provision your project for SMS notifications and complete the configuration.
Avoid repeated registration attempts. Repeated registrations of the same msisdn and sender without an opted_in value will result in multiple opt-in instruction messages being sent to the msisdn.
Security:
Request Body
Content-Type: application/json
Object
OBJECT PROPERTIESlocale_country : String
The ISO 3166 two-character country code. The value for this field becomes a tag in the
ua_locale_countrytag group.locale_language : String
The ISO 639-1 two-character language code. The value for this field becomes a tag in the
ua_locale_languagetag group.msisdn : StringRequired
The mobile phone number you want to register as an SMS channel (or send a request to opt-in). Must be numeric characters only, without leading zeros. 15 digits maximum. Pattern:
^[0-9]*$Max length: 15opted_in : String
The UTC datetime in ISO 8601 format that represents the date and time when explicit permission was received from the user to receive messages.
sender : StringRequired
A long or short code the app is configured to send from. When using a short code, prepend the ISO 3166-1 alpha-2 formatted country code to the short code with a colon, e.g.:
US:12345. Failing to provide the country code will only cause an error if your app contains multiple short code senders for different countries. See the ISO 3166 browsing tool to locate the proper alpha-2 country code. Max length: 100 Min length: 1timezone : String
The IANA identifier for a timezone, e.g. “America/Los_Angeles”. The value in this field becomes a tag in the
timezonetag group.
Responses
200
A channel with this msisdn/sender combination already exists.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
One ofNew channel with opt-in : Object
The request included a valid
OBJECT PROPERTIESopted_invalue. Airship creates a channel that is opted in to your audience.channel_id : String
Unique Channel ID for the SMS channel. Format:
uuidok : Boolean
If true, Airship creates a channel value with
opt_inset totrue.operation_id : String
A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. Format:
uuid
New channel without opt-in : Object
Response to a request that does not include an
OBJECT PROPERTIESopted_invalue. Airship creates a channel withopt_inset tofalseand sends the user a message prompting them to opt in.channel_id : StringRequired
Unique Channel ID for the SMS channel. This channel is created with
opt_inset tofalse, as the user has not yet opted in to your audience. Format:uuidok : BooleanRequired
If true, Airship creates a channel with
opt_inset tofalseand Airship sends a message prompting the user to opt in to your audience.operation_id : StringRequired
A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. Format:
uuidpush_id : StringRequired
Identifies the message prompting the user to opt in to your audience, sent as a result of a request without an
opted_invalue. Format:uuidstatus : StringRequired
The channel has been created but has not yet opted-in. Possible values:
pending
201
The channel was created. If the request did not contain an
RESPONSE HEADERSopted_invalue, the channel is created with apendingstatus and the channel’sopt_invalue is set tofalse; you can assign assign tags and organizependingchannels before the user has finished the opt-in process, but you cannot send messages to channels until they complete the opt-in flow.location : String
URI of the channel, used for later registrations.
Format:
url
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
One ofNew channel with opt-in : Object
The request included a valid
OBJECT PROPERTIESopted_invalue. Airship creates a channel that is opted in to your audience.channel_id : String
Unique Channel ID for the SMS channel. Format:
uuidok : Boolean
If true, Airship creates a channel value with
opt_inset totrue.operation_id : String
A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. Format:
uuid
New channel without opt-in : Object
Response to a request that does not include an
OBJECT PROPERTIESopted_invalue. Airship creates a channel withopt_inset tofalseand sends the user a message prompting them to opt in.channel_id : StringRequired
Unique Channel ID for the SMS channel. This channel is created with
opt_inset tofalse, as the user has not yet opted in to your audience. Format:uuidok : BooleanRequired
If true, Airship creates a channel with
opt_inset tofalseand Airship sends a message prompting the user to opt in to your audience.operation_id : StringRequired
A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. Format:
uuidpush_id : StringRequired
Identifies the message prompting the user to opt in to your audience, sent as a result of a request without an
opted_invalue. Format:uuidstatus : StringRequired
The channel has been created but has not yet opted-in. Possible values:
pending
400
The channel could not be created. This error occurs when the project is not configured with a valid sender, the request was missing required fields, or the msisdn does not meet the E.164 international standard.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESerrors : String
Returned with 40x responses; explains reason for the unsuccessful request.
ok : Boolean
If false, the request was unsuccessful.
Opt-out of SMS messages
Example
POST /api/channels/sms/opt-out HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"sender": "US:12345",
"msisdn": "15035556789"
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
SmsRegistrationRequest request = SmsRegistrationRequest
.newOptOutRequest("12345", "15035556789");
Response<SmsRegistrationResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
sms = ua.Sms(airship, sender='12345', msisdn='15035556789')
response = sms.opt_out()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.opt_outHTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}POST /api/channels/sms/opt-out
This will mark an SMS channel as opted-out (inactive) and it will not receive alerts even when they are addressed in the future. To opt the user back in, call the registration function again with a valid opted_in value.
Security:
Request Body
Content-Type: application/json
Object
OBJECT PROPERTIESmsisdn : StringRequired
The mobile phone number you want to opt-out of SMS messages. Must be numeric characters only, without leading zeros. 15 digits maximum. Pattern:
^[0-9]*$Max length: 15sender : StringRequired
A long or short code the app is configured to send from. When using a short code, prepend the ISO 3166-1 alpha-2 formatted country code to the short code with a colon, e.g.:
US:12345. Failing to provide the country code will only cause an error if your app contains multiple short code senders for different countries. See the ISO 3166 browsing tool to locate the proper alpha-2 country code. Max length: 100 Min length: 1
Responses
202
The msisdn/channel is opted-out of SMS notifications.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If true, the operation completed successfully.
400
The request body is not valid.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESdetails : Object
OBJECT PROPERTIESerror : String
Specific error message that explains why the request was unsuccessful.
error : String
Returned with 40x responses; explains why the request was unsuccessful.
error_code : Integer
The 5-digit Airship error code, pointing to a more specific error than the HTTP Status.
ok : Boolean
If false, the request was unsuccessful.
Uninstall SMS Channel
Example
POST /api/channels/sms/uninstall HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"sender": "US:12345",
"msisdn": "15035556789"
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
SmsRegistrationRequest request = SmsRegistrationRequest
.newUninstallRequest("12345", "15035556789");
Response<SmsRegistrationResponse> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
sms = ua.Sms(airship, sender='12345', msisdn='15035556789')
response = sms.uninstall()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.uninstallHTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}POST /api/channels/sms/uninstall
Removes phone numbers and accompanying data from Airship. Use with caution. Uninstalling an SMS channel will prevent you from retrieving opt-in and opt-out history for the corresponding msisdn. If the uninstalled msisdn opts-in again, it will generate a new channel_id. The new channel_id cannot be reassociated with any opt-in information, tags, named users, Performance Analytics reports, or other information from the uninstalled SMS channel.
Security:
Request Body
Content-Type: application/json
Object
OBJECT PROPERTIESmsisdn : StringRequired
The mobile phone number you want to remove from the Airship system. Must be numeric characters only, without leading zeros. 15 digits maximum. Pattern:
^[0-9]*$Max length: 15sender : StringRequired
A long or short code the app is configured to send from. When using a short code, prepend the ISO 3166-1 alpha-2 formatted country code to the short code with a colon, e.g.:
US:12345. Failing to provide the country code will only cause an error if your app contains multiple short code senders for different countries. See the ISO 3166 browsing tool to locate the proper alpha-2 country code. Max length: 100 Min length: 1
Responses
202
The SMS channel and all information associated with the msisdn is uninstalled.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If true, the operation was successful.
400
The request body is not valid.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESdetails : Object
OBJECT PROPERTIESerror : String
Specific error message that explains why the request was unsuccessful.
error : String
Returned with 40x responses; explains why the request was unsuccessful.
error_code : Integer
The 5-digit Airship error code, pointing to a more specific error than the HTTP Status.
ok : Boolean
If false, the request was unsuccessful.
Update SMS Channel
Example
PUT /api/channels/sms/{channel_id} HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"msisdn": "15035556789",
"sender": "US:12345",
"opted_in": "2020-02-13T11:58:59",
"timezone": "America/Los_Angeles",
"locale_country": "US",
"locale_language": "en"
}HTTP/1.1 200 OK
Content-Type: application/json
{
"ok": true,
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.PUT /api/channels/sms/{channel_id}
Update an existing SMS channel to reflect opt-in date, timezone and/or locale changes. The msisdn and sender in the request must match the existing channel or the request will 404.
Security:
path PARAMETERSchannel_id : String Required
The identifier for the SMS channel you want to update.
Request Body
Content-Type: application/json
Object
OBJECT PROPERTIESlocale_country : String
The ISO 3166 two-character country code. The value for this field becomes a tag in the
ua_locale_countrytag group.locale_language : String
The ISO 639-1 two-character language code. The value for this field becomes a tag in the
ua_locale_languagetag group.msisdn : StringRequired
The phone number corresponding to the
channel_idin the request. You cannot change this value for the existing channel. Pattern:^[0-9]*$Max length: 15opted_in : String
The UTC datetime in ISO 8601 format that represents the date and time when explicit permission was received from the user to receive messages.
sender : StringRequired
The sender corresponding to the
channel_idin the request. You cannot change this value for an existing channel.timezone : String
The IANA identifier for a timezone, e.g. “America/Los_Angeles”. The value in this field becomes a tag in the
timezonetag group.
Responses
200
A channel with this msisdn/sender combination already exists.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
True if the request was successful.
operation_id : String
A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. Format:
uuid
400
The request to update the channel failed. This error occurs when the
msisdnorsenderdon’t match thechannel_idin the request.RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESerrors : String
Returned with 40x responses; explains reason for the unsuccessful request.
ok : Boolean
If false, the request was unsuccessful.
404
Occurs when the
msisdnand/orsenderdon’t match any existingchannel_id.RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESerrors : String
A plain-text explanation of the error.
ok : Boolean
If false, your request was unsuccessful.
SMS Channel Lookup
Example
GET /api/channels/sms/15035556789/12345 HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
sms = ua.Sms(airship, sender='12345', msisdn='15035556789')
channel_info = sms.lookup()require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.lookupHTTP/1.1 200 OK
Data-Attribute: channel
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"channel": {
"channel_id": "84e36d69-873b-4ffe-81cd-e74c9f002057",
"device_type": "sms",
"installed": true,
"push_address": null,
"named_user_id": null,
"alias": null,
"tags": [],
"tag_groups": {
"ua_channel_type": [
"sms"
],
"ua_sender_id": [
"US:12345"
],
"ua_opt_in": [
"true"
]
},
"created": "2020-04-27T22:06:21",
"opt_in": true,
"last_registration": "2020-05-14T19:51:38"
}
}}This operation is not currently supported by the Java Library.GET /api/channels/sms/{msisdn}/{sender}
Lookup an SMS channel by msisdn and sender.
msisdn : Integer Required
The mobile phone number you want to lookup a channel for. 15 digits maximum; may not contain leading zeroes.
Pattern:
^[0-9]*$Max length: 15sender : Integer Required
A long or short code the app is configured to send from. If your app uses the same shortcode for audiences in different countries, prepend the country code to the short code with a colon —
US:12345.
Responses
200
Returns an SMS channel object. An SMS channel object includes tag groups for
ua_channel_type,ua_sender_id, andua_opt_in.RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESchannel : Channel Object
Describes a channel.
ok : Boolean
Success.
404
A
channel_iddoes not exist for themsisdnandsender.RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESerror : String
Returned with 40x responses; explains why the request was unsuccessful.
error_code : Integer
The 5-digit Airship error code, pointing to a more specific error than the HTTP Status.
ok : Boolean
If false, the request was unsuccessful.
Custom SMS Response
SMS Example
POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"sms" : {
"alert": "Your balance is $1234.56. Go to https://www.mybank.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.",
"shorten_links": true
},
"mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.MMS Example
POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <bearer token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"mms" : {
"fallback_text": "See fun cat pics at https://example.com/cat/pics/12345678",
"slides": [
{
"media": {
"url": "https://example.com/cat/pics/12345678.gif",
"content_type": "image/gif",
"content_length": 23098
}
}
],
"shorten_links": true
},
"mobile_originated_id" : "3e1e4fb3-2d3c-431e-96bf-9b235a12f84b"
}HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"operation_id": "f3d0993e-e3e1-4aae-b1c0-864a715bfaff",
"push_id": "7502abe6-e6ea-4f2b-906f-ebbab612c69e"
}POST /api/sms/custom-response
Respond to a mobile originated message based on a keyword consumed by your custom-response webhook, using a mobile-originated ID. See Inbound Message Handling for information about setting up a custom response webhook server.
This endpoint requires bearer authorization.
Security:
Request Body
Content-Type: application/json
One ofObject
OBJECT PROPERTIESmobile_originated_id : StringRequired
The identifier that you received through your SMS webhook corresponding to the mobile-originated message that you’re issuing a custom response to. The
mobile_originated_idis valid for 10 minutes from thereceived_timestampin the payload sent to your webhook server’s/inbound-smsendpoint.Format:
uuidsms : ObjectRequired
OBJECT PROPERTIESalert : StringRequired
Your custom SMS message.
shorten_links : Boolean
If true, Airship will shorten http/https links (space delimited) in the message text fields, producing unique, 25 character URLs for each member of your audience. Airship produces
short_link_clickevents in the Real-Time Data Stream for each link that a user engages with.When this setting is enabled, you can add or remove tags from users who click your links by adding query strings to your URLs. You can serialize tag operations with
&:?ua-tag-add=tag_group:tag&another_group:tag2— adds a tag intag_groupto thechannel_id.?ua-tag-remove=tag_group:tag&another_group:tag2— removes a tag intag groupfrom thechannel_id.
Object
OBJECT PROPERTIESmms : MMS Platform OverridesRequired
Provides the content for a push to MMS channels. If
smsis in thedevice_typearray, your request may include this object. It cannot be combined with an SMS Platform Override as a single push can only include either an SMS or MMS payload.mobile_originated_id : StringRequired
The identifier that you received through your SMS webhook corresponding to the mobile-originated message that you’re issuing a custom response to. The
mobile_originated_idis valid for 10 minutes from thereceived_timestampin the payload sent to your webhook server’s/inbound-smsendpoint.Format:
uuid
Responses
200
The operation was successful.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If
true, your request was successful.operation_id : String
A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. Format:
uuidpush_id : String
A unique identifier for a push operation. Format:
uuid
404
The mobile_originated_id could not be found.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESerror : String
A plain-text explanation of the error.
ok : Boolean
If false, your request was unsuccessful.
operation_id : String
A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. Format:
uuid
Manually Trigger a Keyword Interaction
Example
POST /api/sms/15035556789/keywords HTTP/1.1
User-Agent: Apache-HttpAsyncClient/4.0.1 (java 1.5)
Content-Type: application/json
Authorization: Basic <user:pass>
Connection: close
{
"keyword" : "stop",
"sender_ids" : [ "US:54321", "1234"]
}HTTP/1.1 200 OK
Content-Type: application/json
{
"ok": true
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.This operation is not currently supported by the Ruby Library.Example Failure Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"ok" : false,
"error" : "The following sender(s) are not configured for the 'stop' keyword: ['US:1234']",
"error_code" : 400
}POST /api/sms/{msisdn}/keywords
Trigger Mobile Originated (MO) keyword interactions on behalf of an MSISDN.
Security:
path PARAMETERSmsisdn : String Required
The identifier for the SMS channel you want to trigger a mobile originated keyword from.
Request Body
Content-Type: application/json
Object
OBJECT PROPERTIESkeyword : StringRequired
The keyword you want to trigger an action for.
sender_ids : Array [String]Required
The sender IDs with keyword actions that you want to test. Airship returns a 400 if the
keywordis not configured for one or more of the senders in the array. Min items: 1timestamp : String
The ISO8601 date-time when the MO keyword was sent. If absent, Airship uses the server-time of your request.
Responses
200
The operation was successful.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
OBJECT PROPERTIESok : Boolean
If
true, your request was successful.
400
The operation was not successful. If the request is formatted correctly, one or more
sender_idsdoes not exist or the keyword is not configured for one or more of thesender_ids.RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Named Users
A Named User is a proprietary identifier that maps customer-chosen IDs, e.g., CRM data, to Channels. It is useful to think of a Named User as an individual consumer who might have more than one mobile device registered with your app. For example, Named User “john_doe_123” might have a personal Android phone and an iPad, on both of which he has opted in for push notifications. If you want to reach John on both devices, associate the Channel (device) identifiers for each device to the Named User “john_doe_123,” and push to the Named User. Notifications will then fan out to each associated device.
Named User Listing or Lookup
Example: Named User Lookup
GET /api/named_users/?id=user-456 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
NamedUserListingRequest request = NamedUserListingRequest.newRequest("user-456");
Response<NamedUserListingResponse> response = client.execute(request);
NamedUserView namedUser = response.getBody().get().getNamedUserView().get();
// The named user ID
String namedUserId = namedUser.getNamedUserId();
// Map of tag groups and the associated sets of tags
ImmutableMap<String, ImmutableSet<String>> namedUserTags = namedUser.getNamedUserTags();
// All channel objects associated with the named user
ImmutableSet<ChannelView> channelViews = namedUser.getChannelViews();import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
named_user = ua.NamedUser(airship, 'user-456')
resp = named_user.lookup()
print(resp)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-456'
user = named_user.lookupHTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true,
"named_user": {
"named_user_id": "user-456",
"tags": {
"my_fav_tag_group": [
"tag1",
"tag2"
]
},
"attributes": {
"item_purchased": "Fur removal tool",
"cats_name": "Sammy",
"pets_age": 12
},
"user_attributes": {
"ua_country": "US",
"ua_language": "en",
"ua_tz": "America/Los_Angeles"
},
"channels": [
{
"channel_id": "dceafd02-b852-4305-83df-98b65fa40dd4",
"device_type": "ios",
"installed": true,
"opt_in": true,
"push_address": "FFFF",
"created": "2020-04-08T20:41:06",
"last_registration": "2020-05-01T18:00:27",
"tags": [
"meow"
]
}
]
}
}Example: Named User Listing
GET /api/named_users HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
NamedUserListingRequest request = NamedUserListingRequest.newRequest();
Response<NamedUserListingResponse> response = client.execute(request);
ImmutableList<NamedUserView> namedUsers = response.getBody().get().getNamedUserViews().get();import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
named_user_list = ua.NamedUserList(airship)
for n in named_user_list:
print(n.named_user_id)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
named_user_list = UA::NamedUserList.new(client: airship)
named_user_list.each do |named_user|
puts(named_user)
endHTTP/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": "dceafd02-b852-4305-83df-98b65fa40dd5",
"device_type": "ios",
"installed": true,
"opt_in": true,
"push_address": "FFFF",
"created": "2020-04-08T20:41:06",
"last_registration": "2020-05-01T18:00:27",
"alias": "xxxx",
"tags": ["asdf"],
"ios": {
"badge": 0,
"quiettime": {
"start": "22:00",
"end": "06:00"
},
"tz": "America/Los_Angeles"
}
}
]
}
]
}GET /api/named_users
Return a list of named users or lookup a single named user by named_user_id.
Security:
query PARAMETERSid : String
The
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.
Responses
200
Returns OK for success.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
One ofNamed User Lookup Response Object : Object
Response for a single
OBJECT PROPERTIESnamed_user_idquery.named_user : Named User Object
The response body for a named user listing, including tags, channels and attributes associated with the named user.
ok : Boolean
Success.
Named User Listing Response Body : Object
Response returned when performing this operation without a query.
OBJECT PROPERTIESnamed_users : Array [Named User Object]
next_page : String
There might be more than one page of results for this listing. Follow this URL if it is present to the next page of results. Format:
urlok : Boolean
Success.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Named Users Association
Example: 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"
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
NamedUserRequest request = NamedUserRequest.newAssociationRequest()
.setChannel("df6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.IOS)
.setNamedUserId("user-id-1234");
Response<String> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
named_user = ua.NamedUser(airship, 'user-id-1234')
resp = named_user.associate('df6a6b50-9843-0304-d5a5-743f246a4946', 'ios')require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-id-1234'
named_user.associate(channel_id: 'df6a6b50-9843-0304-d5a5-743f246a4946', device_type: 'ios')Example: 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"
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
NamedUserRequest request = NamedUserRequest.newAssociationRequest()
.setChannel("wf6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.WEB)
.setNamedUserId("user-id-1234");
Response<String> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
named_user = ua.NamedUser(airship, 'user-id-1234')
resp = named_user.associate('wf6a6b50-9843-0304-d5a5-743f246a4946', 'web')require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-id-1234'
named_user.associate(channel_id: 'wf6a6b50-9843-0304-d5a5-743f246a4946')Example: 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"
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
NamedUserRequest request = NamedUserRequest.newAssociationRequest()
.setChannel("em6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.EMAIL)
.setNamedUserId("user-id-1234");
Response<String> response = client.execute(request);require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
named_user = UA::NamedUser.new(client: airship)
named_user.named_user_id = 'user-id-1234'
named_user.associate(channel_id: 'em6a6b50-9843-0304-d5a5-743f246a4946')HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}This operation is not currently supported by the Python Library.POST /api/named_users/associate
Associate a channel or email address with a named user (named_user_id). If the named_user_id does not already exist, this operation will create it. If the channel_id or email address is already associated with the named_user_id, this operation will do nothing.
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.
Content-Type: application/json
One ofAssociate channel_id with named user : Object
OBJECT PROPERTIESchannel_id : StringRequired
The channel ID you want to associate with a named user. Format:
uuiddevice_type : String
The device type of the channel, e.g.,
ios,android,amazon. Do not specifydevice_typefor web, email, sms, or open channels. Possible values:ios,android,amazonnamed_user_id : StringRequired
A string value identifying the new user with no leading or trailing whitespace. If the named_user_id does not already exist, this operation will create a new named user and associate the
channel_idwith it. Pattern:^[^\s].{1,125}\S$Max length: 128 Min length: 1
Associate email with named user : Object
OBJECT PROPERTIESemail_address : StringRequired
The email address you want to associate with a named user. Format:
emailnamed_user_id : StringRequired
A string value identifying the new user with no leading or trailing whitespace. If the named_user_id does not already exist, this operation will create a new named user and associate the
channel_idwith it. Pattern:^[^\s].{1,125}\S$Max length: 128 Min length: 1
Responses
200
Everything worked as expected.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Named Users Disassociation
Example
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"
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
NamedUserRequest request = NamedUserRequest.newDisassociationRequest()
.setChannel("df6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.IOS);
Response<String> response = client.execute(request);require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
named_user = UA::NamedUser.new(client: airship)
named_user.disassociate(channel_id: 'df6a6b50-9843-0304-d5a5-743f246a4946', device_type: 'ios')import urbanairship as ua
airship = ua.Airship('app_key', 'master_secret')
named_user = ua.NamedUser(airship, 'user-id-1234')
resp = named_user.disassociate('df6a6b50-9843-0304-d5a5-743f246a4946', 'ios')Example: Disassociate an email channel from named user
POST /api/named_users/disassociate HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json
{
"email_address": "monopoly.man@gotojail.com",
"named_user_id": "user-id-1234"
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
NamedUserRequest request = NamedUserRequest.newDisassociationRequest()
.setChannel("em6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.EMAIL)
.setNamedUserId("user-id-1234");
Response<String> response = client.execute(request);require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
named_user = UA::NamedUser.new(client: airship)
named_user.disassociate(channel_id: 'em6a6b50-9843-0304-d5a5-743f246a4946')HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}This operation is not currently supported by the Python Library.POST /api/named_users/disassociate
Disassociate a channel or an email address from a named_user_id.
Security:
Request Body
Content-Type: application/json
Object
OBJECT PROPERTIESchannel_id : String
The 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:uuidemail_address : String
The email address you want to disassociate from the
named_user_id. Format:emailnamed_user_id : String
The named user that you want to remove the channel from. Pattern:
^[^\s].{1,125}\S$Max length: 128 Min length: 1
Responses
200
Everything worked as expected.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Named Users Tags
Example
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"
]
}
}UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
.setKey("<app key>")
.setSecret("<master secret>")
.build();
NamedUserTagRequest request = NamedUserTagRequest.newRequest()
.addNamedUsers("user-1", "user-2", "user-3")
.addTags("crm", ImmutableSet.of("tag1", "tag2", "tag3"))
.addTags("loyalty", ImmutableSet.of("tag1", "tag4", "tag5"))
.removeTags("loyalty", ImmutableSet.of("tag6", "tag7"));
Response<String> response = client.execute(request);import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
named_user = ua.NamedUser(airship, 'user-1')
resp1 = named_user.tag(
'loyalty',
add=['tag2', 'tag3', 'tag4'],
remove='tag1'
)
resp2 = named_user.tag(
'crm',
set=['tag5', 'tag6']
)require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
named_user_tags = UA::NamedUserTags.new(client: airship)
named_user_ids = ['user-1', 'user-2', 'user-3']
named_user_tags.set_audience(user_ids: named_user_ids)
named_user_tags.add(group_name: 'crm', tags: ['tag1', 'tag2', 'tag3'])
named_user_tags.remove(group_name: 'loyalty', tags: ['tag6', 'tag7'])
named_user_tags.send_requestHTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}POST /api/named_users/tags
Add, remove, or set tags on a named user. A single request body may contain add and/or remove objects, or a single set field. At least one of the add, remove, or set objects must be present in a request.
A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response. We support up to 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
Content-Type: application/json
Object
OBJECT PROPERTIESadd : Tag Group Object
Add the list of tags to the named user(s), but do not remove any. If the tags are already present, they are not modified.
audience : ObjectRequired
The named user(s) you want to associate/disassociate tags with.
OBJECT PROPERTIESnamed_user_id : Array [String]
Max items: 1000 Min items: 1
remove : Tag Group Object
Remove the list of tags from the named user(s), but do not remove any others. If the tags are not currently present, nothing happens.
set : Tag Group Object
Set these tags for the audience; any tags previously associated with the audience tags that are not in this current list are removed.
Responses
200
Everything worked as expected.
RESPONSE BODYContent-Type: application/vnd.urbanairship+json; version=3;
Returned with 2xx Responses. At a minimum, 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
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 BODYContent-Type: application/vnd.urbanairship+json; version=3;
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key & secret or bearer token) was either incorrect or missing.
RESPONSE BODYContent-Type: text/plain
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
RESPONSE BODYContent-Type: application/json
Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
Named Users Uninstall
Example: Delete 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"]
}require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')
named_user_uninstall = UA::NamedUserUninstaller.new(client: airship)
named_user_uninstall.named_user_ids = ['user-id-1234']
named_user_uninstall.uninstallHTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3;
{
"ok": true
}This operation is not currently supported by the Java Library.This operation is not currently supported by the Python Library.POST /api/named_users/uninstall
Disassociate and delete all channels associated with the named_user_id(s) and also delete the named_user_id(s). This call removes all channels associated with a named user from Airship systems in compliance with data privacy laws.
Uninstalling channels also removes accompanying analytic data (including Performance Analytics) from the system.
See Individual Data Privacy Rights Under Data Privacy Laws for more information about data privacy law compliance.
Channel uninstallation, like channel creation, is an asynchronous operation, and may take some time to complete.
Security:
Request Body
Content-Type: application/json
Object
OBJECT PROPERTIES