Audience Targeting API

  • Updated

This API is deprecated. Please contact your account manager if you have questions.

Version 3.0 / March 2015

Use the Audience API to create a set of users who can later be targeted with a campaign. Create audiences by using Apple’s IDFA or Android’s advertising ID. To use this API, make HTTP requests to this URL:

https://api.applovin.com/audiences/command

The following table summarizes each command in this API:

create creates a new audience
list lists the current audiences
update updates the audience list with a new group of users
(This replaces the existing user list for a given audience.)
append adds new users to an existing audience
delete deletes a given audience

Authentication

All Audience Targeting APIs require that you add an API key to the request as a query parameter request (api_key):

https://api.applovin.com/audiences/command?api_key=API_KEY

You can find this Management Key (formerly called the “Custom Audience Key”) in the Keys tab of your account page. If the Management Key is not visible there, email AppLovin support at adsupport@applovin.com and one will be generated for you.

Errors

This API indicates errors with HTTP status codes:

HTTP Response Code Description
200 Success.
400 The request was not formatted properly, was missing data, or had invalid data.
403 Authentication failed. Check the validity of the API Key.
404 The audience ID you specified does not exist.
406 For create, an active audience with the same parameters exists already.
500 Service Unavailable.

create

The first step when you submit a custom audience is for you to create an empty audience. To create a new audience, make an HTTP request to:

https://api.applovin.com/audiences/create?api_key=API_KEY

The create API accepts the following fields, passed as URL-encoded query parameters:

Name Type Description Required
name String Name of the audience yes
(Must be alphanumeric, _-+, or URL-encoded space)
package_name String Package name or bundle ID of the source app. yes, if audience_type=retargeting
platform Enum (android, ios) Platform of the source app. Must be “android” or “ios”. yes
description String Description of the audience. no
audience_type Enum (ua, retargeting) Type of audience. Defaults to retargeting. yes, if audience_type=ua

Response:

The response is JSON-formatted:

Name Type Description
audience_id String ID of the audience

Example Request:

curl "https://api.applovin.com/audiences/create?name=My%20Audience%20Name&package_name=my.app.bundleId&platform=ios&api_key=API_KEY"

Example Response:

{"audience_id" : "fce0b41a0849706bd0fbbe181e61f419"}

list

To get a list of all the current audiences for a given user, make an HTTP request to the list endpoint.

https://api.applovin.com/audiences/list?api_key=API_KEY

Response:

The response is JSON-formatted:

Name Type Description
code int 200 for success
audiences List of Objects a list of objects containing information about an audience
audience_id String ID of the audience
name String name of the audience
package_name String iTunes ID or package name of the source app
platform Enum (android, ios) platform of the source app (must be “android” or “ios”)
description String description of the audience
user_count Long number of users who are part of the audience
count Long number of audiences the user has

Example Request:

curl "https://api.applovin.com/audiences/list?api_key=API_KEY"

Example Response:

{
  "code": 200,
  "audiences": [
    {
      "audience_id": "dab2d1297d35592597b0eee016e92baa",
      "name": "Custom Audience Test",
      "package_name": "Some package name",
      "platform": "ios",
      "description": "Test Custom Audience",
      "user_count": "10"
    }
  ],
  "count": 1
}

update

To upload a list of users to a given audience, use the update API. If the audience already has an existing user list, this replaces that list with the list of users in the update API request.

To update an audience with a new user list make an HTTP POST request to:

https://api.applovin.com/audiences/update?api_key=API_KEY&audience_id=AUDIENCE_ID&ttl_seconds=TTL_SECONDS

Query Parameters:

Name Type Description Required
audience_id Long ID of the audience returned from the create API yes
ttl_seconds Long seconds the users have to live (seconds until they expire); default is 365 days no

Post Body:

The update API accepts a newline-separated list of IDs in a POST request:

Name Type Description Required
List of advertising ids List of Strings A newline-separated list of Apple’s IDFA or Android’s advertising ID. The IDs must be in UUID format. yes

Response:

The response is JSON-formatted:

Name Type Description
audience_id Long ID of the audience
num_valid_ids Integer number of valid advertising IDs in the new audience list
num_invalid_ids Integer number of invalid advertising IDs in this request

Example Request:

curl -X POST --data-binary @userIds.txt "https://api.applovin.com/audiences/update?audience_id=AUDIENCE_ID&ttl_seconds=2592000&api_key=API_KEY"

Where the contents of the file userIds.txt is:

c77bbe4e-6a28-11e4-bcda-14109fdf9591
f601faf5-4a83-44d6-98ef-b67c24919d39

Example Response:

{ "audience_id" :“dab2d1297d35592597b0eee016e92baa”, "num_valid_ids" : 2, "num_invalid_ids" : 0 }

append

To add users to an existing audience, use the append API. If the audience already has an existing user list, this appends the users to the list.

To append users to an audience with a new user list make an HTTP POST request to:

https://api.applovin.com/audiences/append?api_key=API_KEY&audience_id=AUDIENCE_ID&ttl_seconds=TTL_SECONDS

Query Parameterss:

Name Type Description Required
audience_id Long ID of the audience returned from the create API yes
ttl_seconds Long seconds the users have to live (seconds until they expire); default is 365 days no

Post Body:

The update API accepts a newline-separated list of IDs in a POST request:

Name Type Description Required
List of advertising IDs List of Strings a newline-separated list of Apple’s IDFA or Android’s advertising ID; the IDs must be in UUID format yes

Response:

The response is JSON-formatted:

Name Type Description
audience_id Long ID of the audience
num_valid_ids Integer number of valid advertising IDs in the new audience list
num_invalid_ids Integer number of invalid advertising IDs in this request

Example Request:

curl -X POST --data-binary @userIds.txt "https://api.applovin.com/audiences/append?audience_id=AUDIENCE_ID&ttl_seconds=2592000&api_key=API_KEY"

Where the contents of the file userIds.txt is:

c77bbe4e-6a28-11e4-bcda-14109fdf9591
f601faf5-4a83-44d6-98ef-b67c24919d39

Example Response:

{ "audience_id" : “dab2d1297d35592597b0eee016e92baa”, "num_valid_ids" : 2, "num_invalid_users" : 0 }

delete

To delete an audience make an HTTP request to:

https://api.applovin.com/audiences/delete?api_key=API_KEY&audience_id=AUDIENCE_ID

where AUDIENCE_ID is the ID returned from the create erndpoint.

Response:

There is no response body for the delete API. On success it returns HTTP Response code 200.

Example Request:

curl "https://api.applovin.com/audiences/delete?audience_id=AUDIENCE_ID&api_key=API_KEY"

Tips

Deleting users from an audience without updating the full audience
You cannot remove individual users from an audience, but you can limit their eligibility to 0 seconds, which effectively removes them. To do this, make an append call with ttl_seconds=0.
API Timeouts
Requests time out after about 100 seconds. Depending on your connection speed and conditions on AppLovin’s end, this requires that you batch uploads into chunks of ~100k users. AppLovin recommends that you build batch-retry logic into scripts that interact with this API.
Targeting a Campaign to an Audience
After you create an audience and associate IDs with it, it appears as an option in the Custom Audience section of the Edit Targets page for all eligible campaigns. An audience is eligible for a campaign if they share the same package name and platform, if the campaign type and audience type are retargeting; and if they share the same platform, if the campaign type and audience type are user acquisition.

Example Postman Collection: