Audiences—Additional Identifiers API

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.

API overview

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.

Methods

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>",
  "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:

  • idfa
  • gaid
  • idfv
  • customer_user_id
  • imei
  • oaid
Yes
{key_value}

Valid identifier value for the key_type specified

Yes

{identifiers}

Object containing the names and values of the identifiers to add:

  • {hashed_emails}
  • {phone_number_sha256}
  • {phone_number_e164_sha256}

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:

  • Lowercase
  • No white spaces
  • SHA256 hashed

Example value before hashing: name@domain.com

No

{phone_number_sha256}

Phone number (see note below)

Format:

  • No symbols, letters, or leading zeroes
  • Include country code
  • SHA256 hashed

Example value before hashing:

442070313000

No

{phone_number_e164_sha256}

Phone number in E164 format (see note below)

Format

  • E164 phone number
  • SHA256 hashed

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",
  "data": [
    {
      "key_value": "CDDA802e-AAAA-BBBB-CCCC-DDDDDDDDDDDD",
      "identifiers": {
        "hashed_emails": [
          "34d31be18022626de6b311d6a76e791176d2691b6eef406f524d8f56364c187a",
          "d8c2aec999baad2464e521873ee4465caaf7ff6db8c8b4a25b09ca07694e4dee"
        ],
        "phone_number_sha256": "6c91c4c640f6ef0162833260db4f13dec0df2b683092f4dba7e874bef1acea37",
        "phone_number_e164_sha256": "f3d7e96c73fb0de1b66acfce541d7af758fbd4f3fa3af0ea4e10110000d3625e"
      }
    }
  ]
}

Remove identifiers (DELETE)

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>",
  "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:

  • idfa
  • gaid
  • idfv
  • customer_user_id
  • imei
  • oaid
Yes
{key_value}

Valid identifier value for the key_type specified

Yes

{identifiers}

An array containing the names of the identifiers for which values should be deleted:

  • {hashed_emails}
  • {phone_number_sha256}
  • {phone_number_e164_sha256}

Yes


* Must include at least 1 of these 3 identifiers

Restrictions

The {data} object can include a maximum of 4,000 rows (key_values) per request.

Sample request to remove identifiers

HTTP DELETE
body:
{
  "key_type": "gaid",
  "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:

  • idfa
  • gaid
  • idfv
  • customer_user_id
  • imei
  • oaid

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:

  • The {app-id} as specified in the API request URL is correct.
  • The HTTP header contains is the correct AppsFlyer V2.0 API token. Your account admin can obtain this token from the AppsFlyer dashboard.

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