Use API Static Lists

This topic guide covers the Static List API workflow and integration process.

Static Lists are great for targeting groups of users with similar characteristics which are tracked externally, e.g., in your CRM system. For example, if your CRM is tracking customers interested in weekly offers, you can create a weekly offers list in Urban Airship, upload the user list, and manage list membership based on changes in your CRM.

In the weekly offers example, after creating and populating the original list, you would simply refresh the list each week to reflect additions and deletions to the list membership.

In this guide, we examine the process of creating and updating a reusable list, with a focus on automating the update process.

Create a List

If you haven’t already, create an Audience List. Throughout this tutorial, we will use the example of a weekly offers list:

curl "https://go.urbanairship.com/api/lists" \
   -X POST \
   -u "<AppKey>:<MasterSecret>" \
   -H "Accept: application/vnd.urbanairship+json; version=3" \
   -H "Content-Type: application/json" \
   -d '{
          "name": "weekly_offers",
          "description": "customers interested in receiving weekly offers"
       }'

Upload a CSV to Your List

Now that you have created a list, use the csv endpoint to attach a CSV to the list. To begin, create a CSV file containing up to 10 million identifier_type,identifier pairs:

named_user,named_user_id_1
named_user,named_user_id_2
...
ios_channel,1a3c39bc-97f4-4xd8-akz8-e37f11b4bfd8

Suppose we save this list as weekly_offers.csv. To upload this CSV file to our weekly_offers list, we call the PUT /api/lists/(name)/csv/ endpoint:

curl https://go.urbanairship.com/api/lists/weekly_offers/csv/
   -X PUT \
   -u "<AppKey>:<MasterSecret>" \
   -H "Accept: application/vnd.urbanairship+json; version=3" \
   -H "Content-Type: text/csv" \
   --data-binary @weekly_offers.csv

This request attaches the CSV file to our Audience List.

Note that the Static List API is asynchronous. A call to the csv endpoint may take time to process, meaning you may not be able to use a newly uploaded list immediately. Large lists may take several minutes to upload. In the next section, we discuss how to avoid sending a push to an unprocessed list.

Check List Status

After uploading the list, we need to check with the API that the list has finished processing. This step is critical. If you attempt to send to a list before it has finished processing, one of two problems may occur:

  • If you just created the list, you will be unable to push to it.

  • If you are updating an existing list, your push will go to the earlier version of the list.

To avoid either of the above outcomes, check the list status before sending a push. Checking a list’s status is done through the GET /api/lists/(name)/ endpoint:

curl https://go.urbanairship.com/api/lists/weekly_offers/
   -X GET \
   -u "<AppKey>:<MasterSecret>" \
   -H "Accept: application/vnd.urbanairship+json; version=3"

The above request returns a list object:

{
   "ok": true,
   "name": "weekly_offers",
   "description": "customers interested in receiving weekly offers",
   "created": "2015-05-29T12:31:07",
   "last_updated": "2015-05-29T14:56:11",
   "channel_count": 12634,
   "status": "processing"
}

The "status" key gives us the information we are looking for. It can be one of three values:

  • ready: You may push to the list.

  • processing: The list is being resolved by our system.

  • failed: There was an error processing the list.

The status key reflects the status of the last upload attempt. To ensure that the status is referring to your most recent upload attempt, make sure to check the last_updated date. If this date does not reflect your current attempt, then some error occurred during the CSV upload process, and the API did not try to process your CSV. If this is the case, try re-uploading your CSV, paying close attention to see if the API returns any error messages.

If you are okay with manually checking the list status several times, then simply make a request to the above endpoint every couple of minutes and wait for the status key to read "ready".

Alternatively, you could automate this process. Say you have a check_list('list-name') function, that makes a call to the GET /api/lists/(name) endpoint and returns the value associated with the status key. Using this function, you can quickly implement a loop that repeatedly pings our servers until the list has a "ready" status. The Python script below checks the status of our weekly_offers list every 15 seconds:

import time

while True:
   status = check_list('weekly_offers')

   if status == 'ready':
      print "List is ready"
      break
   elif status == 'failed':
      print "List failed to process"
      break
   else:
      time.sleep(15)

The above example is very simple, but it can be expanded or written in whatever language is best for your integration. However you choose to implement this script, the general idea is to continually ping the GET /api/lists/(name) endpoint until you receive a "ready" or "failed" response.

Push to Your List

Now that the system has successfully finished processing, your list is available for targeting with an audience selector in the Push API.

Below is an example cURL request which sends a push notificiation to your newly-created weekly_offers list and deep-links to your offers content.

curl https://go.urbanairship.com/api/lists/ \
   -X POST \
   -u "<AppKey>:<MasterSecret>" \
   -H "Accept: application/vnd.urbanairship+json; version=3" \
   -H "Content-Type: application/json" \
   -d '{
          "audience": { "static_list": "weekly_offers" },
          "device_types": "all",
          "notification": {
             "alert": "Check out these deals!",
             "open": {
                "type": "deep_link",
                "content": "offers"
             }
          }
       }'