At a glance: Use the Audiences Additional Identifiers API to bulk upload user identifiers from your internal systems (such as BI and CRM) to AppsFlyer Audiences, enabling broader audience communication to relevant partners based on these identifiers.
About the API
The Audiences Additional Identifiers API can be used to add the following user identifiers from your internal systems to AppsFlyer Audiences:
- Up to 2 hashed email addresses
- Hashed telephone number
- Hashed E164 telephone number
You can then choose to send these identifiers to your Audiences partners (subject to your account-level user identifier policy), allowing them to more accurately identify your target audiences. Note that not all advertising partners support all identifiers.
When should I use this API?
This API was designed to be used when you want to upload a large volume of identifier data. Typically, this means data collected over time (for example, hashed emails collected from all users of an app over the last 12 months). For real-time, individual updates of identifiers from specific devices, configure additional identifiers in the AppsFlyer SDK or S2S-mobile API.
Important!
Encryption: All additional identifier values must be encrypted with SHA256 hashing. Unencrypted identifiers will not be processed.
Timing: To ensure accurate matching of identifiers, the Audiences Additional Identifiers API can be used as soon as the day following the reporting of key identifiers through the AppsFlyer SDK (UTC). For example, key identifiers reported on 3-January-2022 (UTC) can be updated through this API on 4-January-2022 (UTC) or later.
Actions
Authentication
The request must include an HTTP header containing your account's AppsFlyer V2.0 API token. Ask your account admin to obtain this token from the AppsFlyer dashboard.
API Specifications and sample code
Add/modify identifiers (PUT)
API request URL
https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}
| Parameter | Description | Mandatory |
|---|---|---|
| {app-id} |
App ID of the app from which the identifiers were collected (as it appears in the AppsFlyer dashboard) |
Yes |
API request body
{
"key_type": "<key_type>",
"action": "add",
"data": [
{
"key_value": "<key_value>",
"identifiers": {
"hashed_emails": [
"<hashed_email_value>",
"<hashed_email_value>"
],
"phone_number_sha256": "<phone_number_sha256_value>",
"phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
}
},
{
"key_value": "<key_value>",
"identifiers": {
"hashed_emails": [
"<hashed_email_value>",
"<hashed_email_value>"
],
"phone_number_sha256": "<phone_number_sha256_value>",
"phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
}
}
]
}| Parameter | Description | Mandatory |
|---|---|---|
| {key_type} |
The identifier used as the unique value to represent the user in each data row of the request. The value specified here applies to every row in the request. Possible values:
|
Yes |
| {action} |
add |
No Default value: add |
| {key_value} |
Valid identifier value for the key_type specified |
Yes |
|
{identifiers} |
Object containing the names and values of the identifiers to add:
|
Yes * Must include a value for at least 1 of these 3 identifiers |
|
{hashed_emails} |
An array of up to 2 hashed email addresses Format:
Example value before hashing: name@domain.com |
No |
|
{phone_number_sha256} |
Phone number (see note below) Format:
Example value before hashing: 442070313000 |
No |
| {phone_number_e164_sha256} |
Phone number in E164 format (see note below) Format
Example value before hashing: +442070313000 |
No |
Note
Different advertising partners support different phone number formats. So, if you choose to add a phone number, sending both identifiers is recommended: phone_number_sha256 and phone_number_e164_sha256.
Restrictions
The following restrictions apply to the Add/modify identifiers request:
- Previously existing values (if any) will be overwritten by values sent in the request.
- The {data} object can include a maximum of 4,000 rows (key_values) per request.
Sample request to add identifiers
HTTP PUT
body:
{
"key_type": "idfv",
"action": "add",
"data": [
{
"key_value": "CDDA802e-AAAA-BBBB-CCCC-DDDDDDDDDDDD",
"identifiers": {
"hashed_emails": [
"34d31be18022626de6b311d6a76e791176d2691b6eef406f524d8f56364c187a",
"d8c2aec999baad2464e521873ee4465caaf7ff6db8c8b4a25b09ca07694e4dee"
],
"phone_number_sha256": "6c91c4c640f6ef0162833260db4f13dec0df2b683092f4dba7e874bef1acea37",
"phone_number_e164_sha256": "f3d7e96c73fb0de1b66acfce541d7af758fbd4f3fa3af0ea4e10110000d3625e"
}
}
]
}Remove identifiers (PUT)
API request URL
https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}
| Parameter | Description | Mandatory |
|---|---|---|
| {app-id} |
App ID of the app from which the identifiers were collected (as it appears in the AppsFlyer dashboard) |
Yes |
API request body
{
"key_type": "<key_type>",
"action": "remove",
"data": [
{
"key_value": ",<key_value>",
"identifiers": [
"hashed_emails",
"phone_number_sha256",
"phone_number_e164_sha256"
]
},
{
"key_value": ",<key_value>",
"identifiers": [
"hashed_emails",
"phone_number_sha256",
"phone_number_e164_sha256"
]
}
]
}| Parameter | Description | Mandatory |
|---|---|---|
| {key_type} |
The identifier used as the unique value to represent the user in each data row of the request. The value specified here applies to every row in the request. Possible values:
|
Yes |
| {key_value} |
Valid identifier value for the key_type specified |
Yes |
| {action} |
remove |
No Default value: add |
|
{identifiers} |
An array containing the names of the identifiers for which values should be deleted:
|
Yes
|
Restrictions
The {data} object can include a maximum of 4,000 rows (key_values) per request.
Sample request to remove identifiers
HTTP PUT
body:
{
"key_type": "gaid",
"action": "remove",
"data": [
{
"key_value": "cdda802e-aaaa-bbbb-cccc-dddddddddddd",
"identifiers": [
"hashed_emails",
"phone_number_sha256",
"phone_number_e164_sha256"
]
}
]
}Responses
| Code | Message | Description |
|---|---|---|
|
202 |
Accepted for processing |
Request will be applied during the next processing window. |
|
400 |
Request body must have a valid key_type |
The following key_types are supported:
|
|
400 |
Request must have ‘data’ with at least 1 element |
Data list can not be empty. |
|
400 |
Request ‘data’ should not exceeds the size of 4000 in a single request |
Data list can include a maximum of 4,000 rows. |
|
400 |
Request data has too many invalid ‘data’ elements |
More than 10% of the data to modify is not valid according to the specification. |
|
404 |
AppsFlyer - Page Not Found |
Check that:
|
Response examples
{
"message": "Accepted for processing",
"received": 1000,"invalid": 2,
"trace-id": "698ed323-c787-45b5-b792-463c67c94064"
}
{
"error": "Request body must have a valid key_type",
"trace-id": "18a5f685-ea4d-4ca9-beab-a542a3786d12"
}
{
"error": "Request must have 'data' with at least 1 element",
"trace-id": "c155a7fa-b573-4efe-9bfb-5ae7de40e7fd"
}
{
"error": "Request 'data' should not exceeds the size of 4000 in a single request”,
"trace-id": "b325a7fa-b573-4efe-9bfb-5ae7de40e72c"
}
{
"error": "Request data has too many invalid 'data' elements",
"valid": 2,
"invalid": 30,
"trace-id": "33551c1d-5682-405e-a959-c8729ca74735"
}
Rate limitations
- 5 requests per second
- 350 requests per minute