Campaign Management API
The Campaign Management API is for advertisers who use AppLovin’s AppDiscovery to promote their apps. Advertisers (and users who have advertising access to their company’s account) can create an OAuth application that authenticates access to these APIs. Advertisers can also create third-party OAuth applications that help to manage campaigns across many advertising clients.
Third-Party App Authorization Flow
This section is for companies who use the Campaign Management API on behalf of other companies who use third-party apps. If you manage your own company’s campaigns, use a first-party OAuth app instead, and skip to the API Request Authentication section.
AppLovin supports the standard OAuth web application flow. All query parameters are required. Send users to this URL to prompt them to authorize your app to manage their campaigns:
Third-Party App Authorization Flow Target URL
Table of Third-Party App Authorization Request Query Parameters
Name | Description | Example |
---|---|---|
client_id | Client ID of your OAuth App | 34af7c430e24bbccbc647ca3dd5ac858 |
redirect_uri | Where to redirect the user after flow completion. This must be URL-encoded. It must match the redirect_uri defined in the OAuth creation process. | https%3A%2F%2Fmydomain.com%2Foauth_code |
response_type | Set this to code . | code |
scope | The scope(s) this app should use. Must be a subset of the scopes defined in the app. URL-encode this value. Supported scopes:
| campaigns%3Awrite%20creatives%3Awrite |
state | An opaque value used by the client to maintain state between the request and callback | ab13221308fe6abad1d1 |
Third-Party App Authorization Flow Sample Request
After the user consents to using your OAuth app, Applovin sends a callback to your redirect_uri
.
That callback contains the user’s authentication code.
Table of Third-Party App Authorization Response Query Parameters
Name | Description | Example |
---|---|---|
code | The code value used to generate access and refresh tokens on behalf of the user. See the section on API Request Authentication | 9aa19842db327e4e43cc426e6ad6c2d1eacd2e3d464 |
state | The state that was passed to AppLovin’s initialization request, echoed back | ab13221308fe6abad1d1 |
Third-Party App Authorization Flow Sample Response
API Request Authentication
Issue a POST
request to this endpoint to generate a session token based on your Client ID and Client Secrets.
The session token lasts for 60 minutes (for first-party OAuth applications).
Put the access token you retrieve from this endpoint in the accessToken.access_token
field in the response on all other requests.
Do this via the header Authorization: Bearer access_token
.
Authentication Target URL
Authentication Content Type
Table of Access Token Form Fields
Name | Description | Example |
---|---|---|
client_id | Client ID of your OAuth App | 34af7c430e24bbccbc647ca3dd5ac858 |
client_secret | Client Secret of your OAuth App | 9538e854765525d0b34af7c430e24bbcdfd58b83f3836fd0e83cbfd1b |
code | The code value from the Authorization callback to an external company’s redirect_url . Required for grant_type=authorization_code , otherwise invalid. | 9aa19842db327e4e43cc426e6ad6c2d1eacd2e3d464 |
grant_type | Type of grant. For first party apps, set this to client_credentials . For third-party apps authenticating with the authentication code, set this to authorization_code . For third-party apps authenticating with a refresh token, set this to refresh_token . | client_credentials |
redirect_uri | The redirect URI for third-party applications. Invalid on first-party applications. | https://mydomain.com/oauth_code |
refresh_token | The user’s refresh token to generate a new access token and refresh token. Each refresh token can be used only once. But a new refresh token is returned with each call. Refresh tokens expire in 30 days. Required for grant_type=refresh_token , otherwise invalid. | c75742c98f382264fca6a0a5759354b6eb95ea1a7c44d0e0b22e36ff26f8 |
scope | The scope(s) that this session token should use. Must be a subset of the scopes defined in the app. Write scopes automatically have read permission. Separate multiple scopes with spaces. Supported scopes:
grant_type=client_credentials , optional for grant_type=refresh_token , invalid for grant_type=authorization_code | campaigns:write creatives:write |
/campaign/campaign_id
Issue a GET
request to this endpoint to view an individual campaign’s details.
Issue a POST
request to this endpoint to edit an individual campaign’s details, or to create a new campaign.
When you create a new campaign, don’t fill in the campaign_id in the request URL nor in the request body.
/campaign/campaign_id
Target URL
/campaign/campaign_id
Sample Response Body
/campaign/campaign_id
Sample Request Body
Table of /campaign/campaign_id
Request/Response Body Fields
Name | Description | Required on Creation | Required on Update | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
bid_type * | Bid Type of the campaign (CPI , CPP_GOAL , RET , CPE , ROAS_AD_BASED , or ROAS_IAP ) Example: | FALSE | TRUE | ||||||||||||||
bundle_id * | The Bundle ID of the promoted app (iOS only) Example: | FALSE | TRUE | ||||||||||||||
campaign_id * | Unique Campaign Identifier Example: | TRUE | FALSE | ||||||||||||||
category | Category of the campaign Example: | FALSE | TRUE | ||||||||||||||
clicks * | Yesterday’s clicks Example: | FALSE | TRUE | ||||||||||||||
created * | The date that the campaign was created Example: | FALSE | TRUE | ||||||||||||||
goal_period * | Number of Days after install for goal to be measured. Possible values by bid_type are:
Example: 0 | FALSE | FALSE | ||||||||||||||
impressions * | Yesterday’s impressions Example: | FALSE | TRUE | ||||||||||||||
installs * | Yesterday’s installs Example: | FALSE | FALSE | ||||||||||||||
name | Campaign Name Example: | TRUE | FALSE | ||||||||||||||
package_name * | The Package Name of the promoted app. On iOS, use the numeric portion of the iTunes ID Example: | FALSE | TRUE | ||||||||||||||
platform * | Platform of the promoted app (ios or android ) Example: | FALSE | TRUE | ||||||||||||||
spend * | Yesterday’s spend Example: | FALSE | TRUE | ||||||||||||||
status | Whether the campaign is active or not Example: | FALSE | FALSE | ||||||||||||||
tracking_method | The campaign tracking method. See the table of tracking methods below. Example: | FALSE | TRUE |
* read-only
/campaigns
Issue a GET
request to this endpoint to view all campaigns.
You cannot make edits to campaigns with this endpoint.
/campaigns
Target URL
/campaigns
Sample Response Body
Table of /campaigns
Response Body Fields
See the table of request/response fields from /campaign/campaign_id
.
/creative_set/creative_set_id
Issue a POST
request to this endpoint to update a creative set’s name or to create a new creative set.
To create a new creative set, do not fill in the creative_set_id in the request URL nor in the request body.
A creative set is a collection of assets that can be combined together to generate many ads.
When you assemble a creative set, you do not need to upload each asset multiple times.
Creative sets also include information about the languages of the underlying assets.
/creative_set/creative_set_id
Target URL
/creative_set/creative_set_id
Sample Response Body
Table of /creative_set/creative_set_id
Request/Response Body Fields
Name | Description | Example |
---|---|---|
ads * | Array of ad objects associated with this creative set. These objects have the same format as the response body from the /ad/ad_id endpoint. | |
assets * | Array of asset objects associated with this creative set. See table below. | |
campaign_id * | Campaign ID | "29d66efc22ae53a201e1532265b83f12" |
countries | Countries that this creative set should be restricted to (for example, for country-specific promotions). You do not need to duplicate campaign targeting on each creative set. If this list is blank, the campaign-defined countries are eligible. If this list includes countries outside of what the campaign targets, those countries will not be eligible | ["za", "gb"] |
languages | List of languages. See the table below for a full list. | |
name | Creative set name | |
product_page | iOS Custom Product Page or Android Store Listing associated with the creative set |
* read-only
Table of Asset Object Fields
Name | Description | Example |
---|---|---|
asset | Asset URL, hash, or text string | "https://res1.applovin.com/oab49763/foobidyfoo_v23_phone.mp4" |
status | The Campaign Management API processes assets asynchronously. It begins by setting the status to processing . It finishes by setting the status to either error (for failure) or ready (for success). | "processing" , "error" , "ready" |
type | Asset type. See the table below for possible asset types. | "TXT_TITLE" |
/creative_sets/campaign_id
Issue a GET
request to this endpoint to view all creative sets associated with a campaign.
/creative_sets/campaign_id
Target URL
/creative_sets/campaign_id
Sample Response Body
Table of /creative_sets/campaign_id
Response Body Fields
See the table of response fields from /creative_set/creative_set_id
/creative_set_assets/creative_set_id
Issue a POST
request to this endpoint to upload, update, or remove an asset associated with a creative set.
Only one asset can be managed per request.
The response will include all assets in the creative set.
POST
/creative_set_assets/creative_set_id
Target URL
POST
/creative_set_assets/creative_set_id
Content Type
Table of Request Asset Form Fields
Name | Description | Example |
---|---|---|
asset † | Asset URL, hash, or text string. | "https://res1.applovin.com/ob7cb6fc/foobidyfoo_v23_phone.mp4" , "3f5a01dc0980f3d04188e73e91c" , "Best app you’ll ever play" |
file ‡ | Image, video, or HTML file. | See Ad rules, specifications, and guidelines |
remove * | (Optional) Pass in true to remove the asset type. | true or false |
type ‡ | Asset type. See the table below for possible asset types. | ”TXT_TITLE” |
update | (Optional) Pass in true to update the asset type. | true or false |
* When you remove an asset, you only need to pass the type
parameter.
† When you add or update an asset, you only need to pass either the asset
parameter or the file
parameter.
‡ When you pass in a file to add or update a file asset, type
is calculated from the file properties.
Sample POST
/creative_set_assets/creative_set_id
Response Body
Table of POST
/creative_set_assets/creative_set_id
Response Asset Object Fields
Name | Description | Example |
---|---|---|
asset | Asset URL, hash, or text string | "https://res1.applovin.com/oab49763/foobidyfoo_v23_phone.mp4" |
status | The Campaign Management API processes assets asynchronously. It begins by setting the status to processing . It finishes by setting the status to either error (failure) or ready (success). | "processing" , "error" , "ready" |
type | Asset type. See the table below for possible asset types. | "TXT_TITLE" |
/ad/ad_id
Issue a GET
request to this endpoint to view an ad’s properties.
Issue a POST
request to this endpoint to edit an ad’s name or status.
After you upload all required assets for an ad template (via the UI or via an API call to /creative_set/creative_set_id
), the ads are automatically created.
/ad/ad_id
Target URL
/ad/ad_id
Sample Response Body
Table of /ad/ad_id
Request/Response Body Fields
Name | Description |
---|---|
creative_set_id * | Parent creative set ID |
creative_set_name * | Parent creative set name |
id * | Ad ID |
name | Ad name |
size * | Ad size: one of BANNER , INTER , LEADER , MREC , NATIVE , or WIDGET |
status | Whether the ad is active (true ) or not (false ) |
template * | Ad template name |
* read-only
/ads/creative_set_id
Issue a GET
request to this endpoint to view all ads associated with a creative set.
/ads/creative_set_id
Target URL
/ads/creative_set_id
Sample Response Body
Table of Ad Object Fields
See the table of request/response fields from /ad/ad_id
.
/creative_sets/campaign_id
Issue a GET
request to this endpoint to view all creative sets associated with a campaign.
/creative_sets/campaign_id
Target URL
/creative_sets/campaign_id
Sample Response Body
Table of /creative_sets/campaign_id
Response Body Fields
See the table of request/response fields from /ad/ad_id
.
/campaign_targets/campaign_id
Issue a GET
request to this endpoint to view a campaign’s targeting, URLs, bids, and budgets.
Issue a POST
request to this endpoint to update those attributes.
/campaign_targets/campaign_id
Target URL
/campaign_targets/campaign_id
Sample Response Body
Table of /campaign_targets/campaign_id
Request/Response Body Fields
Name | Description | Example |
---|---|---|
bid_type * | Type of bid used in this campaign. Same as what is set on the campaign object. | CPI |
countries | List of Countries objects. See below. | See Table Below |
device_types | List of eligible device types. An empty list means all device types are eligible. Options are: "phone" , "tablet" , "other" . Only supported on iOS. | ["phone", "other"] |
os_major_version_min | Lowest OS version that the campaign is eligible to serve on. 10 means 10.0 and above. | 9 |
* read-only
Table of Fields for Countries Objects
A campaign either has a total budget shared by all countries, or each country needs a specific budget.
Therefore, the bid, budget, and URL values should either be in the DEFAULT
object or in each country-specific object.
A POST
request to this endpoint will only update countries that are included in the request.
Targeted countries that are not included in the request will not be updated.
To disable a country, set disabled
to true
.
Name | Description | Example |
---|---|---|
bid | The bid value of that country. On CPI campaigns, this is the CPI in USD. For RET , ROAS_AD_BASED , and ROAS_IAP , this is the percent goal (50 =50%). For CPP and CPE , this is the goal event value in USD. | 2.9 |
budget | Daily budget (USD) | 1000 |
click_url | Click tracking URL | https://s2s.adjust.com/impression/123abc?campaign={CAMPAIGN_NAME}%20({CAMPAIGN_ID})&gps_adid={IDFA} |
country | "DEFAULT" or two-letter country code | "gb" |
disabled | The API only returns active countries. To disable countries, set this value to true on update. | false |
impression_url | Impression tracking URL | https://app.adjust.com/123abc?campaign={CAMPAIGN_NAME}%20({CAMPAIGN_ID})&gps_adid={IDFA} |
/source_bids/campaign_id
Issue a GET
request to this endpoint to view all the override app source bids of a campaign.
Issue a GET
request to this endpoint with optional limit
and offset
query parameters to paginate through the override app source bids of a campaign.
Issue a POST
request to this endpoint to update or add more source bid overrides.
/source_bids/campaign_id
Target URLs
/source_bids/campaign_id
Sample Response Body
/source_bids/campaign_id?limit=2&offset=2000
Sample Response Body
Table of /source_bids/campaign_id
Request/Response Body Fields
Name | Description | Example |
---|---|---|
app_id * | The app that should receive an overridden bid | "da605e6f950f1aec838816df845e95e0c8d5cb7a994d71ae0ef2" |
app_id_external † | The External App ID (read-only) | "f950f1aec838816df845e95e0c8da605e6" |
bid_override_percentage ‡ | The percent over (or under) the bid that the campaign would use otherwise. "100" means twice the bid. "default" uses the campaign default or the bid_value . | 10 |
bid_value ‡ | The overridden bid value. "default" uses the campaign default or the bid_override_percentage . | 1.2345 |
country | Two-letter country code | "gb" |
* You can find this value in the Reporting API Column “external_placement_id
”, the tracking URL macro {PLACEMENT_ID}
, or via the UI tools for CSV bidding.
† You can find this value in the Reporting API Column “app_id_external
” or the tracking URL macro {APP_ID}
.
This value is ignored on POST
requests. It is included on the GET
request for backwards compatibility.
‡ At most one of these values can be other than "default"
.
Clear bid overrides by setting both bid_override_percentage
and bid_value
to "default"
.
Table of /source_bids/campaign_id?limit=xxxx&offset=yyyy
Response Body Fields
Name | Description | Example |
---|---|---|
limit | Number of rows to return in this response. Useful for pagination through large responses. | 5000 |
offset | Number of rows in the data set this response should skip. Useful for pagination through large responses. | 15000 |
source_bids | List of source bids. See Table of /source_bids/campaign_id Request/Response Body Fields for field definition. | |
total_row_count | Number of source bid overrides associated with this campaign. | 8192 |
/sources/campaign_id
Issue a GET
request to this endpoint to view the status of sources where a campaign is serving.
Issue a POST
request to this endpoint to update the status of sources across a campaign.
/sources/campaign_id
Target URLs
/sources/campaign_id
Sample Response Body
/sources/campaign_id?limit=2&offset=2000
Sample Response Body
Table of /sources/campaign_id
Request/Response Body Fields
Name | Description | Example |
---|---|---|
app_id * | The reference to the app that can be toggled | da605e6f950f1aec838816df845e95e0c8d5cb7a994d71ae0ef2 |
app_id_external † | The external app ID (read-only) | f950f1aec838816df845e95e0c8da605e6 |
status | Whether the app is active or not | true |
* You can find this value in the Reporting API Column “external_placement_id
”, the tracking URL macro {PLACEMENT_ID}
, or via the UI tools for CSV bidding.
† You can find this value in the Reporting API Column “app_id_external
” or the tracking URL macro {APP_ID}
.
This value is ignored on POST
Requests.
It is included on the GET
Request for backwards compatibility.
Table of /sources/campaign_id?limit=xxxx&offset=yyyy
Response Body Fields
Name | Description | Example |
---|---|---|
limit | Number of rows to return in this response. Useful for pagination through large responses. | 5000 |
offset | Number of rows in the data set this response should skip. Useful for pagination through large responses. | 15000 |
sources | List of sources. See Table of /sources/campaign_id Request/Response Body Fields for field definition. | |
total_row_count | Number of source bid overrides associated with this campaign. | 8192 |
Table of Tracking Methods
API Name | MMP Name |
---|---|
adjust | Adjust |
applovin | AppLovin |
appsflyer | AppsFlyer |
apsalar | Singular |
branch | Branch |
custom_track | Custom |
justtrack | JustTrack |
kochava | Kochava |
tenjin | Tenjin |
Language Codes
Language Code | Language |
---|---|
ar | Arabic |
bg | Bulgarian |
bn | Bengali |
bs | Bosnian |
ca | Catalan |
cs | Czech |
da | Danish |
de | German |
el | Greek |
en | English |
es | Spanish |
et | Estonian |
eu | Basque |
fa | Farsi |
fi | Finnish |
fr | French |
he | Hebrew |
hi | Hindi |
hr | Croatian |
hu | Hungarian |
id | Indonesian |
in | Indian |
is | Icelandic |
it | Italian |
he | Hebrew |
hi | Hindi |
iw | Hebrew |
ja | Japanese |
jv | Javanese |
ka | Georgian |
ko | Korean |
ld | Indonesian |
lt | Lithuanian |
lv | Latvian |
mk | Macedonian |
mr | Marathi |
ms | Malay |
nb | Norwegian |
nl | Dutch |
no | Norwegian |
pl | Polish |
pt | Portugese |
ro | Romanian |
ru | Russian |
sk | Slovak |
sq | Albanian |
sr | Serbian |
su | Sundanese |
sv | Swedish |
th | Thai |
tr | Turkish |
ug | Uighur |
uk | Ukrainian |
ur | Urdu |
vi | Vietnamese |
zh | Chinese (Simplified and Traditional) |
zh_hans | Chinese (Simplified) |
zh_hant | Chinese (Traditional) |
Asset Types
API Name | Asset Type Name | Description |
---|---|---|
HOSTED_HTML | Playable File | File of a playable ad |
IMG_BANNER | Banner Image | 320×50 |
IMG_ICON | App Icon | Should match the icon used in the store |
IMG_INTER_L | Landscape Image | Used in static interstitials and as endcards on videos |
IMG_INTER_P | Portrait Image | Used in static interstitials and as endcards on videos |
IMG_LEADER | Leader Image | 728×90 |
IMG_MREC | Medium Rectangle (MREC) Image | 300×250 |
IMG_NATIVE | Native Image | Main image of a native ad: 1200×628 or 1200×627 |
TXT_BUTTON | Button | Button text |
TXT_RATING | App Rating | 0.0–5.0, only increments of 0.5 are accepted |
TXT_SUBTITLE | Subline | Secondary text used in some ads to describe the app |
TXT_TITLE | App name | Used in banner ads and some video templates |
VID_LONG_L | Long Landscape Video | Landscape oriented video more than 15 seconds |
VID_LONG_P | Long Portrait Video | Portrait oriented video more than 15 seconds |
VID_SHORT_L | Short Landscape Video | Landscape oriented video less than 15 seconds |
VID_SHORT_P | Short Portrait Video | Portrait oriented video less than 15 seconds |
Templates
Size | Template Name | Assets |
---|---|---|
Banner | Standard | IMG_BANNER |
Interstitial | Landscape — Over 15s | IMG_INTER_P , IMG_INTER_L , VID_LONG_L |
Interstitial | Landscape — Under 15s | IMG_INTER_P , IMG_INTER_L , VID_SHORT_L |
Interstitial | Landscape Playable Endcard — Over 15s | HOSTED_HTML , VID_LONG_L |
Interstitial | Landscape Playable Endcard — Under 15s | HOSTED_HTML , VID_SHORT_L |
Interstitial | Portrait — Over 15s | IMG_INTER_P , IMG_INTER_L , VID_LONG_P |
Interstitial | Portrait — Under 15s | IMG_INTER_P , IMG_INTER_L , VID_SHORT_P |
Interstitial | Portrait Playable Endcard — Over 15s | HOSTED_HTML , VID_LONG_P |
Interstitial | Portrait Playable Endcard — Under 15s | HOSTED_HTML , VID_SHORT_P |
Interstitial | Rewarded Playable | HOSTED_HTML |
Interstitial | Standard | IMG_INTER_P , IMG_INTER_L |
Interstitial | Standard Playable | HOSTED_HTML |
Leader | Standard | IMG_LEADER |
MREC | Standard | IMG_MREC |
Preload | Standard | n/a |