Tag Lists

Manage tag lists for organizing and applying tags in bulk.

Note

You cannot update channel information or opt-in status from these endpoints. To update channels, use the appropriate channel registration endpoints.

Create a tag list

Add tags to your contacts by creating a list and uploading CSV file with user identifiers. The body of the request contains the name, description, and optional metadata for the list. After you define a list, you populate it with a call to the Upload Tag List endpoint.

Jump to examples ↓

POST /api/tag-lists

Security:

Request body:

Content-Type: application/json
Tag List metadata object
Contains all user-specified data when defining a tag list in Airship. Although add, remove, and set are optional, one or more must be present.

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/tag-lists HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "name":"ua_tags_foobar",
  "description":"Description of the file being uploaded",
  "extra":{
      "key":"value",
      "another":"etc..."
  },
  "add":{
      "tag-group-name":[
        "tag-value"
      ],
      "tag-group-name2":[
        "tag-value2a",
        "tag-value2b"
      ]
  },
  "remove":{
      "tag-group-name3":[
        "tag-value"
      ]
  },
  "set":{
      "tag-group-name4":[
        "tag-value"
      ]
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://go.urbanairship.com/api/tag-lists/ua_tags_foobar

{
  "ok" : true
}

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

TagListRequest tagListRequest = TagListRequest.newRequest()
        .setName("ua_tags_my_new_list");
        .setDescription("First of many tags lists!")
        .addTags("tag_group1", ImmutableSet.of("tag1","tag2"))
        .removeTags("tag_group2", ImmutableSet.of("tag3","tag4"))
        .setTags("tag_group3", ImmutableSet.of("tag4","tag5"))
        .addExtra("test","value")
Response<GenericResponse> response = client.execute(tagListRequest);

from urbanairship import (
    BasicAuthClient, TagList
)

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

tag_list = TagList(
    client=client,
    list_name="ua_tags_my_new_list",
    description="First of many tags lists!",
    extra={
        "filename": "tags.csv",
        "source": "CRM"
    },
    add_tags={
        "tag-group-name": ["tag-value"],
        "tag-group-name2": ["tag-value2a", "tag-value2b"]
    },
    remove_tags={
        "tag-group-name3": ["tag-value"]
    },
    set_tags={
        "tag-group-name4": ["tag-value"]
    }
)

tag_list.create()

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')
tags = {'tag_group_name': ['tag1', 'tag2']}

tag_list = UA::TagList.new(client: airship)
tag_list.name = 'ua_tags_list_name'
tag_list.create(description: 'description', extra: {'key': 'value'}, add: tags)

Delete tag list

Delete a list. Deleting a list will not affect any previous uploads but will prevent new uploads to the deleted list. For example, this does not remove the tags associated with the previously-uploaded file from the channels in that file.

Jump to examples ↓

DELETE /api/tag-lists/{list_name}

Security:

Path parameters:

list_name stringREQUIRED
The name of the list.

Responses

204
The delete operation was successful.
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

DELETE /api/tag-lists/ua_tags_foobar HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+csv; version=3

HTTP/1.1 204 No Content

Download list errors

During processing, after a list is uploaded, errors can occur. Depending on the type of list processing, an error file may be created, showing a user exactly what went wrong.

Jump to examples ↓

GET /api/tag-lists/{list_name}/errors

Security:

Path parameters:

list_name stringREQUIRED
The name of the list.

Responses

200
Returns OK for success. The response will contain the errors found during list processing.
Response body:
- Content-Type: text/csv
  Type: string
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/tag-lists/ua_tags_foobar/errors HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+csv; version=3

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

8b4de669-16f1-4e71-9a1f-0c62a8235a65,ERROR,"Unknown channel"
abcd,ERROR,"Invalid msisdn"

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

TagListErrorsRequest request = TagListErrorsRequest.newRequest("ua_tags_foobar");
Response<String> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, TagList
)

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

tag_list = TagList(
  airship=client, 
  list_name="ua_tags_foobar", 
  description="example list", 
)

errors = tag_list.get_errors()

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')

tag_list = UA::TagList.new(client: airship)
error_csv = tag_list.errors

Retrieve lists

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

Jump to examples ↓

GET /api/tag-lists

Note

The tag list content will return the data provided in the tag list creation operation. Although add, remove, and set are optional, one or more must be present.

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/tag-lists HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

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

{
  "ok" : true,
  "lists" : [
    {
      "name" : "ua_tags_foo",
      "description" : "",
      "extra" : { "key": "value" },
      "add":{
        "tag-group-name": [
          "tag-value"
        ],
        "tag-group-name2": [
          "tag-value2a",
          "tag-value2b"
        ]
      },
      "remove": {
        "tag-group-name3": [
          "tag-value"
        ]
      },
      "set": {
        "tag-group-name4": [
          "tag-value"
        ]
      },
      "created" : "2013-08-08T20:41:06",
      "last_updated" : "2014-05-01T18:00:27",
      "channel_count" : 0,
      "mutation_success_count": 1000,
      "mutation_error_count": 10,
      "error_path":  "https://go.urbanairship.com/api/tag-lists/users_a/errors",
      "status" : "ready"
    },
    {
      "..." : "..."
    }
  ]
}

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

TagListListingRequest tagListListingRequest = TagListListingRequest.newRequest();
Response<TagListListingResponse> response = client.execute(tagListListingRequest);

from urbanairship import (
    BasicAuthClient, TagList
)

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

# List all tag lists
response = TagList.list(airship=client)
tag_lists = response.json()

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')

tag_list = UA::TagList.new(client: airship)
list_response = tag_list.list

Upload tag list

Upload a CSV that will set tag values on the specified channels or Named Users.

The first entry in the uploaded CSV must be a header row. The first field must be one of the following identifier types: channel_id, msisdn, named_user, email_address.

Only one identifier type is allowed per file.

You must include both msisdn and sms_sender columns when targeting SMS or MMS channel types. See example to the right.

Uploads must be newline-delimited identifiers (text/CSV) as described in RFC 4180, with commas as the delimiter, optionally double-quoted values, UTF-8 encoded, and with CRLF or LF line separators.

Target type	Required column headers
Web	`channel_id`
Open Channel	`channel_id`
iOS	`channel_id`
Android	`channel_id`
Named User	`named_user`
Email	`email_address`
SMS	`msisdn` (numeric and no leading 0) `sms_sender` (numeric)
MMS	`msisdn` (numeric and no leading 0) `sms_sender` (numeric)

Optional Fields: Opt-in dates can optionally be set for new channels when the identifier is an email_address or msisdn.

Target type	Optional column headers
SMS	`ua_opted_in` (UTC Timestamp)
MMS	`ua_opted_in` (UTC Timestamp)
Email	`ua_transactional_opted_in` (UTC Timestamp) `ua_commercial_opted_in` (UTC Timestamp)

Jump to examples ↓

PUT /api/tag-lists/{list_name}/csv

Note

The maximum number of rows 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 your upload 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 header contains too many columns
40013	CSV header’s first field must be an identifier
40018	CSV header does not contain required column for identifier type

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/tag-lists/ua_tags_foobar/csv HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: text/csv

channel_id
c543f3a3-bc1d-4830-8dee-7532c6a23b9a
6ba360a0-1f73-4ee7-861e-95f6c1ed6410
15410d17-687c-46fa-bbd9-f255741a1523
c2c64ef7-8f5c-470e-915f-f5e3da04e1df

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "ok" : true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
TagListUploadRequest tagListUploadRequest = TagListUploadRequest.newRequest("ua_tags_cool_list", "path/to/file.csv");
Response<GenericResponse> response = client.execute(tagListUploadRequest);

from urbanairship import (
    BasicAuthClient, TagList
)

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

tag_list = TagList(
    client=client,
    list_name="ua_tags_cool_list",
    description="example list"
)

tag_list.upload(file_path="path/to/file.csv")

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')

tag_list = UA::TagList.new(client: airship)
tag_list.name = 'ua_tags_list_name'
tag_list.upload(csv_file: 'file_content', gzip: true)

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

msisdn,sms_sender,firstName
5035556789,18588675309,Jane
4155551212,18588675309,Rory

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "ok" : true
}

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

TagListUploadRequest tagListUploadRequest = TagListUploadRequest.newRequest("ua_tags_cool_list", "path/to/sms_file.csv.csv");
Response<GenericResponse> response = client.execute(tagListUploadRequest);

from urbanairship import (
    BasicAuthClient, TagList
)

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

tag_list = TagList(
    client=client,
    list_name="ua_tags_foobar",
    description="example list"
)

tag_list.upload(file_path="path/to/sms_file.csv")

require 'urbanairship'
UA = Urbanairship
airship = UA::Client.new(key: 'app_key', secret: 'master_secret')

tag_list = UA::TagList.new(client: airship)
tag_list.name = 'ua_tags_list_name'
tag_list.upload(csv_file: 'sms_file_content', gzip: true)