Static Lists

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

Airship automatically deletes a Static list and all its versions after 90 days of inactivity. Timestamps used to calculate the 90-day period are the creation date, when updating list contents or metadata, and when sending a message (pushing) to the list. The creation date is the initial day one of the 90-day period. Each instance of updating or sending to the list resets the timestamp to day one.

After automatic deletion or deleting from the Airship dashboard, the list is removed from the upload history, is no longer visible in the Airship dashboard or through API calls, and is no longer available for audience segmentation.

Create list

Create a static list. The body of the request will contain several of the list object parameters, but the actual list content will be provided by a second call to the upload endpoint. You can upload up to 100 lists per project.

Jump to examples ↓

POST /api/lists

Note

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

Security:

Request body:

Content-Type: application/json
List metadata object
Contains all user-specified data when defining a static list in Airship.
OBJECT PROPERTIES
- description string
  An optional description for the list.
- extra object
  An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.
- name stringREQUIRED
  The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.
  Note: Since the name portion of the URL may represent any Unicode string, it must be encoded properly as a URI path component. The encodeURIComponent function in JavaScript can be used.

Responses

201
The list was created successfully.
Response headers:
- Location string
  The URI of the list, used for later updates.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OK response
  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  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 and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
409
The request conflicts with another request.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

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

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

{
   "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListRequest request = StaticListRequest.newRequest("platinum_members")
                .setDescription("loyalty program platinum members")
                .addExtra("key", "value");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Create a new static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)
static_list.description = 'loyalty program platinum members'
static_list.extra = {'key': 'value'}

response = static_list.create()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
static_list.create(description: 'loyalty program platinum members')

Delete a list

Delete a static list.

Jump to examples ↓

DELETE /api/lists/{list_name}

Warning

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

Security:

Path parameters:

list_name stringREQUIRED
The name of the list.

Responses

204
An API request was successful, but there is no response body to return.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
You cannot delete or modify lists with a ua_ prefixed name.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
Response body:
- Content-Type: application/vnd.urbanairship+json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

HTTP/1.1 204 No Content

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListDeleteRequest request = StaticListDeleteRequest.newRequest("platinum_members");
Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Delete a static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)
response = static_list.delete()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
static_list.delete

Download a list of channels

Allows you to download the contents of a static list (as opposed to a GET /api/lists/{list_name}, which will return metadata about the list). The CSV output from this endpoint will only include entries originally uploaded as ios_channel, android_channel, or amazon_channel.

Jump to examples ↓

GET /api/lists/{list_name}/csv

Security:

basicAuth
oauth2Token : lst

Path parameters:

list_name stringREQUIRED
The name of the list you want to retrieve or update.

Responses

200
Returns a CSV list of channels.
Response body:
- Content-Type: text/csv
  Type: string
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
Response body:
- Content-Type: application/vnd.urbanairship+json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

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

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

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListDownloadRequest request = StaticListDownloadRequest.newRequest("foobar");
Response<String> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Download a static list
response = StaticList.download(
    client=client,
    list_name='platinum_members'
)

Get single list metadata

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

Jump to examples ↓

GET /api/lists/{list_name}

Security:

Path parameters:

list_name stringREQUIRED
The name of the list.

Responses

200
List metadata retrieved successfully.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - description string
    An optional description for the list.
  - extra object
    An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.
  - name string
    The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.
  - ok boolean
    Success.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
Response body:
- Content-Type: application/vnd.urbanairship+json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

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

{
   "ok" : true,
   "name" : "platinum_members",
   "description" : "loyalty program platinum members",
   "extra" : { "key" : "value" },
   "created" : "2020-04-08T20:41:06",
   "last_updated" : "2020-05-01T18:00:27",
   "channel_count" : 1000,
   "status" : "ready"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListLookupRequest request = StaticListLookupRequest.newRequest("platinum_members");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Look up a static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)
response = static_list.lookup()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
static_list.lookup

Retrieve lists

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

Jump to examples ↓

GET /api/lists

Security:

Responses

200
Lists metadata retrieved successfully.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - lists array
    An array of list objects.
  - ok boolean
    Success.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

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

{
   "ok" : true,
   "lists" : [
      {
         "name" : "platinum_members",
         "description" : "loyalty program platinum members",
         "extra" : { "key" : "value" },
         "created" : "2020-04-08T20:41:06",
         "last_modified" : "2020-05-01T18:00:27",
         "channel_count": 3145,
         "status": "ready"
      },
      {
         "name": "gold_members",
         "description": "loyalty program gold member",
         "extra": { "key": "value" },
         "created": "2020-04-08T20:41:06",
         "last_updated": "2020-05-01T18:00:27",
         "channel_count": 678,
         "status": "ready"
      }
   ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListListingRequest request = StaticListListingRequest.newRequest();
Response<StaticListListingResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticLists
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# List all static lists
static_lists = StaticLists(client)
for static_list in static_lists:
    print(
        static_list.name,
        static_list.description,
        static_list.extra,
        static_list.created,
        static_list.last_updated,
        static_list.channel_count,
        static_list.status
    )

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_lists = UA::StaticLists.new(client: airship)

static_lists.each do |static_list|
    puts(static_list)
end

Update list contents

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

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

named_user
ios_channel
android_channel
amazon_channel
sms_channel
email_channel
open_channel
web_channel

The first entry in the uploaded CSV may be a header row, which will be ignored. If present, the header row must contain exactly two entries, and the first column must not be an identifier_type as specified above.

Jump to examples ↓

PUT /api/lists/{list_name}/csv

Note

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

Warning

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

Security:

Path parameters:

list_name stringREQUIRED
The name of the list you want to retrieve or update.

Request body:

Content-Type: text/csv
Type: string

Responses

202
The request has been accepted for processing.
Response body:
- Content-Type: application/json
  OK response
  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

400

Bad Request. Parsing or validating the request failed.

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

Response body:

Content-Type: application/vnd.urbanairship+json; version=3
Error response
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 and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
Response body:
- Content-Type: application/vnd.urbanairship+json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

named_user,customer-42
named_user,room-27
ios_channel,5i4c91s5-9tg2-k5zc-m592150z5634
web_channel,d132f5b7-abcf-4920-aeb3-9132ddac3d5a
android_channel,52b2b587-0152-4134-a8a0-38ae6933c88a
email_channel,ab1a81e3-5af3-4c04-a7ae-d676960e6684
open_channel,6bcf3e63-a38a-44d8-8b0d-2fb5941e74ab
sms_channel,ab1a81e3-aaf3-ac04-a7ae-a676960e6684

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

{
   "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

File dataDirectory = new File("src/data");
String filePath = dataDirectory.getAbsolutePath() + "/platinum.csv";
StaticListUploadRequest request = StaticListUploadRequest.newRequest("platinum_members", filePath);

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Upload a CSV file to a static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)

with open('list.csv', 'r') as csv_file:
    response = static_list.upload(csv_file)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
File.open('csv_file', 'rb') do |csv|
    static_list.upload(csv_file: csv, gzip: false)
end

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

Identifier Type,Identifier
alias,some-user-12345
alias,some-user-12346
ios_channel,5b1a81e3-5af3-4c04-a7ae-d676960e6684
named_user,SODFHsodfuJ9433
named_user,"contains,comma"
named_user,"contains""double-quote"

Update list metadata

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

Jump to examples ↓

PUT /api/lists/{list_name}

Note

To update the list contents, use the list upload endpoint. The update endpoint is used to update a list’s metadata rather than the actual list of device identifiers.

Security:

Path parameters:

list_name stringREQUIRED
The name of the list.

Request body:

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

Content-Type: application/json
List metadata object
Contains all user-specified data when defining a static list in Airship.
OBJECT PROPERTIES
- description string
  An optional description for the list.
- extra object
  An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters.
- name stringREQUIRED
  The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.
  Note: Since the name portion of the URL may represent any Unicode string, it must be encoded properly as a URI path component. The encodeURIComponent function in JavaScript can be used.

Responses

200
The list metadata was updated successfully.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OK response
  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.
400
Bad Request. Parsing or validating the request failed. error_code 40001: Attempted list rename. List renaming is not allowed.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  Error response
  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 and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g., the API may not be used to create or modify lists with a ua_ prefixed name.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
404
The requested resource doesn’t exist.
Response body:
- Content-Type: application/vnd.urbanairship+json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

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

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

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

{
   "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

StaticListRequest request = StaticListRequest.newUpdateRequest("platinum_members")
                .setDescription("loyalty program platinum members")
                .addExtra("key", "value");

Response<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, StaticList
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

# Update an existing static list
static_list = StaticList(
    client=client,
    name='platinum_members'
)
static_list.description = 'loyalty program platinum members'
static_list.extra = {'key': 'value'}

response = static_list.update()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

static_list = UA::StaticList.new(client: airship)
static_list.name = 'platinum_members'
static_list.update(description: 'loyalty program platinum members')