Campaign API

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

Read time 6 minutes

Last updated 4 hours ago

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

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

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"
        }
    }
}

Next steps

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

Campaign API

Authentication Type

Get campaigns

Method

Request Example URL

Required Parameters

Parameters

Name

Required

Type

Allowed values

Default value

Description

Response example

Get creation state

Method

Request Example URL

Required Parameters

Parameters

Name

Required

Data type

Description

Example response

Update activation status

Method

Request Example URL

Required Parameters

URL Parameters

Name

Required

Data type

Description

Example Response

Create campaign

Method

Request Example URL

Required Parameters

Body Parameters

Name

Required

Data type

Description

Timelines properties

Name

Required

Data type

Description

Attribution properties

Name

Required

Data type

Description

Budget properties

Name

Required

Data type

Description

Frequency Capping properties

Name

Required

Data type

Description

Full request example

Response example

Update campaign

Method

Request example URL

Required parameters

URL/Body parameters

Name

Required

Data type

Description

Full request example

Response example

Basic campaign targeting

Get campaign targeting

Update campaign targeting

Body Parameters