---
title: "Create or update a single user with attributes, subscriptions, and identifiers"
method: POST
path: "/v2/user/attributes"
tags: ["User Properties"]
---

# Create or update a single user with attributes, subscriptions, and identifiers

`POST /v2/user/attributes`

Creates or updates a single user record, including associated attributes, subscriptions, and identifiers. If a user with the provided identifiers already exists, their information will be updated; otherwise, a new user will be created.

There is a limit of 100 of custom attributes that can be created. If intending to update an existing attribute, the name of the key must match the name of the existing attribute. If an existing attribute does not exist, a new attribute will be created with the given key as the name. Attributes with enumerated values must have a value that matches an existing enum value; new enum values will not be created.  Attempting to pass custom attributes as an array or a map such as `["New York City]` or `{"favorite city": "Boston"}` will result in a 400 error.

Default Rate Limit: 150 requests per second

## Request body

- CreateUserAttributesRequestDtoV2
  - `attributes` object — Personal details about the user. These attributes will take priority over custom properties. All fields are considered optional.
    - `firstName` string — The user's first name.
    - `lastName` string — The user's last name.
    - `demographic` object — An object containing additional personal and professional details.
      - `language` string — The user's preferred language.
      - `dateOfBirth` string, date — The user's date of birth in YYYY-MM-DD (ISO-8601 format).
      - `age` integer — The user's age.
      - `organization` string — The organization the user is associated with.
      - `title` string — The user's title (e.g., Mr, Ms, Dr).
      - `website` string — The user's website URL.
    - `location` object — An object containing the user's address and geographical details.
      - `address1` string — The first line of the address (e.g., street name and number).
      - `address2` string — The second line of the address (e.g., apartment or suite).
      - `city` string — The city where the user is located.
      - `state` string — The state where the user is located.
      - `zip` string — The postal or ZIP code.
      - `latitude` string — The geographical latitude.
      - `longitude` string — The geographical longitude.
      - `country` string — The country of the user provided in ISO-3166-1 format
      - `region` string — The region of the user in ISO-3166-2 format
      - `timezone` string — The user's timezone (e.g., EST).
    - `locale` object — An object representing the user's locale information.
      - `language` string — The preferred language in ISO 639-1 format.
      - `country` string — The user's country in ISO 3166-1 alpha-2 format.
    - `custom` object — A key-value object for custom attributes. Please use the correct primitive type for the value. DateTime strings must adhere to ISO-8601 format for proper recognition. The key will be assigned a type corresponding to the type seen of the first value. For example, if 'Age' is passed with the first value of '24', 'Age' will be typed as a 'Number'. There is no need to pass strings in double quotes. Both object keys and object values are case sensitive. "Favorite color" and "Favorite Color" would be considered different custom attributes.
  - `subscriptions` object[] — An array of subscription details, defining how the user prefers to receive communications. Notes: - A legal disclosure is required when a user is opted-in programmatically. - For marketing messages, required [legal language](https://docs.attentivemobile.com/pages/legal-docs/legal-disclosure-language/) must be included. - For transactional messages, you must include a [transactional opt-in unit](https://docs.attentivemobile.com/pages/legal-docs/legal-transactional/). - By default, if a subscription already exists, it will try and record the attempt to create the subscription again. For TEXT subscriptions, this may result in a message being sent to the person indicating that they are already subscribed. - Requests to opt-in subscribers must contain a sign-up source id. - The unique identifier of a sign-up source can be found in the Sign-up Units tab of the Attentive platform in the ID column. If this value is provided in the request, then this sign-up unit will be used for opting in the user in the request. - Phone numbers must be submitted in [e164 format](https://en.wikipedia.org/wiki/E.164). - valid examples: `+19148440001`, `+442071838750`, `+551155256325` - invalid examples: `19148440001`, `+1---914---844---0001`, `1 () 914 844 0001`
    - `signUpSourceId` string, required — A string identifying the source of the user's sign-up.
    - `channel` 'TEXT' | 'EMAIL', required — The communication channel the user is subscribed to (e.g., TEXT). Supported channels include: - TEXT - EMAIL
    - `singleOptIn` boolean — Opt in subscriber silently (do not send a Reply Y to subscribe text). NOTE: This property is disabled (set to false) by default. We strongly recommend maintaining the standard double opt-in flow, as it serves important legal and compliance purposes. If you want to enable single opt-in, we encourage you to speak with your dedicated Client Strategy Manager (CSM) or our White Glove team (whiteglove@attentivemobile.com) before you enable it. If this property is set to true, subscribers will be added without receiving the initial “Reply Y” confirmation text message. This setting bypasses only the “Reply Y” message. The mandatory legal message will still be sent.
  - `identifiers` object — Contains various identifiers used to uniquely identify the user. Notes: - Sending duplicate values could lead to unintentionally bridging users together. - Don't use customIdentifiers to send attributes (e.g., first name, last name). To send those types of attributes, add to the attributes payload. - Avoid sending null values or empty strings. If you don't have a valid identifier, you should omit the field from the payload.
    - `email` string — The user's email address.
    - `phone` string — The user's phone number.
    - `shopifyId` string — The user's Shopify ID, if applicable.
    - `klaviyoId` string — The user's Klaviyo ID, if applicable.
    - `clientUserId` string — Your own unique identifier to be associated with a user to be associated with a user through a phone, email, shopify id, klaviyo id, or custom identifier. Please do NOT put Shopify IDs or Klaviyo IDs here, there are dedicated fields for those identifiers. There is a 100-character limit.
    - `customIdentifiers` CustomIdentifier[]
      - `key` string, required — The name of the custom identifier.
      - `value` string, required — The value of the custom identifier.

## Response `202`

Accepted

- Success — A successful response.
  - `success` boolean — Indicates whether the request was successful.
  - `message` string — A message with the result of the request.

## Other responses

- `400` — Invalid parameter in request query or body
- `401` — Unauthorized
- `403` — Access Denied
- `404` — The specified resource was not found
- `429` — The user has sent too many requests in a given amount of time
- `500` — Internal Server Error

---

[API](https://skmtc.net/attentive/apis/attentive-api-v2.md) · [All operations](https://skmtc.net/attentive/apis/attentive-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/attentive/attentive-api-v2/revisions/be387e501197/schema)