Campaign API
The Campaign API enables you to get your campaign information and manage your ironSource Ads campaigns:
With the Campaign API, you can:
- Create new campaigns
- Get the creation status during the creation process
- Update existing campaigns with all basic campaign configurations, including basic campaign targeting capabilities
- Activate or deactivate existing campaigns
Authentication Type: Bearer API Authentication
Get campaigns
Use this API to retrieve a list of your campaigns with their configuration data.
Method: GET
Request Example URL: https://api.ironsrc.com/advertisers/v4/campaigns
Required Parameters: None
Parameters:
Name | Required | Type | Allowed values | Default value | Description |
fields | No | Comma separated string fields | name, id, timeline, deliveryStatus, isActive, isArchived, titleId, budget, optimizationType, bidType, campaignType, attribution, frequencyCapping, creationDate | name, id, creationDate, titleId, budget, timeline, isActive, isArchived | A list of campaign fields to retrieve (id, name, isActive, isArchived will be always added to the response). |
ids | No | Comma separated campaign ids | – | – | Filter campaigns by a list if campaign ids |
titleIds | No | Comma separated title ids | – | – | Filter campaigns by a list if title ids |
isPendingCreation | No | Boolean | true, false | Filter pending creation campaigns | |
isActive | No | Boolean | true, false | Filter active or inactive campaigns | |
isArchived | No | Boolean | true, false | Filter archived or non archived campaigns | |
order | No | String | name, creationDate, dailyBudget, totalBudget, startDate, endDate | CreationDate | Order campaigns results, if no order and direction supplied, default sort is by creationDate desc. |
direction | No | String | asc, desc | asc | |
requestId | No | String | – | – | Used for paginated requests. |
pageNumber | No | Number | Any positive integer | 1 | Used for paginated requests. |
resultsBulkSize | No | Number | 1-500 (positive integer) | 100 | Used for paginated requests. |
Response example:
{
"campaigns": [
{
"name": " test daily limit",
"id": 1234567,
"titleId": 602904,
"timeline": {
"startDate": "2021-05-30",
"endDate": null
},
"attribution": {
"clickUrl": "https://app.appsflyer.com/abc123?campaign={CampaignName}_{CampaignId}&adgroup={ApplicationId}_{SubID}&creative={SubID}&ironsource_click_id={DynamicParameter}&idfa={DeviceId}&impression_id={REQ_ID}.{OPP_ID}",
"impressionUrl": "https://app.appsflyer.com/abc123?campaign={CampaignName}_{CampaignId}&adgroup={ApplicationId}_{SubID}&creative={SubID}&ironsource_click_id={DynamicParameter}&idfa={DeviceId}&impression_id={REQ_ID}.{OPP_ID}",
"type": "MMP",
"isSkanReporting": true,
}
"creationDate": "2021-05-30",
"frequencyCapping": {
"minHoursBetweenCompletions": null,
"dailyCompletionsLimit": 10,
"totalCompletionsLimit": 100
},
"budget": {
"type": "shared",
"total": "unlimited",
"daily": "unlimited"
}
"bidType": "CPM",
"campaignType": "userAcquisition",
"deliveryStatus": "pendingApproval",
"optimizationType": null,
"isActive": true,
"isArchived": false
}
]
"requestId": "MjczNjc5LjExNzY1NTUuMzAwMC4w";
"totalResultsCount": 20
}
Get creation state
Use this API to retrieve the creation state of a campaign and Identify what is needed for it to be activated.
Method: GET
Request Example URL: https://api.ironsrc.com/advertisers/v4/campaigns/creationState/:campaignId
Required Parameters: campaignId
Parameters:
Name | Required | Data type | Description |
campaignId | Yes | Number | The Campaign ID to get the creation state for |
Example response:
{
"hasBid": true,
"hasCreatives": true,
"hasCountries": true,
"hasSlotsLeft"?: true (only for skanReady campaigns)
}
Update activation status
Use this API to update the activation status of Active / Inactive / Pending creation campaigns.
Method: PUT
Request Example URL: https://api.ironsrc.com/advertisers/v4/campaigns/status/:campaignId/:isActive
Required Parameters: campaignId
URL Parameters:
Name | Required | Data type | Description |
campaignId | Yes | Number | Campaign ID we would like to change its activation status |
isActive | Yes | Boolean | Possible values:
|
Example Response:
{
"success": true
}
Create campaign
Use this API to create a new campaign.
Method: POST
Request Example URL: https://api.ironsrc.com/advertisers/v4/campaign
Required Parameters: None
Body Parameters:
Name | Required | Data type | Description |
campaignType | Yes | String |
Supported types of campaigns: userAcquisition |
bidType | Yes | String |
Campaign bid type available: CPI, CPM, tCPI |
titleId | Yes | Integer | Title ID of the created campaign |
name | Yes | String | The name of the campaign |
timeline | Yes | Object <{startDate, endDate}> |
Campaign scheduling See Timeline properties table below |
attribution | Yes | Object <{clickUrl, impressionUrl, type}> |
Campaign measurement URLs and SKAN settings See Attribution properties table below |
budget | Yes | Object <{type, daily, total}> |
Set campaign budget type and value See Budget properties table below |
frequencyCapping | Yes, if bid type is of type CPM | Object <{totalCompletionsLimit, dailyCompletionsLimit, minHoursBetweenCompletions}> |
Set the maximum number of clicks/views per user, can be used if the campaign bid type is of type CPM. See Frequency Capping properties table below |
Timelines properties:
Name | Required | Data type | Description |
startDate | Yes | Date | String | Date | today |
endDate | Yes | Date | Date | null |
Attribution properties:
Name | Required | Data type | Description |
clickUrl | Yes | String | |
impressionUrl | Yes | String | |
type | Only when creating (posting) IOS campaigns | String | Possible values:
|
Budget properties:
Name | Required | Data type | Description |
type | Yes | String | Possible values:
|
daily | Yes, if budget type is shared | Integer | String |
Campaign daily budget: Range 50-2000000 | unlimited |
total | Yes | Integer | String |
Campaign total budget: Range 100-2000000 | unlimited |
Frequency Capping properties:
Name | Required | Data type | Description |
totalCompletionsLimit | Yes | Integer | Range 0-999 |
dailyCompletionsLimit | Yes | Integer | Range 0-999 |
minHoursBetweenCompletions | Yes | Integer | Range 0-72 |
Full request example:
{
"campaignType": "userAcquisition",
"bidType": "CPM",
"titleId": titleId,
"name": "New Campaign",
"timeline": {"startDate": "today", "endDate": null},
"attribution": {"clickUrl": clickUrl, "impressionUrl": impressionUrl},
"budget": {"type": "shared", "daily": 50, "total": "unlimited"},
"frequencyCapping": {"totalCompletionsLimit": 10, "dailyCompletionsLimit": 100, "minHoursBetweenCompletions": 4}
}
Response example:
{
"id": 382491
}
Update campaign
Use this API to update a specific campaign configuration
Method: PUT
Request Example URL: https://api.ironsrc.com/advertisers/v4/campaigns/:id
Required Parameters: id
URL/Body Parameters:
Name | Required | Data type | Description |
id | Yes | Integer | Campaign ID of the updated campaign |
name | No | String | The name of the campaign |
timeline | No | Object <{startDate, endDate}> |
Campaign scheduling See Timeline properties table |
attribution | No | Object <{clickUrl, impressionUrl}> |
Campaign measurement URLs and SKAN settings See Attribution properties table |
budget | No | Object <{type, daily, total}> |
Set campaign budget type and value See Budget properties table |
frequencyCapping | No | Object <{totalCompletionsLimit, dailyCompletionsLimit, minHoursBetweenCompletions}> |
Set the maximum amount of clicks/views per user See Frequency Capping properties table |
Full request example:
{
"name": "Updated Campaign",
"timeline": {"startDate": "2023-11-09", "endDate": "2024-11-09"},
"attribution": {"clickUrl": clickUrl, "impressionUrl": impressionUrl},
"budget": {"type": "byCountry", "total": 200},
}
Response example:
{
"success": true
}
Basic Campaign targeting
Targeting setup API allows you to manage your campaign targeting (target titles, OS versions, Ad units, Device types)
Get campaign targeting
Use this API to retrieve the current targeting configuration for your campaign
Authentication Type: Bearer
Method: GET
Request Example URL: https://api.ironsrc.com/advertisers/v4/targeting/campaign/:campaignId
Required Parameters: campaignId
Response example:
{
"data": {
"osVersions": {
"list": [
"6.1",
"9.1",
"10.0",
"10.1",
"11",
"11.1"
],
"useLatest": false
},
"deviceTypes": [
"phone"
],
"adFormats": [
"interstitial"
],
"targetTitles": "exclude_my_titles"
}
}
Update campaign targeting
Use this API to update basic campaign targeting configurations.
Method: PUT
Request Example URL: https://api.ironsrc.com/advertisers/v4/targeting/campaign/:campaignId
Required Parameters: campaignId
Body Parameters:
Name | Required | Data type | Default value | Description |
targetTitles | No | String | allTitles | Chose the titles you would like the campaign to target: allTitles, excludeMyTitles, crossPromo (only for permitted advertisers) |
osVersions | No | Object | All | Choose a range, list of OS versions (See OS Versions property table below) |
deviceTypes | No | Array<String> | [“phone”, “tablet”] | Choose Device type: phone, tablet |
adFormats | No | Array<String> | [“interstitial”, “rewardedVideo”] | Choose Ad units: Interstitial, rewardedVideoFormally called “Ad units” (adUnits) |
OS Versions properties:
Name | Required | Data type | Description |
range | No | Object | Possible values: min, max (See OS ranges property table below) |
list | No | “all” | Array<String> | Use “all” for all os versions, otherwise array of required os versions, for example: [“10”, “10.1”, “11”] |
OS ranges properties:
Name | Required | Data type | Description |
max | Yes | String | Use any supported OS version or “latest” |
min | No | String |
Use any supported OS version Default value: minimum OS version for the campaign platform |
Request body example:
{
"targetTitles": "excludeMyTitles",
"deviceTypes": ["phone"],
"adFormats": ["interstitial"],
"osVersions": {
"range": {
"min": "10.1",
"max": "latest"
}
}
}