Audience Targeting API

This API is no longer available. 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:

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, please open a ticket here and request one be generated for you.

Errors

This API indicates errors with HTTP status codes:

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 JSON-formatted:

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:

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:

Post Body:

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

Response:

The response is JSON-formatted:

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:

Post Body:

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

Response:

The response is JSON-formatted:

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:

• AppLovin Audiences.postman_collection.json6 KB