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:
  • isActive = true
    Update campaign status to Active
  • isActive = false
    Update campaign status to Inactive

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:
  • MMP – campaign optimization will be based on MMP reported events
  • SKAN – campaign optimization will be based on SKAN reported events (permissions based)

Budget properties:

Name Required Data type Description
type Yes String Possible values:
  • shared – Set one daily budget for the entire campaign
  • byCountry – Set a daily budget for each country group separately.
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"
        }
    }
}