1. Home
  2. /Developer
  3. /REST APIs
  4. /Airship API
  5. /Operations
  6. /Named Users

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

Return a list of Named Users or look up a single Named User by named_user_id.

Jump to examples ↓

GET /api/named_users

Security:

Query parameters:

  • id string
    The named_user_id you want to look up. When querying a named_user_id, the response contains a single named_user object. If you do not query a specific named_user_id, the response returns an array of named_users, in which each object represents an individual Named User.

Responses

  • 200

    Returns OK for success.

    Response body:

    • Content-Type: application/vnd.urbanairship+json; version=3
      One of

  • 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

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

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

{
  "ok": true,
  "named_user": {
      "named_user_id": "user-456",
      "created" : "2020-04-08T20:41:06",
      "last_modified" : "2020-05-01T18:00:27",
      "tags": {
        "my_fav_tag_group": [
            "tag1",
            "tag2"
        ]
      },
      "subscription_lists": [
        {
          "list_ids": ["example_listId-1", "example_listId-5"],
          "scope": "web"
        },
        {
          "list_ids": ["example_listId-2", "example_listId-3"],
          "scope": "app"
        },
        {
          "list_ids": ["example_listId-2"],
          "scope": "web"
        },
        {
          "list_ids": ["example_listId-3"],
          "scope": "email"
        },
        {
          "list_ids": ["example_listId-4"],
          "scope": "sms"
        }
      ],
      "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"
            ]
        }
      ]
  }
}

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();

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-456')
response = named_user.lookup()
print(response)

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.lookup

Example Named User listing

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

HTTP/1.1 200 OK
Data-Attribute: named_users
Link: <https://go.urbanairship.com/api/named_users?start=user-1234>; rel=next
Content-Type: application/vnd.urbanairship+json; version=3

{
   "next_page": "https://go.urbanairship.com/api/named_users?start=user-1234",
   "named_users": [
      {
         "named_user_id": "user-id-1234",
         "created" : "2020-04-08T20:41:06",
         "last_modified" : "2020-05-01T18:00:27",
         "tags": {
            "my_fav_tag_group": ["tag1", "tag2"]
         },
         "subscription_lists": [
         {
            "list_ids": ["example_listId-1", "example_listId-5"],
            "scope": "web"
         },
         {
            "list_ids": ["example_listId-2", "example_listId-3"],
            "scope": "app"
         },
         {
            "list_ids": ["example_listId-2"],
            "scope": "web"
         },
         {
            "list_ids": ["example_listId-3"],
            "scope": "email"
         }
         ],
         "attributes":{
            "item_purchased":"Fur removal tool",
            "cats_name":"fluffy butt",
            "pets_age":2
         },
         "user_attributes": {
            "ua_country": "US",
            "ua_language": "en",
            "ua_tz": "America/Los_Angeles"
         },
         "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"
               }
            }
         ]
      }
   ]
}

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();

from urbanairship import (
    BasicAuthClient, NamedUserList
)

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

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)
end

Named User update

Create or update a Named User by associating/disassociating channels and adding/removing tags and attributes in a single request.

Jump to examples ↓

POST /api/named_users/{named_user_id}

 Warning

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:

Path parameters:

  • named_user_id stringREQUIRED
    A string value identifying the user with no leading or trailing whitespace. If this value contains reserved or special characters they must be URL encoded.

Request body:

  • Content-Type: application/json

    Named User update payload

    At least one of associate, disassociate, tags, or attributes must be provided. If a channel is provided in both associate and disassociate sections, a 400 will be returned.

Responses

  • 200

    Request was accepted.

    Response body:

    • Content-Type: application/json

      Body may contain warnings about portions of the request which were not processed.

      OBJECT PROPERTIES
      • attribute_warnings string

        Warnings encountered when processing attributes for this Named User.

      • ok booleanREQUIRED

        Set to true when status code is 200.

      • tag_warnings string

        Warnings encountered when processing tags for this Named User.

  • 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.

Examples

Create a Named User by associating an email and SMS channel and setting tags and attributes.

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

{
  "associate": [
      {
        "email_address": "john@example.com"
      },
      {
        "channel_id": "f5346fa3-99f1-496d-be37-2895ef58f5a5",
        "device_type": "sms"
      }
  ],
  "tags": {
      "set": {
          "subscription_status": ["gold"],
          "favorites" : ["sports", "stocks"]
      }
  },
  "attributes": [
    {
      "action": "set",
      "key": "name",
      "value": "John"
    }
  ]
}

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

NamedUserUpdateChannel namedUserUpdateChannel = NamedUserUpdateChannel.newBuilder()
        .addChannel(NamedUserUpdateDeviceType.ANDROID_CHANNEL, "aa2ae18c-f4b0-48ac-a859-55f26d2a7439")
        .build();

Attribute lastName = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("pseudo")
        .setValue("Pataki")
        .build();

NamedUserUpdatePayload namedUserUpdatePayload = NamedUserUpdatePayload.newBuilder()
        .addAttribute(lastName)
        .addTags("go", List.of("test1","test2"))
        .removeTags("go",List.of("test3","test4"))
        .addNamedUserUpdateChannel(namedUserUpdateChannel)
        .setAction(NamedUserUpdateChannelAction.ASSOCIATE)
        .build();

NamedUserUpdateRequest request = NamedUserUpdateRequest.newRequest("john", namedUserUpdatePayload);
Response<NamedUserUpdateResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

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

associate = [
  {"email_address": "john@example.com"},
  {"channel_id": "f5346fa3-99f1-496d-be37-2895ef58f5a5", "device_type": "sms"}
]
tags = {
  "set": {
      "subscription_status": ["gold"],
      "favorites" : ["sports", "stocks"]
      }
}
attributes = [
    {
      "action": "set",
      "key": "name",
      "value": "John"
    }
  ]

named_user = NamedUser(
  airship=client,
  named_user_id="john_doe"
)

response = named_user.update(
  associate=associate,
  tags=tags,
  attributes=attributes
)

Named Users association

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.

Jump to examples ↓

POST /api/named_users/associate

 Warning

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. You can associate up to 100 Channel IDs to a Named User.

  • Content-Type: application/json

    One of
    • Named User association payload with Channel ID object
      OBJECT PROPERTIES
      • channel_id stringREQUIRED

        The Channel ID you want to associate with a Named User.

      • device_type string

        The device type of the channel.

        Possible values: ios, android, amazon, web, open, email, sms

      • named_user_id stringREQUIRED

        A string value identifying the user with no leading or trailing whitespace. If the named_user_id does not already exist, this operation will create a new Named User.

    • Named User association payload with email address object
      OBJECT PROPERTIES
      • email_address stringREQUIRED

        The email address you want to associate with a Named User.

      • named_user_id stringREQUIRED

        The existing Named User ID

Responses

  • 200

    The request was accepted but is not guaranteed to be successfully processed. If the Named User has more than 1,000 channels associated with it, the request will be ignored.

    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.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    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

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<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.associate(channel_id='df6a6b50-9843-0304-d5a5-743f246a4946', device_type='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<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.associate(channel_id='wf6a6b50-9843-0304-d5a5-743f246a4946')

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@example.com",
   "named_user_id": "user-id-1234"
}

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();

NamedUserRequest request = NamedUserRequest.newAssociationRequest()
        .setChannel("em6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.EMAIL)
        .setNamedUserId("user-id-1234");

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

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.email_associate(email_address='monopoly.man@example.com')

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')

Named Users disassociation

Disassociate a channel or an email address from a named_user_id.

Jump to examples ↓

POST /api/named_users/disassociate

Security:

Request body:

  • Content-Type: application/json

    One of
    • Named User disassociation payload with Channel ID object
      OBJECT PROPERTIES
      • channel_id stringREQUIRED

        The Channel ID you want to disassociate from a Named User.

      • device_type string

        The device type of the channel.

        Possible values: ios, android, amazon, web, email, sms, open

      • named_user_id string

        The existing Named User ID.

    • Named User disassociation payload with email address object
      OBJECT PROPERTIES
      • email_address stringREQUIRED

        The email address you want to disassociate from a Named User.

      • named_user_id string

        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_id with it.

Responses

  • 200

    The request was accepted but is not guaranteed to be successfully processed.

    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.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    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

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<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.disassociate(channel_id='df6a6b50-9843-0304-d5a5-743f246a4946', device_type='ios')

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')

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@example.com",
   "named_user_id": "user-id-1234"
}

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();

NamedUserRequest request = NamedUserRequest.newDisassociationRequest()
        .setChannel("em6a6b50-9843-0304-d5a5-743f246a4946", ChannelType.EMAIL)
        .setNamedUserId("user-id-1234");

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

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-id-1234')
response = named_user.email_disassociate(email_address='monopoly.man@example.com')

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')

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.

Jump to examples ↓

POST /api/named_users/tags

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • add object<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.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • audience objectREQUIRED

      The Named User(s) you want to associate/disassociate tags with.

      OBJECT PROPERTIES
      • named_user_id array[string]
    • remove object<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.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

    • set object<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.

      Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.

      A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

  • 200

    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-formatted.

    Response body:

    • Content-Type: application/json

      Body may contain warnings about portions of the request which were not processed.

      OBJECT PROPERTIES
      • ok booleanREQUIRED

        Set to true when status code is 200.

      • tag_warnings string

        Warnings encountered when processing tags for this Named User.

  • 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 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.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    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

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"
      ]
  }
}

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();

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<GenericResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, NamedUser
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)
named_user = NamedUser(airship=client, named_user_id='user-1')

resp1 = named_user.tag(
    group='loyalty',
    add=['tag2', 'tag3', 'tag4'],
    remove='tag1'
)

resp2 = named_user.tag(
    group='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_request

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.

Jump to examples ↓

POST /api/named_users/uninstall

 Note

Channel uninstallation, like channel creation, is an asynchronous operation and may take some time to complete.

Security:

Request body:

  • Content-Type: application/json

    OBJECT PROPERTIES
    • named_user_id array[string]REQUIRED

      Array of strings representing the named_user_id(s) you wish to be uninstalled. Must have between 1 to 100 items in the array with a 128 character/byte maximum per item.

Responses

  • 200

    All channels have been deleted and disassociated from the Named User.

    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.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    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

Example delete all users and their associated channels

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

{
   "named_user_id": ["user-id-1234","user-id-5678"]
}

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();

NamedUserUninstallRequest namedUserUninstallRequest = NamedUserUninstallRequest
        .newUninstallRequest(ImmutableList.of("user-id-1234","user-id-5678"));

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

from urbanairship import (
    BasicAuthClient, NamedUser
)

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

response = NamedUser.uninstall(
    client=client,
    named_users=["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.uninstall

Scoped Named User batch operations

Supports multiple operations on a Named User within a single request for a specified scope. The supported operation is subscription_lists. The behavior of each of these operations are the same as their individual request counterpart.

Jump to examples ↓

POST /api/named_users/scoped/{named_user_id}

 Note

If you are using a single-channel Preference Center created before October 10, 2022, that has not been migrated to user-level, use the /api/channels/subscription_lists endpoint to add or remove individual channels to/from your subscription list.

Security:

Path parameters:

  • named_user_id stringREQUIRED
    A string value identifying the user with no leading or trailing whitespace. If this value contains reserved or special characters they must be URL encoded.

Request body:

  • Content-Type: application/json

    Type: object

Responses

  • 200

    The scoped Named User batch operations succeeded.

    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.

  • 406

    Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

    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

Example scoped Named User batch operations

POST /api/named_users/scoped/b8f9b663-0a3b-cf45-587a-be880946e881 HTTP/1.1
Authorization: Basic <application or master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "scoped": [
      {
          "scope": ["app"],
          "subscription_lists": {
              "subscribe": ["stickers", "gifs"],
              "unsubscribe": ["cookies"]
          }
      },
      {
          "scope": ["web"],
          "subscription_lists": {
              "subscribe": ["daily_snacks", "brunch"],
              "unsubscribe": ["promotions"]
          }
      }
   ]
}

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();

Set<NamedUserScopeType> scopeTypes1 = new HashSet<>(Arrays.asList(NamedUserScopeType.APP));
Set<String> subscribeLists1 = new HashSet<>(Arrays.asList("stickers", "gifs"));
Set<String> unsubscribeLists1 = new HashSet<>(Arrays.asList("cookies"));

Set<NamedUserScopeType> scopeTypes2 = new HashSet<>(Arrays.asList(NamedUserScopeType.WEB));
Set<String> subscribeLists2 = new HashSet<>(Arrays.asList("daily_snacks", "brunch"));
Set<String> unsubscribeLists2 = new HashSet<>(Arrays.asList("promotions"));

NamedUserScope namedUserScope1 = NamedUserScope.newBuilder()
        .setScopes(scopeTypes1)
        .setSubscribeLists(subscribeLists1)
        .setUnsubscribeLists(unsubscribeLists1)
        .build();

NamedUserScope namedUserScope2 = NamedUserScope.newBuilder()
        .setScopes(scopeTypes2)
        .setSubscribeLists(subscribeLists2)
        .setUnsubscribeLists(unsubscribeLists2)
        .build();

NamedUserScopedPayload namedUserScopedPayload = NamedUserScopedPayload.newBuilder()
        .addNamedUserScope(namedUserScope1)
        .addNamedUserScope(namedUserScope2)
        .build();

NamedUserScopedRequest request = NamedUserScopedRequest.newRequest("named_user_id", namedUserScopedPayload);
Response<GenericResponse> response = client.execute(request);

Set or remove attributes on Named Users

Set or remove attributes on a Named User.

A single request body may contain a set or remove field, or both, or a single set field. If both set and remove fields are present and the intersection of the attributes in these fields is not empty, then a 400 will be returned.

If an attribute request is partially valid, i.e., at least one attribute exists, Airship returns a 200 with a warning about the attributes that failed to update. The attributes listed in the warnings string will be in CSV format.

Jump to examples ↓

POST /api/named_users/{named_user_id}/attributes

 Note

Airship returns a 200 with a warning if you attempt to set attributes on a Named User that does not exist.

Security:

Path parameters:

  • named_user_id stringREQUIRED
    The Named User you are setting the attributes for.

Request body:

  • Content-Type: application/json

    array<Attributes Object>

    Include an array of attributes objects in your request.

Responses

  • 200

    Success. If an attribute request is partially valid, i.e., at least one attribute exists, Airship returns a 200 with a warning string containing a CSV list of attributes that failed to update. Airship also returns a 200 with a warning if you attempt to set attributes on a named_user, even if the named_user does not exist.

    Response body:

    • Content-Type: application/json

      Body may contain warnings about portions of the request which were not processed.

      OBJECT PROPERTIES
      • ok boolean

        Set to true when status code is 200.

      • warnings string

        Warnings encountered when updating Named User attributes.

  • 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.

Examples

Example

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

{
    "attributes": [
        {
            "action": "set",
            "key": "firstName",
            "value": "Gyuri",
            "timestamp": "2020-09-19 12:00:00"
        },
        {
            "action": "remove",
            "key": "birthDate",
            "timestamp": "2020-09-19 12:00:00"
        },
        {
            "action": "set",
            "key": "lastName",
            "value": "Pataki",
            "timestamp": "2020-09-19 12:00:00"
        }
    ]
}

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();

Attribute firstName = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("firstName")
        .setValue("Gyuri")
        .setTimeStamp(DateTime.parse("2020-09-19T12:00:00Z"))
        .build();

Attribute birthDate = Attribute.newBuilder()
        .setAction(AttributeAction.REMOVE)
        .setKey("birthDate")
        .setTimeStamp(DateTime.parse("2020-09-19T12:00:00Z"))
        .build();

Attribute lastName = Attribute.newBuilder()
        .setAction(AttributeAction.SET)
        .setKey("lastName")
        .setValue("Pataki")
        .setTimeStamp(DateTime.parse("2020-09-19T12:00:00Z"))
        .build();

NamedUserAttributePayload payload = NamedUserAttributePayload.newBuilder()
        .addAttribute(firstName)
        .addAttribute(birthDate)
        .addAttribute(lastName)
        .build();

NamedUserAttributeRequest request = NamedUserAttributeRequest.newRequest("my_named_user", payload);
Response<NamedUserAttributeResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Attribute, ModifyAttributes
)

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

set_major_league = Attribute(
                      action="set",
                      key="major_league",
                      value="sf_giants")

remove_minor_league = Attribute(
                         action="remove",
                         key="minor_league")

set_position = Attribute(
                  action="set",
                  key="position",
                  value="LF")

modifications = ModifyAttributes(
                   airship=client,
                   attributes=[set_major_league,
                               remove_minor_league,
                               set_position],
                   named_user="my_named_user"
                )

modifications.send()