Version 3.0 / March 2015

Use the Audience APIs 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:

Authentication

All Audience Targeting APIs require that you add an API key as a query parameter in the 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 uses HTTP status codes to indicate errors:

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:

Response:

The response is a JSON-formatted response:

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 API.

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

Response:

The response is a JSON-formatted response:

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 Params:

Post Body:

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

Response:

The response is a JSON-formatted response:

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 Params:

Post Body:

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

Response:

The response is a JSON-formatted response:

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 API.

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

There is no way to remove individual users from an audience, but you can limit their eligibility down to 0 seconds, which effectively removes them. To do this, make an append call with ttl_seconds=0.

API Timeouts

Requests timeout after about 100 seconds. Depending on your connection speed and conditions on our end, this will require that you batch uploads into chunks of ~100k users. We recommend building batch-retry logic into scripts that interact with this API.

Targeting a Campaign to an Audience

Once you create an audience and associate IDs with it, it will appear 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: