Audiences—import an audience

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:

  

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.
  • You can import as many identifiers as you want in a single CSV file so long as each row includes the required identifiers, as further detailed below.
• 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 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.

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}

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>"
    }
  ]
}

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/audiences-import-api/v2/add?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"
      }
   ]
}

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.