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 remarketing
To target users who have a birthday with promotional offers.
You can do the following:
- Use your other system to generate a list of users with birthdays. Export this list as a list of advertising IDs
- Upload the list to AppsFlyer and send it to the audience partner of choice
- 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.
Example CSV file: 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.
- Chose the CSV file to upload.
- Click Upload.
Wait for the confirmation message Uploaded successfully. - Click Save Audience and Proceed.
- .Select a partner to select 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
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 |
|
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} |
|
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} |
|
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 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 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