Audiences—import an audience

At a glance: Import predefined audience segments from your internal systems (such as BI and CRM) to AppsFlyer Audiences, allowing you to use Audiences to connect and maintain these segments with your advertising partners.

Why import audiences?

In certain circumstances, you may have predefined audience segments in your internal systems. Importing these audiences (as lists of device and/or user identifiers) to AppsFlyer allows you to use Audiences as your central point for connecting and maintaining all of your audience segments with your advertising partners. Additionally, it enables you to take full advantage of other Audiences features, such as identifier matching/data enrichment and connected campaign metrics.

Consider the following examples:

 Examples

Promotional remarketing
You want to target promotional offers to users during the month of their birthdays.

Here's how to do it with Audiences:

  1. Use your internal CRM to generate a list of users along with their birthdays.
  2. Segment the list according to birthday month, and export it as individual lists of advertising IDs.
  3. Import the lists to AppsFlyer as audiences and connect them to the partners with which you want to run the promotional campaigns.
  4. Set up campaigns with the relevant partners to target the audiences accordingly.

Acquiring additional users
Your app development studio acquires another studio. The studio you acquired has the device IDs of users who previously installed their apps, and you want to target these users to install your existing apps.

Here's how to do it with Audiences:

  1. Obtain the list of device IDs from the studio you acquired, and import it to AppsFlyer as an audience.
  2. Connect the audience to the partners with which you want to run campaigns.
  3. Set up campaigns with the relevant partners to target these users accordingly.

Audiences import V2.0

The remainder of this article describes concepts and procedures related to the new Audiences import feature V2.0 (with options for importing by CSV and API). Legacy procedures for Audiences import V1.0 (CSV and API) can be found here.

Imported audience types

When you import an audience, you designate it as one of two types, which determines how AppsFlyer treats the uploaded audience, both in terms of processing and uploading it to partners. This election is made when an audience is first imported and can't be changed later.

A standard imported audience:

  • Undergoes identifier matching and data enrichmenta process in which Audiences matches imported identifiers with existing identifiers in the Audiences database (for the same user on the same app) in order to enrich audience data uploaded to partners.
  • Is uploaded to partners subject to your account's user identifier policy.
  • Must be imported using the V2.0 import feature described in this article.

An as-is imported audience:

  • Doesn't undergo identifier matching and data enrichment.
  • Is uploaded to partners without reference to your account's user identifier policy (meaning all imported identifiers are uploaded to partners).
  • Can be imported using either the V2.0 import feature (described in this article) or using the V1.0 legacy import feature.

 Important!

  • All audiences existing as of November 23, 2021, are designated as-is audiences and cannot be changed to standard audiences. You can continue to update these audiences as necessary using either the V2.0 import feature (described in this article) or the V1.0 legacy import feature.
  • Only an admin can designate a new imported audience as an as-is audience.

Audience import procedures

Import an audience either by uploading a CSV file or using the Import Audience API.

Import a CSV file

Prepare a CSV file, with the following specifications:

Format

  • One column for each user identifier being uploaded
  • A header row with the name of the identifier in each column (all lowercase)
  • No blank rows
  • Maximum number of rows: 10 million
  • If you prepare the file using Excel, save it as a CSV (Comma delimited) (*.csv) file, as shown in the following image:

    CSV.jpg

identifier hash

Columns and identifiers

  • Data is ingested using the header row to identify the data in each column, therefore:
    • There is no requirement that columns appear in a specific order.
    • There is no requirement to include columns for identifiers not being uploaded.
  • Available identifiers:
    • app_id
    • idfv
    • idfa
    • gaid
    • oaid
    • imei
    • cuid
    • emails
    • phone
    • phone_e164
    • braze_id
    • amplitude_id
  • Required identifiers:
    • For Android audiences: app_id + one of: gaid OR oiad OR imei OR cuid OR braze_id OR amplitude_id
    • For iOS audiences: app_id + one of: idfv OR idfa OR cuid OR braze_id OR amplitude_id
    Note: app_id is not required for as-is audiences

Example CSV files:

new-import-android-example.csv
new-import-ios-example.csv

To create and import a new audience using a CSV file:

  1. Go to Integration > Audiences.

  2. Click the Import audience button.
    The New audience screen opens, with the Define tab displayed.

  3. Enter a unique Audience Name.

  4. Select the audience platform: Android or iOS.

  5. Indicate whether this audience is a standard audience or as-is audience.
    • For a standard audience, leave the box unchecked.
    • For an as-is audience, check the box. (Note: This option is available only to admins.)
  6. Click Save audience and proceed.
    The Import tab is displayed.
  7. In the Import using CSV section, keep the default of Add new devices/users (since this is a new audience).
  8. Select the CSV file to upload.
    Wait for the confirmation message Uploaded successfully.
  9. Click Next.
    The Connect tab is displayed.
  10. (Optional) Follow the instructions for connecting an audience to partners.
  11. Click Done.

Your audience is now visible in the Audiences dashboard, and it has been imported and connected to partners. Note, however, that the newly-imported audience list is not yet available for upload to partners since imported audiences are processed with a data freshness of daily.

To update an existing audience using a CSV file:

  1. Go to Integration > Audiences.

  2. Click on the name of the audience you want to update.
    The Edit audience screen opens, with the Define tab displayed.

  3. If you want to edit the audience name, you can do so here. Otherwise, select the Import tab to upload the new CSV file.

  4. In the Import using CSV section, choose what to do with the uploaded list:
    • Add new devices/users: Add device/user identifiers to the existing audience
    • Remove devices/users from existing audience: Remove device/user identifiers in the uploaded list from the audience
    • Overwrite existing audience with new devices/users: Replace the entire audience with the uploaded list
  5. Select the CSV file to upload.
    Wait for the confirmation message Uploaded successfully.
  6. Click Next.
    The Connect tab is displayed.
  7. Make changes to partner connections for this audience if required.
  8. Click Done.

Your audience has been updated using the CSV file. Note, however, that the revised audience list is not yet uploaded to partners since imported audiences are processed with a data freshness of daily.

Message Cause What to Do
Uploaded successfully    
Seems like your device list is empty. Add some device IDs to it and try again The CSV file is empty

Make sure that the CSV contains at least one device ID.

We couldn’t understand one or more of your device IDs.
  • The CSV format is incorrect
  • The file you uploaded is not a CSV file
  • The CSV file was edited and saved by a program other than a valid CSV editor (i.e. Microsoft Excel)
  • One or more device IDs is in the wrong format
  • Make sure that the CSV is in the required format.
  • Make sure that all device IDs are in the correct format.
  • If you used Excel, save the file as a CSV file described above.
Cannot use import v1 while applying user account policy on audience. You have uploaded a CSV file for a standard audience using the V1.0 import structure. Standard audiences must be uploaded using a CSV in the V2.0 structure. Edit the CSV file you are uploading to use the format, columns, and identifiers described above.
We just had a temporary connection problem and couldn’t upload your file. You can try again now. Possible network error Try uploading the CSV file again.
Confirmation messages

Use the Import Audience API

The Import Audience API is used to either add or remove devices from an audience. Use the procedure that follows to generate the API request URL and the API request body.

API request URL

https://hq1.appsflyer.com/audiences-import-api/v2/{action}?api_token={api_token}
Parameter Description Mandatory
{action}
  • To add devices: add
  • To remove devices: remove
Yes
{api_token}

Your account-specific API token

Yes

API request body

{
  "import_key": "{import_key}",
  "platform": "{platform}",
  "devices":[
    {
    "{identifier_1_name}":"{identifier_1_value}",
    "{identifier_2_name}":"{identifier_2_value}",
    "{identifier_n_name}":"{identifier_n_value}"
    }
  ]
}
Parameter Description Mandatory
{import_key}

Unique key that identifies the audience

  • Use the same import_key for both the add and remove endpoints. 
Yes
{platform}

android or ios

Yes
{device}

The identifiers you are adding for each device/user

  • See Columns and identifiers above for a list of available and required identifiers
  • Maximum number of devices in one call is 10,000
Yes

To import a new audience using the API:

  1. Go to Integration > Audiences.
  2. Click the Import audience button.
    The New audience screen opens, with the Define tab displayed.
  3. Enter a unique Audience Name.
  4. Select the audience platform: Android or iOS.
  5. Indicate whether this audience is a standard audience or as-is audience.
    • For a standard audience, leave the box unchecked.
    • For an as-is audience, check the box. (Note: This option is available only to admins.)
  6. Click Save audience and proceed.
    The Import tab is displayed.
  7. In the Import using API section, keep the default of Add new devices/users (since this is a new audience).
  8. Copy the API request URL (the API token is already included).
  9. Copy the API request body.
  10. Click Next.
    The Connect tab is displayed.
  11. (Optional) Follow the instructions for connecting an audience to partners.
  12. Click Done.
  13. Prepare the API request including the user/device identifiers, and POST it to AppsFlyer as shown in the sample below. 

To update an existing audience using the API:

  1. Go to Integration > Audiences.

  2. Click on the name of the audience you want to update.
    The Edit audience screen opens, with the Define tab displayed.

  3. If you want to edit the audience name, you can do so here. Otherwise, select the Import tab.

  4. In the Import using API section, choose what to do with the uploaded list:
    • Add new devices/users: Add device/user identifiers to the existing audience. 
    • Remove devices/users from existing audience: Remove device/user identifiers from the existing audience.
  5. Copy the API request URL (the API token is already included).
    • Important! Changing this option changes the endpoint path in the code to be copied. Be sure to use the correct endpoint for the action you are taking (in this and future API requests).
  6. Copy the API request body.
  7. Click Next.
    The Connect tab is displayed.
  8. Make changes to partner connections for this audience if required.
  9. Click Done.
  10. Prepare the API request including the user/device identifiers, and POST it to AppsFlyer as shown in the sample below.

Sample request to add devices

HTTP POST 
https://hq1.appsflyer.com/audience-import-api?api_token=
Accept: application/json
Content-Type: application/json
body: {
     "import_key": "EKFH2UMC5PPCU8J7M5QQCBPKIH89E6NCOB7XQFWMC",
     "platform": "android", 
     "devices":[
      {
      "gaid":"c4fc2600-fd62-4511-bc1d-c3495c8b0861",
      "emails":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "app_id":"com.test.app-channel1"
      }
   ]
}
Code Message Description

200

The request was successful

Audience successfully imported

400 Invalid audience platform, this audience is already configured for Android/iOS. To use a different platform, please create a new audience in the UI The platform specified in the request body doesn't match the platform specified when creating the audience
400 X or more of your rows do not contain an app id. You must attach an app id to each row.

When the audience is designated as a standard audience, each row must contain an app_id

400 X or more of your rows does not contain a valid unique identifier

All or some rows do not contain at least one of the following identifiers in a valid format:

  • For Android audiences: gaid OR oiad OR imei OR cuid OR braze_id OR amplitude_id
  • For iOS audiences: idfv OR idfa OR cuid OR braze_id OR amplitude_id
400 Cannot process more than Y devices per request (n devices counted in this request)

The request body contains a list of more than 10,000 device IDs

400 Device list cannot be empty

The request body contains an empty list of devices

You must provide at least 1 device ID per request

400 We couldn’t understand one or more of your device IDs All or some device IDs are not in a valid format

400

X or more of devices to remove contain more than one identifier per device

A remove request was sent with more than one identifier per device 

403 Forbidden Unauthorized request: Incorrect or missing import key
500 Could not parse request

Invalid request body format (not the expected JSON structure or not a JSON)

See the sample request above

Response codes

API limitations

  • You can only add devices to one audience per request
  • You can only remove devices from one audience per request
  • You can send up to 10,000 device IDs per request
Was this article helpful?