# Named User

A Named User is a proprietary identifier that maps customer-chosen IDs, e.g., CRM data, to Channels. Schemas for managing Named Users, their associations, and updates.


## Named User object {#nameduserresponsebody}

The response body for a Named User listing, including tags, channels and attributes associated with the Named User.

[Jump to examples ↓](#nameduserresponsebody-examples)

- **`attributes`** `object` <[Custom and predefined Attributes]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#attributes)> **REQUIRED**

  Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign.

This object enumerates predefined attributes, but you can [create your own in the Airship dashboard](/docs/guides/audience/attributes/adding/).


- **`channels`** `array` <[Channel listing object]({{< ref "/developer/rest-api/ua/schemas/channels/" >}}#channellistingobject)> **REQUIRED**

  Listing of channels associated with the Named User.

- **`created`** `string` **REQUIRED**

  The creation [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format).

  Format: `date-time`

- **`last_modified`** `string` **REQUIRED**

  The last modified [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format).

  Format: `date-time`

- **`named_user_id`** `string` **REQUIRED**

  A customer-chosen ID that represents a user, e.g., CRM ID. This ID cannot have leading or trailing whitespace.

  Example: `john_doe`

- **`subscription_lists`** `array` <[Subscription List item object]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#namedusersubscriptionlistitem)> **REQUIRED**

  A list of subscription list items associated with the Named User.

- **`tags`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)> **REQUIRED**

  One or more tag group objects associated with the Named User. See [Named User Tags](/docs/developer/rest-api/ua/operations/tags/#modifynamedusertags).

  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](/docs/reference/data-collection/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.

- **`user_attributes`** `object` **REQUIRED**

  User attributes consist of three values that are copied from the last channel associated with the Named User.

  **OBJECT PROPERTIES**

  - **`ua_country`** `string`

    An ISO 3166 two-character country code. Example: "US".

  - **`ua_language`** `string`

    An ISO 639-1 two-character language code. Example: "en".

  - **`ua_local_tz`** `string`

    Time zone as a string. Example: "America/Los_Angeles"


**Used in:**

- [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser)

**Examples**

*Example Named User*

```json
{
  "named_user": {
      "named_user_id": "user-id-1234",
      "created" : "2020-04-08T20:41:06",
      "last_modified" : "2020-05-01T18:00:27",
      "tags": {
        "loyalty program": [
            "silver-member",
            "ten-plus-years",
            "valued-customer"
        ],
        "crm id": [
            "abc-123-def-456"
        ]
      },
      "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"
            ]
        }
      ]
  }
}

```

---

## Named User update payload {#nameduserupdate}

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.


- **`associate`** `array`

  Associate a list of channels or email addresses with the Named User.
If the `channel_id` or `email_address` is already associated with the Named User,
this operation will do nothing.


  **Any of:**

    - **`channel_id`** `string` **REQUIRED**

      Format: `uuid`

      Example: `9c36e8c7-5a73-47c0-9716-99fd3d4197d5`

    - **`device_type`** `string`

      The device type of the channel.
If the channel is not yet registered in Airship and `device_type` is not provided a 400 will be returned.


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

    - **`email_address`** `string` **REQUIRED**

      This email channel must already be registered in Airship or a 400 will be returned


      Format: `email`

      Example: `user@example.com`


- **`attributes`** `array` <[Attribute assignment]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#attributesobject)>

  Set or remove attributes on a Named User.

A single request body may contain `set` or `remove` operations, or both.
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 at least one of the attributes included in the request is valid,
i.e., at least one attribute exists, Airship returns a 200 with a warning containing a
list of attributes that failed to update.


- **`disassociate`** `array`

  Disassociate a channel or an email address from the Named User.


  **Any of:**

    - **`channel_id`** `string` **REQUIRED**

      Format: `uuid`

      Example: `9c36e8c7-5a73-47c0-9716-99fd3d4197d5`

    - **`device_type`** `string`

      The device type of the channel.
If the channel is not yet registered in Airship and `device_type` is not provided a 400 will be returned.


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

    - **`email_address`** `string` **REQUIRED**

      This email channel must already be registered in Airship or a 400 will be returned


      Format: `email`

      Example: `user@example.com`


- **`tags`** `object`

  Add, remove, or set tags on a Named User. A single request body may
contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects
must be present in a request.

A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return
a 400 response.

If at least one of the tags included in the request is valid,
i.e., at least one tags exists, Airship returns a 200 with a warning containing a
list of tags that failed to update.


  **OBJECT PROPERTIES**

  - **`add`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)>

    Add the list of tags to the Named User, 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](/docs/reference/data-collection/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.

  - **`remove`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)>

    Remove the list of tags from the Named User, 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](/docs/reference/data-collection/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]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)>

    Set these tags for the Named User; any tags previously associated 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](/docs/reference/data-collection/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.


**Used in:**

- [Named User update]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#updatenameduser)

---