ENGAudience API Overview
1. Overview
The Tapjoy Audience API is a REST API for creating and retrieving information about audiences that can be used for app suppression on 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.
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).
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 for app suppression.
The values available for list_type: ['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.
Endpoint
https://api.tapjoy.com/v4/audiences
B. Example Requests
POST /v4/audiences
Host: api.tapjoy.com
Authorization: Bearer <token_string>
Accept: application/json; */*
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 "https://api.tapjoy.com/v4/audiences?account_id=497670f6-a152-4bdd-a717-dbe7f7635dc7&app_id=6881899b-9c55-4d83-9afc-552f880289d4&description=LIST-DESCRIPTION&list_type=app_suppression&name=LIST-NAME&offer_id="
3. FAQ
How often can a client upload an audience for app suppression?
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.
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.
Which MMPs are integrated with the audience API automatically?
Appsflyer.