Import an audience to Audiences

At a glance:  Import advertising IDs generated from other systems, like BI and CRM into your audiences. The imported IDs form part of a ruleset to add additional IDs to the audience or as an exclude list to prevent IDs from being included in the audience.

Audiences import procedures

In the Audiences user interface, at the import list stage, select one of the following:

  • Overwrite the existing list
  • Add to the existing list
  • Exclude (remove) from the existing list 

Lists can be imported by file upload in the interface or by API.

 Examples

Promotional retargeting 

To target users who have a birthday with promotional offers.

You can do the following:

  1. Use your other system to generate a list of users with birthdays. Export this list as a list of advertising IDs
  2. Upload the list to AppsFlyer and send it to the audience partner of choice
  3. Setup up a campaign in the audience partner to target the audience accordingly

Acquiring additional users

Your app development studio acquires another studio. This studio has a list of users that installed their apps and you want to target these users to install your existing apps.

You can do the following:

  • Take the list of device advertising IDs that belong to the users of the studio that you acquired
  • Import this list to AppsFlyer and upload it to your audience partner of choice
  • Target these users to install your apps

Import audience by uploading a CSV file

Prerequisites:

Prepare a CSV file with the following format and schema:

  • One column
  • No heading row
  • No blank rows
  • Rows contain a single advertising ID
  • Maximum number of rows:10 million.
  • If you prepare the file using Excel, save it as a CSV (Comma delimited) (*.csv) file. Select the file type as shown in the figure that follows.

    CSV.jpg

Example CSV file:

d5e97b54-5ded-4570-ad87-fe9b42f18820
c2595c12-9110-4c09-a80e-34cf6c0caf61
ae2fbdf8-82f1-46a8-8a84-13d6da7e2c7c
7a1e87b9-b4c2-4869-a55e-5bf1d1278476

To upload the audience CSV file

  1. Go to Integration > Audiences.
    The Audiences window opens.

  2. Click Add Audience.
    The Audience window opens. The Build tab is displayed.

  3. Enter a unique Audience Name.

  4. Select the audience platform: Android or iOS.

  5. Select Import Audience.
  6. If it's a new audience:
    • Enter an Audience Name.
    • Click Save.
  7. Click CSV Upload.
  8. Choose what to do with the imported audience:
    • Add new devices: adds the list of device ids to the existing audience
    • Overwrite all existing devices: replace the entire audience with the uploaded list
    • Exclude from existing device list: remove devices in the upload list from the audience.
  9. Chose the CSV file to upload.
  10. Click Upload
    Wait for the confirmation message Uploaded successfully.
  11. Click Save Audience and Proceed.
  12. .Select a partner to select to.
  13. If necessary, follow the instructions connect to partners
  14. Click Close.
    The list is not immediately available. Lists are processed with a data freshness of Daily

Upload confirmation messages 

Message Cause What to Do
Uploaded successfully  The data will be available with a data freshness of daily  
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
  • The CSV should contain one column and one device ID per row. The CSV should contain no headers.
  • Make sure that all device IDs are in the correct GUID format
  • If you used Excel, save the file as a CSV file as shown here. 
  • CSV.jpg

See table above for the correct formats

We just had a temporary connection problem and couldn’t upload your file. You can try again now Possible network error Try to upload the CSV file again

Import an audience using the API

The import audience API is used to either add or remove devices from an audience. The API has the structure shown in the example. Use the procedure that follows to generate the API request URL and the API requirest body.

API request URL

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

The account-specific API token

Yes

API request body

{
"import_key": "{mport_key}",
"platform": "{plaform}",
"devices": [
"{device}",
"{device2}",
"{devicen}"
]
}
Parameter Description Mandatory
{import_key} Unique key that identifies the audience. Note: Use the same import_key for both the add and remove endpoints.   Yes
{platform}

Android or ios

Yes
{device}
  • Unique device IDs
  • The maximum number of devices in one call 10,000.
Yes

 Before you begin:

  • Ensure that you have created the audience in AppsFlyer.

To prepare an API request URL:

  1. Go to Integration > Audiences.
    The Audiences window opens.

  2. Click Add Audience.
    The Audience window opens. The Build tab is displayed.

  3. Enter a unique Audience Name.

  4. Select the audience platform: Android or iOS.

  5. Select Import Audience.
  6. Click API.
  7. Select API Action
    • Add Devices: add additional device advertising IDs to an existing audience. 
    • Remove Devices: Remove a list of device advertising IDs from an existing audience.
      Note: Choosing an API Action changes the endpoint path referenced. It doesn't persist after you save the audience. When you want to add or remove devices from an audience, you can specify the action using the necessary path. 
  8. Copy the API Request URLthe API token is already included in the URL.
  9. Copy the API Request Body.
  10. Click Save Audience and Proceed.
  11. (optional) Connect your audience to partners.
  12. Prepare the API inclduing the devices ids and post the API to Appsflyer as shown in the example above. 

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": [
      "a23416b8-a21a-4051-a62f-5d3cb85e16ed",
      "09a14a6b-cce8-44f3-8f77-62eff8b5aa4f",
      "289da41f-0473-4977-89ae-8fc92234a921"
     ]
}
Code Message Description

200

The request was successful Audience successfully imported
400 Seems like your device list is empty. Add some device IDs to it and try again

The request body contains an empty list of devices.

You must provide at least 1 device ID per request.

400 Cannot process more than 10,000 devices per request (x devices counted in this request) The request body contains a list of more than 10,000 device IDs
400 We couldn’t understand one or more of your device IDs Some device IDs are not valid IDFA / GAID
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
403 Forbidden Incorrect or missing import key
500 Could not parse request

Invalid request body format.

See the request sample above.

API limitations

  • You can only add devices to one audience per request
  • You can only remove devices from one audience per request
  • Batch requests (multiple audiences) are not supported
  • You can send up to 10,000 device IDs per request
Was this article helpful?