Ad Sets

Ad Sets are the second level element of an advertising campaign. They serve as a container for one or multiple ads.

The Ad Sets Model

The Ad Sets model of n_2 describes an advertising ad set independently of the platform it is running on.

Properties

Name
id
Type
string
Description
Unique identifier for the ad set.
Name
name
Type
string
Description
Name of the ad set.
Name
platform
Type
string
Description
The platform the ad set is running on. See the Platforms section for a list of supported platforms. This parameter is read-only.
Name
status
Type
string
Description
Status of the ad set. Possible values are Running, Active, Paused, Archived and Deleted.
Name
advertiser
Type
string
Description
The advertiser the ad set belongs to. This is a reference to the advertiser id.
Name
parentId
Type
string
Description
The id of the campaign the ad set belongs to. This is a reference to the campaign id.
This may be renamed to campaignId in the future.
Name
channelKind
Type
string
Description
The kind of channel the ad set is running on. Possible values are Social, Search, Display, Video, Audio, DOOH, CTV and Mail. There also exists the Mixed value, which is used when the ad set contains ads that are running on multiple channels.
Name
settings
Type
list<Setting>
Description
A list of settings for the ad set. See the Settings Model for more information. Settings are used to represent the configuration of an ad set. Settings include things like runtimes, budgets and objectives.
Name
ads
Type
list<Ad>
Description
A list of ads that belong to the ad set. See the Ad Model for more information.
This parameter is optional and will only be included in GET request responses if the childResources parameter includes the value Ad.
Name
targetings
Type
list<Targeting>
Description
A list of targetings that belong to the ad set. See the Targeting Model for more information.
This parameter is optional and will only be included in GET request responses if the childResources parameter includes the value Targeting.

Example Object

   {
     "id": "12340987",
     "name": "My Ad Set",
     "platform": "GoogleAds",
     "status": "Active",
     "parentId": "1234567",
     "advertiser": "876543",
     "channelKind": "Search",
     "settings": [
       {
         "kind": "DailyBudget",
         "budget": 10,
         "currency": "EUR",
       },
       {
         "kind": "Objective",
         "objective": "Conversions"
       }
     ],
     "ads": [],
     "targetings": []
   }

GET/v1/<platform>/adsets

List all ad sets

This endpoint allows you to retrieve a paginated list of all your ad sets on a given platform. Refer to the list at the top of this page to see which properties are included with ad set objects.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of ad sets returned.
Name
status
Type
string
Description
Filter ad sets by status. Possible values are Running, Active, Paused, Archived and Deleted.
Name
childResources
Type
list<string>
Description
A list of child resources to include in the response. Possible values are Ad and Targeting.
Example 1: childResources=Ad,Targeting will include all the ads that belong to the ad sets. Along with the ads, all targetings that belong to the ad sets and the corresponding ads will also be included.
Example 2: childResources=Targeting will include all targetings that belong to the ad set. If the platform does not support targetings on the ad set level, this will be ignored.
Defaults to an empty list.
Name
dismissDatabase
Type
boolean
Description
Setting this to true will request ad sets directly from the platform. This will return all ad sets that are currently live on the platform, regardless of their status in our caching database. This is useful if you want to get the latest data from the platform. Notice that this will be slower than the default behaviour.
Defaults to false.

Request

GET

/v1/GoogleAds/adsets

curl -G https://api.n2api.io/v1/GoogleAds/adsets \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d status=Active \
  -d childResources=Ad,Targeting

Response

{
  "has_more": false,
  "data": [
    {
      "id": "12340987",
      "name": "My Ad Set",
      "platform": "GoogleAds",
      "status": "Active",
      "parentId": "1234567",
      "advertiser": "876543",
      "channelKind": "Search",
      "settings": [
        {
          "kind": "DailyBudget",
          "budget": 10,
          "currency": "EUR",
        },
        {
          "kind": "Objective",
          "objective": "Conversions"
        }
      ],
      "ads": [
        {
          "id": "1234569827",
          ...
        }
      ],
      "targetings": [
        {
          "kind": "KeywordTargeting",
          "keywords": [
            "keyword 1",
            "keyword 2",
            "keyword 3"
          ]
        },
        {
          "kind": "GeoTargeting",
          "type": "ZipcodeGeoTargeting",
          "zipcodes": [
            {
              "country": "DE",
              "zipcode": "10115"
            },
            {
              "country": "DE",
              "zipcode": "10117"
            }
          ]
        }
      ]
    }
    {
      "id": "1234569828",
      ...
    }
  ]
}

POST/v1/<platform>/adsets

Create an ad set

This endpoint allows you to create a new ad set. Refer to the list at the top of this page to see which properties are included with ad set objects.

Required attributes in the request body

Name
name
Type
string
Description
Name of the ad set.
Name
advertiser
Type
string
Description
The advertiser the ad set belongs to. This is a reference to the advertiser id.
Name
parentId
Type
string
Description
The id of the campaign the ad set belongs to. This is a reference to the campaign id.
This may be renamed to campaignId in the future.
Name
channelKind
Type
string
Description
The kind of channel the ad set is running on. Possible values are Social, Search, Display, Video, Audio, DOOH, CTV and Mail. There also exists the Mixed value, which is used when the campaign is running on multiple channels.
Name
settings
Type
list<Setting>
Description
A list of settings for the ad set. See the Settings Model for more information. Settings are used to represent the configuration of an ad set. Settings include things like runtimes, budgets and objectives.
Name
targetings
Type
list<Targeting>
Description
A list of targetings that belong to the ad set. See the Targeting Model for more information.
Name
status
Type
string
Description
Status of the newly created ad set. Possible values are Running, Active, Paused, Archived and Deleted.
Defaults to Paused.

Request

POST

/v1/GoogleAds/adsets

curl https://api.n2api.io/v1/GoogleAds/adsets \
  -H "Authorization: Bearer {token}" \
  -d name="My Ad Set" \
  -d advertiser="876543" \
  -d channelKind="Search" \
  -d status="Active" \
  -d parentId="1234567" \
  -d settings='[{"kind":"TotalBudget","budget":1000,"currency":"EUR"}]' \
  -d targetings='[{"kind":"KeywordTargeting","keywords":["keyword 1","keyword 2","keyword 3"]}]'

Response

{
  "id": "12340987",
  "name": "My Ad Set",
  "platform": "GoogleAds",
  "status": "Active",
  "parentId": "1234567",
  "advertiser": "876543",
  "channelKind": "Search",
  "settings": [
    {
      "kind": "TotalBudget",
      "budget": 1000,
      "currency": "EUR",
    },
  ],
  "ads": [],
  "targetings": [
    {
      "kind": "KeywordTargeting",
      "keywords": [
        "keyword 1",
        "keyword 2",
        "keyword 3"
      ]
    }
  ]
}

GET/v1/<platform>/adsets/:id

Retrieve an ad set

This endpoint allows you to retrieve a single ad set by its id. Refer to the list at the top of this page to see which properties are included with ad set objects.

Optional attributes

Name
childResources
Type
list<string>
Description
A list of child resources to include in the response. Possible values are Ad and Targeting.
Example 1: childResources=Targeting,Ad will include all the targetings that belong to the ad set. Along with the targetings, all ads that belong to the ad set and the corresponding targetings will also be included.
Example 2: childResources=Targeting will include all targetings that belong to the ad set. If the platform does not support targetings on the ad set level, this will be ignored.
Defaults to an empty list.
Name
dismissDatabase
Type
boolean
Description
Setting this to true will request the ad set directly from the platform. This will return the ad set that is currently live on the platform, regardless of its status in our caching database. This is useful if you want to get the latest data from the platform. Notice that this will be slower than the default behaviour.
Defaults to false.

Request

GET

/v1/GoogleAds/adsets/12340987

curl -G https://api.n2api.io/v1/GoogleAds/adsets/12340987 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "12340987",
  "name": "My Ad Set",
  "platform": "GoogleAds",
  "status": "Active",
  "parentId": "1234567",
  "advertiser": "876543",
  "channelKind": "Search",
  "settings": [
    {
      "kind": "TotalBudget",
      "budget": 1000,
      "currency": "EUR",
    },
  ]
}

PUT/v1/<platform>/adsets/:id

Update an ad set

This endpoint allows you to update an ad set. Refer to the list at the top of this page to see which properties are included with ad set objects.

Optional attributes in the request body

Name
name
Type
string
Description
New name of the ad set.
Name
status
Type
string
Description
New status of the ad set. Possible values are Running, Active, Paused, Archived and Deleted.

Updating settings

See the settings model for more information on how to update settings on an ad set.

Updating targetings

See the targeting model for more information on how to update targetings on an ad set.

Request

PUT

/v1/GoogleAds/adsets/12340987

curl https://api.n2api.io/v1/GoogleAds/adsets/12340987 \
  -X PUT \
  -H "Authorization: Bearer {token}" \
  -d name="My renamed Ad Set" \

Response

{
  "id": "12340987",
  "name": "My renamed Ad Set",
  "platform": "GoogleAds",
  "status": "Active",
  "parentId": "1234567",
  "advertiser": "876543",
  "channelKind": "Search",
  "settings": [
    {
      "kind": "TotalBudget",
      "budget": 1000,
      "currency": "EUR",
    },
  ]
}

DELETE/v1/<platform>/adsets/:id

Delete an ad set

This endpoint allows you to delete an ad set.

Request

DELETE

/v1/GoogleAds/adsets/12340987

curl https://api.n2api.io/v1/GoogleAds/adsets/12340987 \
  -X DELETE \
  -H "Authorization: Bearer {token}"

Response

{
  deletions: 1,
  data: [
    {
      "id": "12340987",
      "name": "My renamed Ad Set",
      "platform": "GoogleAds",
      "status": "Deleted",
      "parentId": "1234567",
      "advertiser": "876543",
      "channelKind": "Search",
      "settings": [
        {
          "kind": "TotalBudget",
          "budget": 1000,
          "currency": "EUR",
        },
      ]
    }
  ]
}