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:
-
Go to Integration > Audiences.
The Audiences window opens. -
Click Add Audience.
The Audience window opens. The Build tab is displayed. -
Enter a unique Audience Name.
-
Select the audience platform: Android or iOS.
- Select Import Audience.
- If it's a new audience:
- Enter an Audience Name.
- Click Save.
- Click CSV Upload.
- 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.
- Choose the CSV file to upload.
- Click Upload.
Wait for the confirmation message Uploaded successfully. - Click Save Audience and Proceed.
- Select a partner to connect to.
- If necessary, follow the instructions connect to partners.
- 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 | ||
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 |
|
|
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 |
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} |
|
Yes |
{api_token} |
The Import Audience 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} |
|
Yes |
Before you begin:
- Ensure that you have created the audience in AppsFlyer.
To prepare an API request URL:
-
Go to Integration > Audiences.
The Audiences window opens. -
Click Add Audience.
The Audience window opens. The Build tab is displayed. -
Enter a unique Audience Name.
-
Select the audience platform: Android or iOS.
- Select Import Audience.
- Click API.
- 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.
- Copy the API Request URL: the API token is already included in the URL.
- Copy the API Request Body.
- Click Save Audience and Proceed.
- (optional) Connect your audience to partners.
- 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