Audiences—user attributes


At a glance: Enrich your ability to segment users into relevant groups by adding your data about their characteristics into Audiences.


Related reading: Audiences 

User attributes

User attributes, unlike event-based data, are general characteristics that your users share with you. They can be static, like gender, age, birthday, and country; or dynamic, like the user score in a game.

User attribute data is:

  • Updated using CSV file import or JSON via API. 
  • Stored in a hashed form.
  • Available for use in any audience ruleset

User attribute data is not shared with advertising partners.

User attributes are housed at either the app-level or account-level as described in this article. If using app-level attributes, the account user requires app permission to manage and use the attributes. 

The following scenario provides a detailed explanation of user attributes.

Scenario—app marketer requirements

You, the app marketer, are busy with the following:

  • Maintaining 2 gaming apps: game_a and game_b.
  • Launching game_c
  • Targeting current app users with these user attributes:
    • Favorite sport: Cricket
    • Current game score: 15 or more in one of the current games

The table contains user-attribute data from your CRM. Audience rulesets need access to this data. 

Use CRM data in rulesets

In Audiences, create user attributes (favorite sport and game score). This gives ruleset access to CRM data. 

Scenario user attributes

Name Format Level
Game score Number: Lets you set rules like 'ScoreGameB is greater than 29'.

App-level: User's score is recorded for each game played.

Meaning: ScoreGameA, ScoreGameB.

Favorite sport

String: Lets you set rules like 'whose favorite sport is tennis'.

Note! Values are case-sensitive.

Account-level: User's favorite sport is the same regardless of the app.

Note! A user can have only 1 value associated with account-level attributes.

User attributes in rulesets

User attributes act as filters in secondary rules. This example uses criteria (favorite sport and game score) set by the marketer. 


Implement user attributes

Set up, add, manage, and delete user attributes.

Set up


To manage app-level attributes, an account user must have app permission. 

To set up user attributes follow these procedures: 

  1. Add user attributes.

  2. Do one of the following

  3. Implement user attributes in rulesets.


To add user attributes:

  1. Go to Audiences > User Attributes tab.
  2. Click Add user attribute.


  3. Complete the fields. Field characteristics are listed in the table that follows. 
    • Attribute name
    • Format
    • Level
  4. Click Save.
User attribute fields
Field Characteristics
Attribute name
  • English characters only
  • No punctuation or special characters
  • Same name cannot be used at both the app- and account-level
  • Same name can be used at the app-level; for example, above scenario use of ScoreGameA and ScoreGameB
  • Text: Test if the attribute value is or is not equal to a specified rule value. Example: Is cricket or is not cricket.
  • Number: Test if the attribute value is greater than, less than, or equal to a specified rule value. Example: Score greater than 15
  • Account-level: An attribute has no connection to the app.
    Example: gender, favorite sport
  • App-level: An attribute is app-related. Select the apps associated with the attribute. 


To manage user attributes, go to Audiences > User attributes tab.

Manage user attributes
Function Description
Search and filter

By attribute name, app name, and attribute level.

Sort by  Click a column header to sort table rows.
Import data
Change API import key 

To change the API import key:

  1. Click Import data.
  2. Select API.
  3. Click Refresh import key. 

Note! If scripts have embedded keys, make sure to update them with the new key. 


AppsFlyerAdmin_us-en.png Only an admin user can delete an attribute.

To delete an attribute that is part of a ruleset:

  1. Remove the attribute from the ruleset.
  2. Delete the attribute.

Import data

Import field specifications

User-attribute field list
Field Content Format Add data
by CSV
Remove data by CSV

Includes 1 of these user IDs:

  • IDFA
  • GAID
 Text Either device_id or customer_id is mandatory

Either device_id or customer_id is mandatory


To remove existing data, don't send

customer_id  Customer user ID  Text Either device_id or customer_id is mandatory

Either device_id or customer_id is mandatory


To remove existing data, don't send


App-level attribute: App ID as it displays in the dashboard.

For iOS apps, include the prefix ID

Account-level attribute: Always populate with * 

Text Mandatory Mandatory
attribute_key User-attribute name, exactly as it displays on the user-attributes tab. Text Mandatory Mandatory

Assigned value

*See limitations

Text or number Mandatory Don't send

Import data by CSV

User-attribute data is added or removed via a CSV file. The figure and example CSV file that follows, match the scenario describing the feature in this article.



CSV file requirements

  • No header row
  • Contains all the columns listed in the preceding table. 

To import a CSV file:

  1. Click Import data.
  2. Select CSV.
  3. Select either:
    • Add data
    • Remove data 
  4. Choose a CSV file to import. 
  5. Click Upload; an upload status message will appear. 

Import data by API

This import method requires a request URL and JSON with user-attribute data.

  1. In the dashboard, get the prepared API request calls and JSON template.
  2. Populate the JSON template with your data according to the field specifications

To generate the API request URL and JSON template:

  1. Click Import data.
  2. Select API.
  3. Select an action:
    • Update user-attributes: Overwrite or add.
    • Remove user-attributes.
    • Remove user data: Removes all data relating to a specific user. User is identified by their AppsFlyer ID.
    • Remove app data: Removes all data at the app level. 
  4. Copy the generated API request URL.
  5. Copy the generated API request body.
  6. Prepare the JSON (with its user-attribute data) using the specified JSON format. For account-level attributes set "app_ids": ["*"]
  7. Prepare the API call based on the URL and request body.
  8. Send the request programmatically.
Example request and JSON
  "import_key": "c733e4d7-b538-4d12-a2ef-ffffffffffff",
  "attributes_values": [
      "device_id": "",
      "customer_id": "",
      "app_ids": [],
      "attributes": [
          "attribute_key": "",
          "attribute_value": ""


You must authenticate the request using an Authorization Bearer Header with an API token V2.0

Example with multiple device IDs, attribute keys, and attribute values
    "import_key": "c733e4d7-b538-4d12-a2ef-ffffffffffff",
    "attributes_values": [
            "device_id": "0bcfc579-f1f3-4452-9111f",
            "customer_id": "2222222",
            "app_ids": ["game.a.demo"],
            "attributes": [
                    "attribute_key": "score",
                    "attribute_value": 5
                    "attribute_key": "favorite_sport",
                    "attribute_value": "cricket"
            "device_id": "555555-d1d1-d1d1-555-fffffffff",
            "customer_id": "111111",
            "app_ids": ["game.a.demo"],
            "attributes": [
                    "attribute_key": "order",
                    "attribute_value": 7
                    "attribute_key": "number",
                    "attribute_value": 8
Example with a single device ID and multiple attribute keys and values
    "import_key": "c733e4d7-b538-4d12-a2ef-ffffffffffff",
    "attributes_values": [
            "device_id": "0bcfc579-f1f3-4452-9111f",
            "customer_id": "12345678",
            "app_ids": ["game.a.demo"],
            "attributes": [
                    "attribute_key": "score",
                    "attribute_value": 90
                    "attribute_key": "favorite-sport",
                    "attribute_value": "cricket"
                    "attribute_key": "orderNumber",
                    "attribute_value": 93
                    "attribute_key": "netPromoterScore",
                    "attribute_value": 94


  • Only integer (whole) numbers are supported in CSV/API import data. Float type (decimal) numbers are not supported. Example: A "score" attribute value can be 90, but not 90.5.
  • User-attribute data can't be printed or downloaded. 
  • API limitation: Maximum 1000 API requests per minute, 5K devices for flat payload (5K devices with one attribute, 2.5K devices with 2 attributes, etc.)
  • CSV limitation: Maximum 10 million rows
  • Attribute value limitations:

    • No commas, dots, or other special characters inside attribute values.
    • There is a length limitation of 40 characters for a string attribute value.
    • Attribute values can't start with 0.