Campaign API

Leverage the Campaign API to automate the creation, modification, and management of your ad campaigns.

Read time 13 minutes

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 
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/v_4/campaigns 

Required Parameters: None

Parameters:

NameRequiredTypeAllowed valuesDefault valueDescription
fields
NoComma separated string fieldsname, id, timeline, deliveryStatus, isActive, isArchived, titleId, budget, optimizationType, bidType, campaignType, attribution, frequencyCapping, creationDatename, id, creationDate, titleId, budget, timeline, isActive, isArchivedA list of campaign fields to retrieve (id, name, isActive, isArchived will be always added to the response).
ids
NoComma separated campaign ids- -Filter campaigns by a list if campaign ids
titleIds
NoComma separated title ids--Filter campaigns by a list if title ids
isPendingCreation
NoBooleantrue, false
Filter pending creation campaigns
`isActiveNoBooleantrue, false
Filter active or inactive campaigns
isArchived
NoBooleantrue, false
Filter archived or non archived campaigns
order
NoStringname, creationDate, dailyBudget, totalBudget, startDate, endDateCreationDateOrder campaigns results, if no order and direction supplied, default sort is by creationDate desc.
direction
NoStringasc, descasc
requestId
NoString-\Used for paginated requests.
pageNumber
NoNumberAny positive integer1Used for paginated requests.
resultsBulkSize
NoNumber1-500 (positive integer)100Used for paginated requests.

Response example
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
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: /advertisers/v4/campaigns/creationState/:campaignId

Required Parameters: campaignId

Parameters:

NameRequiredData typeDescription
campaignIdYesNumberThe Campaign ID to get the creation state for

Example response:
Example response:

{
 "hasBid": true,
 "hasCreatives": true,
 "hasCountries": true,
 "hasSlotsLeft"?: true (only for skanReady campaigns)
}

Update activation status
Update activation status

Use this API to update the activation status of Active / Inactive / Pending creation campaigns.

Method: PUT

Request Example URL: /advertisers/v4/campaigns/status/:campaignId/:isActive

Required Parameters: campaignId

URL Parameters:

NameRequiredData typeDescription
campaignId
YesNumberCampaign ID we would like to change its activation status
isActive
YesBooleanPossible values: - isActive = true Update campaign status to Active - isActive = false Update campaign status to Inactive

Example Response
Example Response

{
    "success": true
}

Create campaign
Create campaign

Use this API to create a new campaign.

Method: POST

Request Example URL: https://api.ironsrc.com/advertisers/v4/campaigns

Required Parameters: None

Body Parameters
Body Parameters

NameRequiredData typeDescription
campaignType
YesStringSupported types of campaigns: userAcquisition
bidType
YesStringCampaign bid type available: CPI, CPM, tCPI
titleId
YesIntegerTitle ID of the created campaign
name
YesStringThe 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
Timelines properties

NameRequiredData typeDescription
startDate
YesDate | StringDate | today
endDate
YesDateDate | null

Attribution properties
Attribution properties

NameRequiredData typeDescription
clickUrl
YesString
impressionUrl
YesString
type
Only when creating (posting) IOS campaignsStringPossible 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
Budget properties

NameRequiredData typeDescription
type
YesStringPossible 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 sharedIntegerString
total
YesIntegerString

Frequency Capping properties
Frequency Capping properties

NameRequiredData typeDescription
totalCompletionsLimit
YesIntegerRange 0-999
dailyCompletionsLimit
YesIntegerRange 0-999
minHoursBetweenCompletions
YesIntegerRange 0-72

Full request example
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
Response example

{
    "id": 382491
}

Update campaign
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
URL/Body parameters

NameRequiredData typeDescription
id
YesIntegerCampaign ID of the updated campaign
name
NoStringThe 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
Response example

{
    "success": true
}

Basic campaign targeting
Basic campaign targeting

Targeting setup API allows you to manage your campaign targeting (target titles, OS versions, Ad units, Device types).

Get campaign targeting
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
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
Body Parameters

NameRequiredData typeDefault valueDescription
targetTitles
NoStringallTitlesChose the titles you would like the campaign to target: allTitles, excludeMyTitles, crossPromo (only for permitted advertisers)
osVersions
NoObjectAllChoose 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
OS Versions properties

NameRequiredData typeDescription
range
NoObjectPossible values: min, max (See OS ranges property table below)
list
No
"all"
Array<String>

OS ranges properties
OS ranges properties

NameRequiredData typeDescription
max
YesStringUse any supported OS version or "latest"
min
NoStringUse any supported OS version Default value: minimum OS version for the campaign platform

Request body example
Request body example

{
    "targetTitles": "excludeMyTitles",
    "deviceTypes": ["phone"],
    "adFormats": ["interstitial"],
    "osVersions": {
        "range": {
            "min": "10.1",
            "max": "latest"
        }
    }
}

Next steps
Next steps

Learn how to update your campaign creatives with the Creatives API.