---
title: "Named user update"
method: POST
path: "/api/named_users/{named_user_id}"
tags: ["Named Users"]
---

# Named user update

`POST /api/named_users/{named_user_id}`

## Request

- Base URL: `https://go.urbanairship.com`
- URL: `https://go.urbanairship.com/api/named_users/{named_user_id}`
- Auth: one of:
  - HTTP basic
  - HTTP basic
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `http://oauth2.{domain}.com/token` scopes: `nu`
- TypeScript: <https://skmtc.dev/airship/apis/airship-api/docs/api/named_users/:named_user_id/post.ts> (a function with typed inputs; its response is checked against the schema)

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

## Path parameters

- `named_user_id` string, required

## Request body

- 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` union[]: 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.
    - union
      - NamedUserChannelTarget
        - `channel_id` string, uuid, required
        - `device_type` 'ios' | 'android' | 'amazon' | 'web' | 'email' | 'sms' | 'open': 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.
      - NamedUserEmailTarget
        - `email_address` string, email, required: This email channel must already be registered in Airship or a 400 will be returned
  - `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.
    - `attributes` union[], required: The attributes that you want to set for, or remove from, your `audience`. You can have both `set` and `remove` actions in the same request.
      - union
        - SetAttributeObject: Add a new attribute, or edit the value of an existing attribute, for the audience.
          - `action` 'set', required: Indicate that you want to `set` an attribute on the audience.
          - `key` string, required: The attribute ID for the attribute you want to set. JSON attribute key values must be in format `<attribute_ID>#<instance_ID>`. See [JSON attributes](/guides/audience/attributes/about/#json-attributes) in *About attributes*.
          - `timestamp` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the attribute changed. If you don't enter a timestamp, Airship uses the current time.
          - `value` union, required: The value that you want to set for an attribute. Accepts numbers and strings for integer/number type attributes, but your string must be convertible to a number or the request will fail. You can also set an object, which must be valid JSON or the request will fail.
            - string
            - number
            - AttributesValueObject
              - …
        - RemoveAttributeObject: Remove an existing attribute from the audience.
          - `action` 'remove', required: Indicate that you want to `remove` an attribute from the audience.
          - `key` string, required: The attribute ID for the attribute you want to set. JSON attribute key values must be in format `<attribute_ID>#<instance_ID>`. See [JSON attributes](/guides/audience/attributes/about/#json-attributes) in *About attributes*.
          - `timestamp` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the attribute changed. If you don't enter a timestamp, Airship uses the current time.
  - `disassociate` union[]: Disassociate a channel or an email address from the named user.
    - union
      - NamedUserChannelTarget
        - `channel_id` string, uuid, required
        - `device_type` 'ios' | 'android' | 'amazon' | 'web' | 'email' | 'sms' | 'open': 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.
      - NamedUserEmailTarget
        - `email_address` string, email, required: This email channel must already be registered in Airship or a 400 will be returned
  - `tags` NamedUserTags: 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.
    - `add` TagGroupObject: Tag groups appear within the `tags` object for a named user or the `tag_groups` object for a channel. `ua_` is a reserved prefix for Airship-specific tag groups. See [Device property tags](/reference/data-collection/device-property-tags/).
    - `remove` TagGroupObject: Tag groups appear within the `tags` object for a named user or the `tag_groups` object for a channel. `ua_` is a reserved prefix for Airship-specific tag groups. See [Device property tags](/reference/data-collection/device-property-tags/).
    - `set` TagGroupObject: Tag groups appear within the `tags` object for a named user or the `tag_groups` object for a channel. `ua_` is a reserved prefix for Airship-specific tag groups. See [Device property tags](/reference/data-collection/device-property-tags/).

## Response `200`

Request was accepted.

- NamedUserUpdateResponse: Body may contain warnings about portions of the request which were not processed.
  - `attribute_warnings` string: Warnings encountered when processing attributes for this named user.
  - `ok` boolean, required: Set to `true` when status code is `200`.
  - `tag_warnings` string: Warnings encountered when processing tags for this named user.

## Other responses

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

## Changes

- **2026-06-24** `38241778b0c1`: 3 breaking, 3 info
  - removed `subschema #1: Channel, subschema #2: Email address` from the `associate/items/` request property `anyOf` list
  - removed `subschema #1: Channel, subschema #2: Email address` from the `disassociate/items/` request property `anyOf` list
  - removed `subschema #3` from the `attributes/items/attributes/items/oneOf[subschema #1: Set Attribute]/value` request property `oneOf` list
  - added `#/components/schemas/namedUserChannelTarget, #/components/schemas/namedUserEmailTarget` to the `associate/items/` request property `anyOf` list
  - …2 more
  - …this revision’s changelog is incomplete
- **2025-08-28** `3304568aaadc`: 3 breaking
  - removed `subschema #2: Email Address` from the `associate/items/` request property `anyOf` list
  - removed `subschema #2: Email Address` from the `disassociate/items/` request property `anyOf` list
  - removed `subschema #1: Set Attribute, subschema #2: Remove Attribute` from the `attributes/items/attributes/items/` request property `oneOf` list
  - …this revision’s changelog is incomplete

[Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/named_users/:named_user_id/post.md)

---

[API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)