Prospecting API Reference

Note

If you use the API provided here, you are subject to the API Terms of Use. To be able to create prospecting objects your advertisable(s) must be opted-in to the Prospecting Services Addendum.

Note

We’ve introduced API keys, please read Migrating to API Keys

Description

Prospecting API v2

Operations

GET /prospecting/api/v2/adgroups/(adgroup)

Get AdGroup by its EID.

Parameters:

Path Parameters

Name

Required

Type

Description

adgroup

True

string

AdGroup EID to get.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "ads": [
      {
        "ad_eid": "string",
        "ad_eids": "string",
        "adgroup_eid": "string",
        "admin_status": "string",
        "advertisable_eid": "string",
        "campaign_eid": "string",
        "campaign_name": "string",
        "eid": "string",
        "is_active": true,
        "skip_approve_ad": true,
        "status": "string",
        "user_status": "string"
      }
    ],
    "advertisable_eid": "string",
    "attribute_targets": [
      {
        "name": "string",
        "options": [
          {
            "name": "string",
            "target": true
          }
        ]
      }
    ],
    "attribute_targets_segment": "string",
    "audience": {
      "adgroup_eid": "string",
      "created_at": "string",
      "eid": "string",
      "size": 0,
      "source_segment_eid": "string",
      "target_segment_eid": "string",
      "updated_at": "string"
    },
    "auto_audience": true,
    "auto_geo_targets": true,
    "campaign_eid": "string",
    "contextual_targets": [
      {
        "name": "string",
        "options": [
          {
            "name": "string",
            "target": true
          }
        ]
      }
    ],
    "contextual_targets_segment": "string",
    "created_at": "string",
    "device_targets": {},
    "eid": "string",
    "geo_targets": [
      {
        "city": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region_code": "string",
          "type": "string"
        },
        "country": {
          "code": "string",
          "country": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "geo_eid": "string",
        "is_excluded": true,
        "metro": {
          "boundaries": "string",
          "country": "string",
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "name": "string",
        "operation": "string",
        "postal_code": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "type": "string"
        },
        "region": {
          "country": "string",
          "eid": "string",
          "id": "string",
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region": "string",
          "type": "string"
        },
        "type": "string"
      }
    ],
    "is_active": true,
    "name": "string",
    "status": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object

POST /prospecting/api/v2/adgroups/(adgroup)

Edit an AdGroup by its EID.

Parameters:

Path Parameters

Name

Required

Type

Description

adgroup

True

string

AdGroup EID to edit.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "ads": [
      {
        "ad_eid": "string",
        "ad_eids": "string",
        "adgroup_eid": "string",
        "admin_status": "string",
        "advertisable_eid": "string",
        "campaign_eid": "string",
        "campaign_name": "string",
        "eid": "string",
        "is_active": true,
        "skip_approve_ad": true,
        "status": "string",
        "user_status": "string"
      }
    ],
    "advertisable_eid": "string",
    "attribute_targets": [
      {
        "name": "string",
        "options": [
          {
            "name": "string",
            "target": true
          }
        ]
      }
    ],
    "attribute_targets_segment": "string",
    "audience": {
      "adgroup_eid": "string",
      "created_at": "string",
      "eid": "string",
      "size": 0,
      "source_segment_eid": "string",
      "target_segment_eid": "string",
      "updated_at": "string"
    },
    "auto_audience": true,
    "auto_geo_targets": true,
    "campaign_eid": "string",
    "contextual_targets": [
      {
        "name": "string",
        "options": [
          {
            "name": "string",
            "target": true
          }
        ]
      }
    ],
    "contextual_targets_segment": "string",
    "created_at": "string",
    "device_targets": {},
    "eid": "string",
    "geo_targets": [
      {
        "city": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region_code": "string",
          "type": "string"
        },
        "country": {
          "code": "string",
          "country": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "geo_eid": "string",
        "is_excluded": true,
        "metro": {
          "boundaries": "string",
          "country": "string",
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "name": "string",
        "operation": "string",
        "postal_code": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "type": "string"
        },
        "region": {
          "country": "string",
          "eid": "string",
          "id": "string",
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region": "string",
          "type": "string"
        },
        "type": "string"
      }
    ],
    "is_active": true,
    "name": "string",
    "status": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object

GET /prospecting/api/v2/adgroups/(adgroup)/audience

Retrieve the audience for the specified AdGroup.

Parameters:

Path Parameters

Name

Required

Type

Description

adgroup

True

string

AdGroup EID to get audience from.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "adgroup_eid": "string",
    "created_at": "string",
    "eid": "string",
    "size": 0,
    "source_segment_eid": "string",
    "target_segment_eid": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object

POST /prospecting/api/v2/adgroups/(adgroup)/audience

Create an audience for the specified AdGroup.

Parameters:

Path Parameters

Name

Required

Type

Description

adgroup

True

string

AdGroup EID to create an audience for.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "adgroup_eid": "string",
    "created_at": "string",
    "eid": "string",
    "size": 0,
    "source_segment_eid": "string",
    "target_segment_eid": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object

GET /prospecting/api/v2/adgroups/(adgroup)/flights

Get all Flights associated with an AdGroup.

Parameters:

Path Parameters

Name

Required

Type

Description

adgroup

True

string

AdGroup EID to get Flights from.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": [
    {
      "adgroup_eid": "string",
      "created_at": "string",
      "eid": "string",
      "end_date": "string",
      "start_date": "string",
      "updated_at": "string"
    }
  ]
}
Schema
Type

object

results
Type

array of items

POST /prospecting/api/v2/adgroups/(adgroup)/flights

Create a new Flight for an AdGroup.

Parameters:

Path Parameters

Name

Required

Type

Description

adgroup

True

string

AdGroup EID that the new Flight is being added to

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Flight created successfully.

Schema as JSON:

{
  "results": {
    "adgroup_eid": "string",
    "created_at": "string",
    "eid": "string",
    "end_date": "string",
    "start_date": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object

400

The Flight was not created.

  • Your Flight might be missing start/end dates.

  • The start date might be greater than the end date.

  • Your Flight might be overlapping with another of the adgroup’s Flights.

Schema as JSON:

{
  "code": 0,
  "message": "Unknown type"
}
Schema
Type

object

code

HTTP error code.

Type

integer

message

String, list, or dictionary of error messages. If a dictionary, the keys will be field names and the values will be lists of messages.

GET /prospecting/api/v2/adgroups/(adgroup)/geo-targets

Retrieve GeoTargets for the specified AdGroup.

Parameters:

Path Parameters

Name

Required

Type

Description

adgroup

True

string

AdGroup EID to get GeoTargets from.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "data": [
      {
        "city": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region_code": "string",
          "type": "string"
        },
        "country": {
          "code": "string",
          "country": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "geo_eid": "string",
        "is_excluded": true,
        "metro": {
          "boundaries": "string",
          "country": "string",
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "name": "string",
        "operation": "string",
        "postal_code": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "type": "string"
        },
        "region": {
          "country": "string",
          "eid": "string",
          "id": "string",
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region": "string",
          "type": "string"
        },
        "type": "string"
      }
    ],
    "eid": "string"
  }
}
Schema
Type

object

results
Type

object

POST /prospecting/api/v2/adgroups/(adgroup)/geo-targets

Edit GeoTargets for the specified AdGroup.

Parameters:

Path Parameters

Name

Required

Type

Description

adgroup

True

string

AdGroup EID to add GeoTargets to.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Schema for request body:

[
  {
    "eid": "string",
    "operation": "string"
  }
]
Schema
Type

array

Responses:

200

Schema as JSON:

{
  "results": {
    "data": [
      {
        "city": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region_code": "string",
          "type": "string"
        },
        "country": {
          "code": "string",
          "country": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "geo_eid": "string",
        "is_excluded": true,
        "metro": {
          "boundaries": "string",
          "country": "string",
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "name": "string",
        "operation": "string",
        "postal_code": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "type": "string"
        },
        "region": {
          "country": "string",
          "eid": "string",
          "id": "string",
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region": "string",
          "type": "string"
        },
        "type": "string"
      }
    ],
    "eid": "string"
  }
}
Schema
Type

object

results
Type

object

GET /prospecting/api/v2/advertisables/(adv)/campaigns

Get campaigns for the given advertisable.

Parameters:

Path Parameters

Name

Required

Type

Description

adv

True

string

Advertisable EID to get campaigns from.

Query Parameters

Name

Required

Type

Description

is_active

False

boolean

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": [
    {
      "adgroups": [
        {
          "ads": [
            {
              "ad_eid": "string",
              "ad_eids": "string",
              "adgroup_eid": "string",
              "admin_status": "string",
              "advertisable_eid": "string",
              "campaign_eid": "string",
              "campaign_name": "string",
              "eid": "string",
              "is_active": true,
              "skip_approve_ad": true,
              "status": "string",
              "user_status": "string"
            }
          ],
          "advertisable_eid": "string",
          "attribute_targets": [
            {
              "name": "string",
              "options": [
                {
                  "name": "string",
                  "target": true
                }
              ]
            }
          ],
          "attribute_targets_segment": "string",
          "audience": {
            "adgroup_eid": "string",
            "created_at": "string",
            "eid": "string",
            "size": 0,
            "source_segment_eid": "string",
            "target_segment_eid": "string",
            "updated_at": "string"
          },
          "auto_audience": true,
          "auto_geo_targets": true,
          "campaign_eid": "string",
          "contextual_targets": [
            {
              "name": "string",
              "options": [
                {
                  "name": "string",
                  "target": true
                }
              ]
            }
          ],
          "contextual_targets_segment": "string",
          "created_at": "string",
          "device_targets": {},
          "eid": "string",
          "geo_targets": [
            {
              "city": {
                "country_code": "string",
                "eid": "string",
                "id": 0,
                "is_facebook_target": true,
                "name": "string",
                "name_localized": "string",
                "region_code": "string",
                "type": "string"
              },
              "country": {
                "code": "string",
                "country": "string",
                "eid": "string",
                "id": 0,
                "is_facebook_target": true,
                "name": "string",
                "server_id": 0,
                "type": "string"
              },
              "geo_eid": "string",
              "is_excluded": true,
              "metro": {
                "boundaries": "string",
                "country": "string",
                "country_code": "string",
                "eid": "string",
                "id": 0,
                "is_facebook_target": true,
                "name": "string",
                "server_id": 0,
                "type": "string"
              },
              "name": "string",
              "operation": "string",
              "postal_code": {
                "country_code": "string",
                "eid": "string",
                "id": 0,
                "is_facebook_target": true,
                "name": "string",
                "type": "string"
              },
              "region": {
                "country": "string",
                "eid": "string",
                "id": "string",
                "is_facebook_target": true,
                "name": "string",
                "name_localized": "string",
                "region": "string",
                "type": "string"
              },
              "type": "string"
            }
          ],
          "is_active": true,
          "name": "string",
          "status": "string",
          "updated_at": "string"
        }
      ],
      "admin_notes": "string",
      "admin_status": "string",
      "advertisable_eid": "string",
      "contextual_targeting_categories": [
        {
          "category_id": 0,
          "category_name": "string"
        }
      ],
      "created_at": "string",
      "currency_code": "string",
      "eid": "string",
      "end_date": "string",
      "frequency_cap": 0,
      "is_active": true,
      "kpi_goal": 0.0,
      "kpi_metric": "string",
      "name": "string",
      "source": "49er",
      "start_date": "string",
      "status": "string",
      "targeting_type": "lookalike",
      "updated_at": "string",
      "user_status": "string",
      "vcpc": 0.0,
      "vcpx": 0.0,
      "weekly_budget": 0.0
    }
  ]
}
Schema
Type

object

results
Type

array of items

POST /prospecting/api/v2/advertisables/(adv)/campaigns

Create a campaign for the specified advertisable.

Parameters:

Path Parameters

Name

Required

Type

Description

adv

True

string

Advertisable EID to create the campaign for.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "adgroups": [
      {
        "ads": [
          {
            "ad_eid": "string",
            "ad_eids": "string",
            "adgroup_eid": "string",
            "admin_status": "string",
            "advertisable_eid": "string",
            "campaign_eid": "string",
            "campaign_name": "string",
            "eid": "string",
            "is_active": true,
            "skip_approve_ad": true,
            "status": "string",
            "user_status": "string"
          }
        ],
        "advertisable_eid": "string",
        "attribute_targets": [
          {
            "name": "string",
            "options": [
              {
                "name": "string",
                "target": true
              }
            ]
          }
        ],
        "attribute_targets_segment": "string",
        "audience": {
          "adgroup_eid": "string",
          "created_at": "string",
          "eid": "string",
          "size": 0,
          "source_segment_eid": "string",
          "target_segment_eid": "string",
          "updated_at": "string"
        },
        "auto_audience": true,
        "auto_geo_targets": true,
        "campaign_eid": "string",
        "contextual_targets": [
          {
            "name": "string",
            "options": [
              {
                "name": "string",
                "target": true
              }
            ]
          }
        ],
        "contextual_targets_segment": "string",
        "created_at": "string",
        "device_targets": {},
        "eid": "string",
        "geo_targets": [
          {
            "city": {
              "country_code": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "name_localized": "string",
              "region_code": "string",
              "type": "string"
            },
            "country": {
              "code": "string",
              "country": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "server_id": 0,
              "type": "string"
            },
            "geo_eid": "string",
            "is_excluded": true,
            "metro": {
              "boundaries": "string",
              "country": "string",
              "country_code": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "server_id": 0,
              "type": "string"
            },
            "name": "string",
            "operation": "string",
            "postal_code": {
              "country_code": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "type": "string"
            },
            "region": {
              "country": "string",
              "eid": "string",
              "id": "string",
              "is_facebook_target": true,
              "name": "string",
              "name_localized": "string",
              "region": "string",
              "type": "string"
            },
            "type": "string"
          }
        ],
        "is_active": true,
        "name": "string",
        "status": "string",
        "updated_at": "string"
      }
    ],
    "admin_notes": "string",
    "admin_status": "string",
    "advertisable_eid": "string",
    "contextual_targeting_categories": [
      {
        "category_id": 0,
        "category_name": "string"
      }
    ],
    "created_at": "string",
    "currency_code": "string",
    "eid": "string",
    "end_date": "string",
    "frequency_cap": 0,
    "is_active": true,
    "kpi_goal": 0.0,
    "kpi_metric": "string",
    "name": "string",
    "source": "49er",
    "start_date": "string",
    "status": "string",
    "targeting_type": "lookalike",
    "updated_at": "string",
    "user_status": "string",
    "vcpc": 0.0,
    "vcpx": 0.0,
    "weekly_budget": 0.0
  }
}
Schema
Type

object

results
Type

object

PATCH /prospecting/api/v2/advertisables/(adv)/campaigns

Change either user_status or currency_code (not both) for all campaigns belonging to the given advertisable. Completed or inactive campaigns won’t be affected when changing the user_status.budget and kpi_goal fields will be updated accordingly on each campaign when currency_code is changed.

Parameters:

Path Parameters

Name

Required

Type

Description

adv

True

string

Advertisable EID associated with the patched campaigns.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": [
    {
      "adgroups": [
        {
          "ads": [
            {
              "ad_eid": "string",
              "ad_eids": "string",
              "adgroup_eid": "string",
              "admin_status": "string",
              "advertisable_eid": "string",
              "campaign_eid": "string",
              "campaign_name": "string",
              "eid": "string",
              "is_active": true,
              "skip_approve_ad": true,
              "status": "string",
              "user_status": "string"
            }
          ],
          "advertisable_eid": "string",
          "attribute_targets": [
            {
              "name": "string",
              "options": [
                {
                  "name": "string",
                  "target": true
                }
              ]
            }
          ],
          "attribute_targets_segment": "string",
          "audience": {
            "adgroup_eid": "string",
            "created_at": "string",
            "eid": "string",
            "size": 0,
            "source_segment_eid": "string",
            "target_segment_eid": "string",
            "updated_at": "string"
          },
          "auto_audience": true,
          "auto_geo_targets": true,
          "campaign_eid": "string",
          "contextual_targets": [
            {
              "name": "string",
              "options": [
                {
                  "name": "string",
                  "target": true
                }
              ]
            }
          ],
          "contextual_targets_segment": "string",
          "created_at": "string",
          "device_targets": {},
          "eid": "string",
          "geo_targets": [
            {
              "city": {
                "country_code": "string",
                "eid": "string",
                "id": 0,
                "is_facebook_target": true,
                "name": "string",
                "name_localized": "string",
                "region_code": "string",
                "type": "string"
              },
              "country": {
                "code": "string",
                "country": "string",
                "eid": "string",
                "id": 0,
                "is_facebook_target": true,
                "name": "string",
                "server_id": 0,
                "type": "string"
              },
              "geo_eid": "string",
              "is_excluded": true,
              "metro": {
                "boundaries": "string",
                "country": "string",
                "country_code": "string",
                "eid": "string",
                "id": 0,
                "is_facebook_target": true,
                "name": "string",
                "server_id": 0,
                "type": "string"
              },
              "name": "string",
              "operation": "string",
              "postal_code": {
                "country_code": "string",
                "eid": "string",
                "id": 0,
                "is_facebook_target": true,
                "name": "string",
                "type": "string"
              },
              "region": {
                "country": "string",
                "eid": "string",
                "id": "string",
                "is_facebook_target": true,
                "name": "string",
                "name_localized": "string",
                "region": "string",
                "type": "string"
              },
              "type": "string"
            }
          ],
          "is_active": true,
          "name": "string",
          "status": "string",
          "updated_at": "string"
        }
      ],
      "admin_notes": "string",
      "admin_status": "string",
      "advertisable_eid": "string",
      "contextual_targeting_categories": [
        {
          "category_id": 0,
          "category_name": "string"
        }
      ],
      "created_at": "string",
      "currency_code": "string",
      "eid": "string",
      "end_date": "string",
      "frequency_cap": 0,
      "is_active": true,
      "kpi_goal": 0.0,
      "kpi_metric": "string",
      "name": "string",
      "source": "49er",
      "start_date": "string",
      "status": "string",
      "targeting_type": "lookalike",
      "updated_at": "string",
      "user_status": "string",
      "vcpc": 0.0,
      "vcpx": 0.0,
      "weekly_budget": 0.0
    }
  ]
}
Schema
Type

object

results
Type

array of items

GET /prospecting/api/v2/advertisables/(adv)/settings

Get advertisable settings.

Parameters:

Path Parameters

Name

Required

Type

Description

adv

True

string

Advertisable EID to get settings for.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "advertisable": "string",
    "ctc_weight": 0.0,
    "ctc_window": 0,
    "vtc_weight": 0.0,
    "vtc_window": 0
  }
}
Schema
Type

object

results
Type

object

POST /prospecting/api/v2/advertisables/(adv)/settings

Edit advertisable settings.

Parameters:

Path Parameters

Name

Required

Type

Description

adv

True

string

Advertisable EID to edit settings for.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "advertisable": "string",
    "ctc_weight": 0.0,
    "ctc_window": 0,
    "vtc_weight": 0.0,
    "vtc_window": 0
  }
}
Schema
Type

object

results
Type

object

GET /prospecting/api/v2/attribute_names/(adv)

Returns the full set of available per-source attribute data

Parameters:

Path Parameters

Name

Required

Type

Description

adv

True

string

Advertisable EID

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

List of sources for the advertisable,where every key is a source

Schema as JSON:

{
  "[source]": {
    "attributes": {
      "[attribute_name]": {
        "values": {
          "[value]": {
            "id": 0.0
          }
        }
      }
    }
  }
}
Schema

List of sources for the advertisable,where every key is a source

Type

object

[source]

All attributes for the source

Type

object

GET /prospecting/api/v2/attribute_names/(adv)/sources

Returns a list of strings containing the NAMEs of theattribute sources

Parameters:

Path Parameters

Name

Required

Type

Description

adv

True

string

Advertisable EID

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

List of sources availablefor the advertisable

Schema as JSON:

[
  "string"
]
Schema
Type

array

GET /prospecting/api/v2/attribute_names/(adv)/(name)

Returns all information about the NAME’d attribute source, if the advertisable may access it.

Parameters:

Path Parameters

Name

Required

Type

Description

adv

True

string

Advertisable EID

name

True

string

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

All attributes for the source

Schema as JSON:

{
  "attributes": {
    "[attribute_name]": {
      "values": {
        "[value]": {
          "id": 0.0
        }
      }
    }
  }
}
Schema

All attributes for the source

Type

object

attributes

List of attributes for the source, where every key is an attribute

Type

object

GET /prospecting/api/v2/audiences/(audience)

Retrieve an audience with the specified EID.

Parameters:

Path Parameters

Name

Required

Type

Description

audience

True

string

Audience EID to get.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "adgroup_eid": "string",
    "created_at": "string",
    "eid": "string",
    "size": 0,
    "source_segment_eid": "string",
    "target_segment_eid": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object

POST /prospecting/api/v2/audiences/(audience)

Edit audience by its EID.

Parameters:

Path Parameters

Name

Required

Type

Description

audience

True

string

Audience EID to edit.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "adgroup_eid": "string",
    "created_at": "string",
    "eid": "string",
    "size": 0,
    "source_segment_eid": "string",
    "target_segment_eid": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object

GET /prospecting/api/v2/campaigns/(campaign)

Retrieve a campaign with the specified EID.

Parameters:

Path Parameters

Name

Required

Type

Description

campaign

True

string

Campaign EID to get.

Query Parameters

Name

Required

Type

Description

event_source

False

string

Default: fortyniner-ui.

active_adgroups_only

False

boolean

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "adgroups": [
      {
        "ads": [
          {
            "ad_eid": "string",
            "ad_eids": "string",
            "adgroup_eid": "string",
            "admin_status": "string",
            "advertisable_eid": "string",
            "campaign_eid": "string",
            "campaign_name": "string",
            "eid": "string",
            "is_active": true,
            "skip_approve_ad": true,
            "status": "string",
            "user_status": "string"
          }
        ],
        "advertisable_eid": "string",
        "attribute_targets": [
          {
            "name": "string",
            "options": [
              {
                "name": "string",
                "target": true
              }
            ]
          }
        ],
        "attribute_targets_segment": "string",
        "audience": {
          "adgroup_eid": "string",
          "created_at": "string",
          "eid": "string",
          "size": 0,
          "source_segment_eid": "string",
          "target_segment_eid": "string",
          "updated_at": "string"
        },
        "auto_audience": true,
        "auto_geo_targets": true,
        "campaign_eid": "string",
        "contextual_targets": [
          {
            "name": "string",
            "options": [
              {
                "name": "string",
                "target": true
              }
            ]
          }
        ],
        "contextual_targets_segment": "string",
        "created_at": "string",
        "device_targets": {},
        "eid": "string",
        "geo_targets": [
          {
            "city": {
              "country_code": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "name_localized": "string",
              "region_code": "string",
              "type": "string"
            },
            "country": {
              "code": "string",
              "country": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "server_id": 0,
              "type": "string"
            },
            "geo_eid": "string",
            "is_excluded": true,
            "metro": {
              "boundaries": "string",
              "country": "string",
              "country_code": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "server_id": 0,
              "type": "string"
            },
            "name": "string",
            "operation": "string",
            "postal_code": {
              "country_code": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "type": "string"
            },
            "region": {
              "country": "string",
              "eid": "string",
              "id": "string",
              "is_facebook_target": true,
              "name": "string",
              "name_localized": "string",
              "region": "string",
              "type": "string"
            },
            "type": "string"
          }
        ],
        "is_active": true,
        "name": "string",
        "status": "string",
        "updated_at": "string"
      }
    ],
    "admin_notes": "string",
    "admin_status": "string",
    "advertisable_eid": "string",
    "contextual_targeting_categories": [
      {
        "category_id": 0,
        "category_name": "string"
      }
    ],
    "created_at": "string",
    "currency_code": "string",
    "eid": "string",
    "end_date": "string",
    "frequency_cap": 0,
    "is_active": true,
    "kpi_goal": 0.0,
    "kpi_metric": "string",
    "name": "string",
    "source": "49er",
    "start_date": "string",
    "status": "string",
    "targeting_type": "lookalike",
    "updated_at": "string",
    "user_status": "string",
    "vcpc": 0.0,
    "vcpx": 0.0,
    "weekly_budget": 0.0
  }
}
Schema
Type

object

results
Type

object

POST /prospecting/api/v2/campaigns/(campaign)

Edit a campaign with the specified EID.

Parameters:

Path Parameters

Name

Required

Type

Description

campaign

True

string

Campaign EID to edit.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "adgroups": [
      {
        "ads": [
          {
            "ad_eid": "string",
            "ad_eids": "string",
            "adgroup_eid": "string",
            "admin_status": "string",
            "advertisable_eid": "string",
            "campaign_eid": "string",
            "campaign_name": "string",
            "eid": "string",
            "is_active": true,
            "skip_approve_ad": true,
            "status": "string",
            "user_status": "string"
          }
        ],
        "advertisable_eid": "string",
        "attribute_targets": [
          {
            "name": "string",
            "options": [
              {
                "name": "string",
                "target": true
              }
            ]
          }
        ],
        "attribute_targets_segment": "string",
        "audience": {
          "adgroup_eid": "string",
          "created_at": "string",
          "eid": "string",
          "size": 0,
          "source_segment_eid": "string",
          "target_segment_eid": "string",
          "updated_at": "string"
        },
        "auto_audience": true,
        "auto_geo_targets": true,
        "campaign_eid": "string",
        "contextual_targets": [
          {
            "name": "string",
            "options": [
              {
                "name": "string",
                "target": true
              }
            ]
          }
        ],
        "contextual_targets_segment": "string",
        "created_at": "string",
        "device_targets": {},
        "eid": "string",
        "geo_targets": [
          {
            "city": {
              "country_code": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "name_localized": "string",
              "region_code": "string",
              "type": "string"
            },
            "country": {
              "code": "string",
              "country": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "server_id": 0,
              "type": "string"
            },
            "geo_eid": "string",
            "is_excluded": true,
            "metro": {
              "boundaries": "string",
              "country": "string",
              "country_code": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "server_id": 0,
              "type": "string"
            },
            "name": "string",
            "operation": "string",
            "postal_code": {
              "country_code": "string",
              "eid": "string",
              "id": 0,
              "is_facebook_target": true,
              "name": "string",
              "type": "string"
            },
            "region": {
              "country": "string",
              "eid": "string",
              "id": "string",
              "is_facebook_target": true,
              "name": "string",
              "name_localized": "string",
              "region": "string",
              "type": "string"
            },
            "type": "string"
          }
        ],
        "is_active": true,
        "name": "string",
        "status": "string",
        "updated_at": "string"
      }
    ],
    "admin_notes": "string",
    "admin_status": "string",
    "advertisable_eid": "string",
    "contextual_targeting_categories": [
      {
        "category_id": 0,
        "category_name": "string"
      }
    ],
    "created_at": "string",
    "currency_code": "string",
    "eid": "string",
    "end_date": "string",
    "frequency_cap": 0,
    "is_active": true,
    "kpi_goal": 0.0,
    "kpi_metric": "string",
    "name": "string",
    "source": "49er",
    "start_date": "string",
    "status": "string",
    "targeting_type": "lookalike",
    "updated_at": "string",
    "user_status": "string",
    "vcpc": 0.0,
    "vcpx": 0.0,
    "weekly_budget": 0.0
  }
}
Schema
Type

object

results
Type

object

GET /prospecting/api/v2/campaigns/(campaign)/adgroups

Get AdGroups that belong to given campaign.

Parameters:

Path Parameters

Name

Required

Type

Description

campaign

True

string

Campaign EID to get AdGroups from.

Query Parameters

Name

Required

Type

Description

is_active

False

boolean

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": [
    {
      "ads": [
        {
          "ad_eid": "string",
          "ad_eids": "string",
          "adgroup_eid": "string",
          "admin_status": "string",
          "advertisable_eid": "string",
          "campaign_eid": "string",
          "campaign_name": "string",
          "eid": "string",
          "is_active": true,
          "skip_approve_ad": true,
          "status": "string",
          "user_status": "string"
        }
      ],
      "advertisable_eid": "string",
      "attribute_targets": [
        {
          "name": "string",
          "options": [
            {
              "name": "string",
              "target": true
            }
          ]
        }
      ],
      "attribute_targets_segment": "string",
      "audience": {
        "adgroup_eid": "string",
        "created_at": "string",
        "eid": "string",
        "size": 0,
        "source_segment_eid": "string",
        "target_segment_eid": "string",
        "updated_at": "string"
      },
      "auto_audience": true,
      "auto_geo_targets": true,
      "campaign_eid": "string",
      "contextual_targets": [
        {
          "name": "string",
          "options": [
            {
              "name": "string",
              "target": true
            }
          ]
        }
      ],
      "contextual_targets_segment": "string",
      "created_at": "string",
      "device_targets": {},
      "eid": "string",
      "geo_targets": [
        {
          "city": {
            "country_code": "string",
            "eid": "string",
            "id": 0,
            "is_facebook_target": true,
            "name": "string",
            "name_localized": "string",
            "region_code": "string",
            "type": "string"
          },
          "country": {
            "code": "string",
            "country": "string",
            "eid": "string",
            "id": 0,
            "is_facebook_target": true,
            "name": "string",
            "server_id": 0,
            "type": "string"
          },
          "geo_eid": "string",
          "is_excluded": true,
          "metro": {
            "boundaries": "string",
            "country": "string",
            "country_code": "string",
            "eid": "string",
            "id": 0,
            "is_facebook_target": true,
            "name": "string",
            "server_id": 0,
            "type": "string"
          },
          "name": "string",
          "operation": "string",
          "postal_code": {
            "country_code": "string",
            "eid": "string",
            "id": 0,
            "is_facebook_target": true,
            "name": "string",
            "type": "string"
          },
          "region": {
            "country": "string",
            "eid": "string",
            "id": "string",
            "is_facebook_target": true,
            "name": "string",
            "name_localized": "string",
            "region": "string",
            "type": "string"
          },
          "type": "string"
        }
      ],
      "is_active": true,
      "name": "string",
      "status": "string",
      "updated_at": "string"
    }
  ]
}
Schema
Type

object

results
Type

array of items

POST /prospecting/api/v2/campaigns/(campaign)/adgroups

Create an AdGroup for the given campaign.

Parameters:

Path Parameters

Name

Required

Type

Description

campaign

True

string

Campaign EID to add AdGroup to.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "ads": [
      {
        "ad_eid": "string",
        "ad_eids": "string",
        "adgroup_eid": "string",
        "admin_status": "string",
        "advertisable_eid": "string",
        "campaign_eid": "string",
        "campaign_name": "string",
        "eid": "string",
        "is_active": true,
        "skip_approve_ad": true,
        "status": "string",
        "user_status": "string"
      }
    ],
    "advertisable_eid": "string",
    "attribute_targets": [
      {
        "name": "string",
        "options": [
          {
            "name": "string",
            "target": true
          }
        ]
      }
    ],
    "attribute_targets_segment": "string",
    "audience": {
      "adgroup_eid": "string",
      "created_at": "string",
      "eid": "string",
      "size": 0,
      "source_segment_eid": "string",
      "target_segment_eid": "string",
      "updated_at": "string"
    },
    "auto_audience": true,
    "auto_geo_targets": true,
    "campaign_eid": "string",
    "contextual_targets": [
      {
        "name": "string",
        "options": [
          {
            "name": "string",
            "target": true
          }
        ]
      }
    ],
    "contextual_targets_segment": "string",
    "created_at": "string",
    "device_targets": {},
    "eid": "string",
    "geo_targets": [
      {
        "city": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region_code": "string",
          "type": "string"
        },
        "country": {
          "code": "string",
          "country": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "geo_eid": "string",
        "is_excluded": true,
        "metro": {
          "boundaries": "string",
          "country": "string",
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "server_id": 0,
          "type": "string"
        },
        "name": "string",
        "operation": "string",
        "postal_code": {
          "country_code": "string",
          "eid": "string",
          "id": 0,
          "is_facebook_target": true,
          "name": "string",
          "type": "string"
        },
        "region": {
          "country": "string",
          "eid": "string",
          "id": "string",
          "is_facebook_target": true,
          "name": "string",
          "name_localized": "string",
          "region": "string",
          "type": "string"
        },
        "type": "string"
      }
    ],
    "is_active": true,
    "name": "string",
    "status": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object

GET /prospecting/api/v2/campaigns/(campaign)/geo-targets

Retrieve GeoTargets for the specified Campaign.

Parameters:

Path Parameters

Name

Required

Type

Description

campaign

True

string

Campaign EID to get GeoTargets from.

Query Parameters

Name

Required

Type

Description

active_adgroups_only

False

boolean

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": [
    {
      "adgroup": "string",
      "geotargets": [
        {
          "city": {
            "country_code": "string",
            "eid": "string",
            "id": 0,
            "is_facebook_target": true,
            "name": "string",
            "name_localized": "string",
            "region_code": "string",
            "type": "string"
          },
          "country": {
            "code": "string",
            "country": "string",
            "eid": "string",
            "id": 0,
            "is_facebook_target": true,
            "name": "string",
            "server_id": 0,
            "type": "string"
          },
          "geo_eid": "string",
          "is_excluded": true,
          "metro": {
            "boundaries": "string",
            "country": "string",
            "country_code": "string",
            "eid": "string",
            "id": 0,
            "is_facebook_target": true,
            "name": "string",
            "server_id": 0,
            "type": "string"
          },
          "name": "string",
          "operation": "string",
          "postal_code": {
            "country_code": "string",
            "eid": "string",
            "id": 0,
            "is_facebook_target": true,
            "name": "string",
            "type": "string"
          },
          "region": {
            "country": "string",
            "eid": "string",
            "id": "string",
            "is_facebook_target": true,
            "name": "string",
            "name_localized": "string",
            "region": "string",
            "type": "string"
          },
          "type": "string"
        }
      ]
    }
  ]
}
Schema
Type

object

results
Type

array of items

PUT /prospecting/api/v2/flights/(flight)

Edit a Flight.

Parameters:

Path Parameters

Name

Required

Type

Description

flight

True

string

Flight EID to edit.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Flight edited successfully.

Schema as JSON:

{
  "results": {
    "adgroup_eid": "string",
    "created_at": "string",
    "eid": "string",
    "end_date": "string",
    "start_date": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object

400

The Flight was not edited.

  • Your Flight might be missing start/end dates.

  • The start date might be greater than the end date.

  • Your Flight might be overlapping with another of the adgroup’s Flights.

Schema as JSON:

{
  "code": 0,
  "message": "Unknown type"
}
Schema
Type

object

code

HTTP error code.

Type

integer

message

String, list, or dictionary of error messages. If a dictionary, the keys will be field names and the values will be lists of messages.

DELETE /prospecting/api/v2/flights/(flight)

Delete a Flight.

Parameters:

Path Parameters

Name

Required

Type

Description

flight

True

string

Flight EID to delete.

Query Parameters

Name

Required

Type

Description

apikey

False

string

Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the NextRoll Developer site

Responses:

200

Schema as JSON:

{
  "results": {
    "adgroup_eid": "string",
    "created_at": "string",
    "eid": "string",
    "end_date": "string",
    "start_date": "string",
    "updated_at": "string"
  }
}
Schema
Type

object

results
Type

object