Documentation

Support

ironSource Ads

Monetization

User Acquisition

Get started as a DSP partner

ironSource Ads

Country group API

Employ the Country Group API to define, update, and manage Country groupings for targeted campaign delivery.
Read time 4 minutesLast updated 4 hours ago
The Country group API allows you to configure your campaign Country groups, set their budget, target different countries within each Country group and set bid and optimizer goal for each Country. Authentication Type: Bearer API Authentication

Get campaign Country groups

Use this API to retrieve a list of all of your Country configurations per campaign. Method: GET Request Example URL: https://api.ironsrc.com/advertisers/v4/CountryGroup/:campaignId Required parameters: campaignId

Response example

{
    "campaignId": 8405744,
    "CountryGroups": [
        {
            "id": 16854,
            "name": "12345",
            "budget": 700,
            "countries": [
                {
                    "Country": "AT",
                    "bid": 6,
                    "setupGoal": "default"
                },
                {
                    "Country": "AU",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "CA",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "CH",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "CN",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "DE",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "DK",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "FR",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "GB",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "IL",
                    "bid": 11,
                    "setupGoal": 4
                },
                {
                    "Country": "JP",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "NO",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "NZ",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "SE",
                    "bid": "default",
                    "setupGoal": "default"
                },
                {
                    "Country": "US",
                    "bid": 7,
                    "setupGoal": 3
                }
            ]
        }
    ]
}

Get Country group setup

Use this API to retrieve a specific Country group configuration for a campaign. Required Parameters: Campaign Id Method: GET Request Example URL: https://api.ironsrc.com/advertisers/v4/CountryGroup/:campaignId /:CountryGroupId Required parameters: campaignId, CountryGroupId

Response example

[
    {
        "campaignId": 16854,
        "name": "12345",
        "budget": 700,
        "countries": [
            {
                "Country": "AT",
                "bid": 6,
                "setupGoal": "default"
            },
            {
                "Country": "AU",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "CA",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "CH",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "CN",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "DE",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "DK",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "FR",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "GB",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "IL",
                "bid": 11,
                "setupGoal": 4
            },
            {
                "Country": "JP",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "NO",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "NZ",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "SE",
                "bid": "default",
                "setupGoal": "default"
            },
            {
                "Country": "US",
                "bid": 7,
                "setupGoal": 3
            }
        ]
    }
]

Create Country group

Use this API to create a Country group. Method: POST Request Example URL: https://api.ironsrc.com/advertisers/v4/CountryGroup/:campaignId Required parameters: campaignId

Body parameters

Name

Required

Data type

Description

nameYesStringName for Country group
dailyBudgetYes, if campaign budget is by Countrynumber'unlimited'Daily budget for Country group
countriesYes
array 
<{Country, bid, setupGoal}>
Countries values for Country group See Country Properties table below

Country properties

Name

Required

Data type

Description

Countryyesstring (only valid Country name)Country code (2 letters representing the Country)
bidyesnumber"default"the bid for the specific Country. min: 0.001, max number after decimals : 3
setupGoalyes, if campaign is optimizednumber"default"the setup goal for a specific Country. for ROAS campaigns: min : 0.1 max numbers after decimal point: 1 for TCPA campaigns: min : 0.1 max : 1000 max numbers after decimal point: 2

Full request example

{
  "name": "name1377",
  "dailyBudget" :  "unlimited",
  "countries": [
    {"Country": "AT", "bid": 8, "setupGoal" : 12}
  ]
}

Response example

{
    "id": 382491
}

Update Country group

Use this API to update a specific Country groups configuration. Authentication Type: Bearer Method: PUT Request Example URL: https://api.ironsrc.com/advertisers/v4/CountryGroup/:campaignId/:CountryGroupId Required parameters: campaignId, CountryGroupId

Body parameters

Name

Required

Data type

Description

nameNoStringName for Country group
dailyBudgetnonumber'unlimited'Daily budget for Country group
countriesno
array 
<{Country, bid, setupGoal}>
countries values for Country group See Country Properties table below

Country properties

Name

Required

Data type

Description

Countryyesstring (only valid Country name)Country code (2 letters representing the Country)
bidyesnumber"default"The bid for the specific Country. min: 0.001, max number after decimals: 3
setupGoalyes, if campaign is optimizednumber"default"The setup goal for a specific Country. For ROAS campaigns: min : 0.1 max numbers after decimal point: 1 for TCPA campaigns: min : 0.1 max : 1000 max numbers after decimal point: 2

Full request example

{
  "countries": [
    {"Country": "AT", "bid": "default", "setupGoal" : 12}
  ]
}

Response example

{
    "success": true
}

Delete Country group

Use this API to delete a specific Country group. Method: DELETE Request Example URL: https://api.ironsrc.com/advertisers/v4/CountryGroup/:campaignId/:CountryGroupId Required parameters: campaignId, CountryGroupId

Response example

{
    "success": true
}

Delete countries from Country group

Use this API to delete countries from a specific Country group. Authentication Type: Bearer Method: DELETE Request Example URL: https://api.ironsrc.com/advertisers/v4/CountryGroup/:campaignId/:CountryGroupId/countries Required parameters: campaignId, CountryGroupId

Body parameters

Name

Required

Data type

Description

removeyes
array <string>
an array of countries you want to remove from the Country group

Full request example

{
  "remove": ["GR", "EG", "QA"]
}

Response example

{
    "success": true
}

Get default bid and setup goal

Use this API in order to get the default values for Country groups Method: Get Request Example URL: https://api.ironsrc.com/advertisers/v4/CountryGroup/:campaignId/default Required parameters: campaignId

Full response example

{
    "setupGoal" : 4,
    "bid" : 2
}

Update default bid and setup goal

Use this API to update default bids and goals for your campaigns. Method: PUT Request Example URL: https://api.ironsrc.com/advertisers/v4/CountryGroup/:campaignId/default Required parameters: campaignId

Body parameters

Name

Required

Data type

Description

setupGoalNonumberthe default setupGoal
bidNonumberthe default bid

Full request example

{
    "setupGoal" : 4,
    "bid" : 2
}

Response example

{
    "success": true
}