[Legacy] Audiences—import procedures (V1.0)

At a glance: Legacy (V1.0) audience import procedures, allowing you to import predefined audience segments from your internal systems (such as BI and CRM) to AppsFlyer Audiences. For maximum flexibility in importing audiences, we recommend using the updated Audience import feature V2.0.

Legacy (V1.0) import procedures

You can import audiences by either uploading CSV files or using the API.

Import 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.

Example CSV file: legacy_import_example_advertising_ID.csv

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. Choose 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 connect 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.
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
  • 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.
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
Upload confirmation messages

Use the Import Audience 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 request 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 Import Audience API token:

  • This token is included in the URL copied from the Audiences dashboard (see instructions below for importing or updating an audience using the API)
  • Note: This is not the same as your account's AppsFlyer API token (V1.0 or V2.0)
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 URL: the 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 including the device 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

To refresh the audience size counter, use Calculate now available in the Actions menu. 

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?