Audience API Overview

1. Overview

The Tapjoy Audience API is a REST API for creating and retrieving information about audiences that can be used for retargeting and deny-listing. Additionally, it can be used for app suppression for a list of devices.

A. App Suppression

App Suppression means the provided devices should be marked as having the associated App ID already installed. This information comes from outside our normal network/SDK data about a device. For example, an advertiser uploads a list of devices that they know already have the app installed. Tapjoy will 'suppress' the app offers, so that we do not show offers for this app to the users.

B. Denylist

Denylisting means the provided devices should not be shown the associated offer. This is different from App Suppression because it does not tell us whether the device has the app installed or not. A device that is on a denylist for one offer, may be shown another offer for the same advertiser app.

C. Retargeting

Allows publishers to target offers to specific list of Device IDs for retargeting purposes.

2. Making Requests

To make a API request you must first request an access token via our OAuth API. Details on how to do this are here.

A. Required Parameters and Expected Values

account_id - the Advertiser account ID to authenticate said advertiser in our system.

name - Name of the Audience.

description - description of the Audience.

devices - a CSV file of device ids. Headers should not be included for this CSV. IDFA and GAID can be any case and include hyphens or not. They are normalized on the backend.

offer_id - the Tapjoy offer_id (or AdSet ID) the client either wants to associate for retargeting or deny-listing.

app_id - the Tapjoy app_id in question the Advertiser wants to suppress.

list_type - list type tells the Audience API whether the client API request is either for retargeting an audience, deny-listing an audience or app suppression.

The values available for list_type: ['retarget', 'denylist', 'app_suppression'].

The expected value for the list type parameter has to be 1 of the 3 options listed .

Note: The parameters listed - 7 in total - are required for an API request, however, not all values need to be listed for each parameter in order to return a successful response from the API.

Additional Note: Each request is made against the same API endpoint.


B. Example Requests

POST /v4/audiences 
Authorization: Bearer <token_string> 
Accept: application/json; */* 


account_id: '51a1d60a-0af4-449d-ac12-72f43846c146' 
name: 'foo' 
description: 'This is our foo audience for retargeting' 
devices: device_list.csv 
offer_id: 'bdc9b48c-3e7b-4347-9c56-161fd227e9c8' 
app_id: ' ' (blank for retargeting lists)
list_type: 'retarget' 


account_id: '5a4e87ac-119f-4181-91c7-fce4f8542cee' 
name: 'bar'
description: 'This is our foo audience for deny-list' 
devices: device_list_2.csv 
offer_id: 'a5e24cb9-de37-4755-bca8-66ad36c63f23'
app_id: ' ' (blank for deny lists)
list_type: 'denylist' 

App Suppression

account_id: '497670f6-a152-4bdd-a717-dbe7f7635dc7' 
name: ' ' 
description: ' ' 
devices: device_list_3.csv 
offer_id: ' ' (blank for suppression lists)
app_id: '6881899b-9c55-4d83-9afc-552f880289d4' 
list_type: 'app_suppression'
curl --header "Authorization: Bearer YOUR-TOKEN" --request POST --form devices=@/path/to/device_list.csv ""

3. FAQ

How often can a client upload an audience for retargeting, deny list, or suppression list?

As often as they want, (e.g., 1hr).

What is the max list of devices I can upload?

There is a soft upper limit of 1 million devics. Contact engineering if you want to process more.

If I upload two files (e.g., list_one.csv, list_two.csv) are they being replaced or merged?

App Suppression - every device in the csv will be marked as having the specified app installed. Sending two lists has the effect of merging them. Denylist - They are being replaced. Retargeting - They are being replaced.

Can I delete a list?

App Suppression - No, once a device is marked as having the app installed there is no way to tell Tapjoy the user has uninstalled the app. If a partner wants to be able to remove devices, they should use a denylist. Denylist - Upload an empty list. Retargeting - Upload an empty list.

Which MMPs are integrated with the audience API automatically?