Grow your game ironSource Ads ironSource Ads User Acquisition Campaign API Leverage the Campaign API to automate the creation, modification, and management of your ad campaigns.
Read time 6 minutes
Last updated 3 months 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 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). No Comma separated campaign ids - - Filter campaigns by a list if campaign ids No Comma separated title ids - - Filter campaigns by a list if title ids No Boolean true, false Filter pending creation campaigns `isActive No Boolean true, false Filter active or inactive campaigns No Boolean true, false Filter archived or non archived campaigns No String name, creationDate, dailyBudget, totalBudget, startDate, endDate CreationDate Order campaigns results, if no order and direction supplied, default sort is by creationDate desc. No String asc, desc asc No String - \ Used for paginated requests. No Number Any positive integer 1 Used for paginated requests. 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/:campaignIdRequired 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/:isActiveRequired Parameters
campaignId
URL Parameters
Name Required Data type Description Yes Number Campaign ID we would like to change its activation status Yes Boolean Possible values: - isActive = true Update campaign status to Active - isActive = false Update campaign status to Inactive
Example Response
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 Yes String Supported types of campaigns: userAcquisition Yes String Campaign bid type available: CPI , CPM , tCPI Yes Integer Title ID of the created campaign Yes String The name of the campaign Yes Object Campaign scheduling. See Timeline properties table below Yes Object <{clickUrl, impressionUrl, type}> Campaign measurement URLs and SKAN settings. See Attribution properties table below Yes Object Set campaign budget type and value See Budget properties table below 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 Yes Date String Date today Yes Date Date null
Attribution properties
Name Required Data type Description Yes String Yes String 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 Yes String Possible values: - shared - Set one daily budget for the entire campaign - byCountry - Set a daily budget for each country group separately. Yes, if budget type is shared Integer String Campaign daily budget: Range 50-2000000 unlimited Yes Integer String Campaign total budget: Range 100-2000000 unlimited
Frequency Capping properties
Name Required Data type Description Yes Integer Range 0-999 Yes Integer Range 0-999 minHoursBetweenCompletionsYes 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
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 Yes Integer Campaign ID of the updated campaign No String The name of the campaign No Object Campaign scheduling See Timeline properties table No Object <{clickUrl, impressionUrl}> Campaign measurement URLs and SKAN settings See Attribution properties table No Object Set campaign budget type and value See Budget properties table 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
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 : BearerMethod : GETRequest Example URL : https://api.ironsrc.com/advertisers/v4/targeting/campaign/:campaignId Required Parameters : campaignIdResponse 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 : PUTRequest Example URL : https://api.ironsrc.com/advertisers/v4/targeting/campaign/:campaignId Required Parameters : campaignIdBody Parameters
Name Required Data type Default value Description No String allTitles Chose the titles you would like the campaign to target: allTitles, excludeMyTitles, crossPromo (only for permitted advertisers) No Object All Choose a range, list of OS versions (See OS Versions property table below) No "phone", "tablet" Choose Device type: phone, tablet No "interstitial", "rewardedVideo" Choose Ad units: Interstitial, rewardedVideoFormally called "Ad units" (adUnits)
OS Versions properties
Name Required Data type Description No Object Possible values: min , max (See OS ranges property table below) No 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 Yes String Use any supported OS version or "latest" 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 .