Advertisers

This article describes services for reading, adding, and updating updating advertisers.

Overview

A direct advertiser is a company that lists advertisements on Oath Ad Platforms DSP to purchase inventory provided by a range of publishers in the broader marketplace. A seat holder manages direct advertisers.

Endpoint

You can use this endpoint to read, create, and update advertiser objects.

/traffic/advertisers
  • Use the GET method to read advertisers.
  • Use the POST method to add new advertsiers.
  • Use the PUT method to update advertisers.

Resources

Advertiser Object

The Advertiser object contains the following fields:

Table 20 Advertiser Object Fields
Name Description Type Add Update
id Specifies the advertiser ID. integer N/A Required
name Specifies the name of the advertiser. string Required Optional
status

Specifies the current status of the advertiser. Options include:

  • If ACTIVE, the advertiser is active.
  • If INACTIVE, the advertiser is inactive.
string Required Optional
landingPageUrl Specifies the advertsier’s website URL. string Required Optional
iabCategoryId

Specifies primary category of the advertiser’s business.

Use the id field from the IAB Taxonomy Types response.

integer Required Optional
iabSecondaryCategoryId

Specifies secondary category of the advertiser’s business.

Use the id field from the IAB Taxonomy Types response.

integer Optional Optional
timezone

Specifies the default time zone for the advertiser’s data; the time zone used to aggregate adveriser data in reports.

Use the tzId field from the Timezones. Some example values: America/New_York, Etc/GMT.

string Required Optional
currency

Specifies the default currency for the advertiser’s data.

Use the code field from the Currency Types. For example, USD, CAD.

string Required Optional
billingMethodType

Specifies the advertiser’s billing method. Options include:

  • MARGIN: oCPM
string Optional Optional
billingPrice Specifies adveriser’s the percentage profit margin expressed as a value between 0 and 100. number Required Optional
contact

Specifies the adveriser’s primary contact information.

To learn more, see Contact Object.

object Optional Optional
isCrossdeviceOff

Enable or disable the optimization using cross device conversions. By default, false.

  • If true, does not track cross-device conversions. For example, if you validate conversions with vendors that cannot track mobile conversions, you may want to disable cross-device conversions.
  • If false, tracks and reports on conversions that take place across multiple devices. For example, if an impression is served to a user’s mobile device, but that user ends up converting and completing a purchase for the advertised product on their desktop, it is considered a cross-device conversion.
boolean Optional Optional
updatedAt Read-only field that specifies the time of the last update. string N/A N/A

Contact Object

The contact object contains the following fields:

Table 21 Contact Object Fields
Name Description Type Add Update
id Specifies the contact ID. integer N/A N/A
firstName Specifies the first name of the contact. string Required Optional
lastName Specifies the last name of the contact. string Required Optional
addressLine1 Specifies the first line of contact information. string Required Optional
addressLine2 Specifies the second line of contact information. string Optional Optional
city Specifies the contact’s city. string Required Optional
region Specifies the contact’s region or state. string Required Optional
postalCode Specifies the contact’s postal code. string Required Optional
country Specifies the contact’s country. string Required Optional
telephone Specifies the contact’s telephone number. string Optional Optional
email Specifies the email address of the advertiser contact. string Optional Optional

Example Payload

{
  "contact": {
    "firstName": "Admin",
    "lastName": "Yahoo",
    "addressLine1": "Yahoo1",
    "addressLine2": "701st Avenue",
    "city": "Sunnyvale",
    "region": "CA",
    "country": "United States",
    "telephone": "4574888849",
    "email": "admin@yahoo.com"
  }
}

Read Advertiser (Single)

To retrieve data for a specific Advertiser, make a GET call with the id parameter.

Parameters

Name Description Type Required?
id Specifies the advertiser ID integer Y

The response returns the advertiser associated with the specified ID.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/advertisers/1

Example Response

{
  "response": {
    "status": "ACTIVE",
    "timezone": "Etc/GMT",
    "currency": "USD",
    "id": 1,
    "name": "My Yahoo!!",
    "landingPageUrl": "https://www.yahoo.com",
    "iabCategoryId": 5,
    "iabSecondaryCategoryId": 501,
    "updatedAt": "2017-04-18T05:22:43Z",
    "billingPrice": 20,
    "contact": {
      "firstName": "Admin",
      "lastName": "Yahoo",
      "addressLine1": "Yahoo1",
      "addressLine2": "701st Avenue",
      "city": "Sunnyvale",
      "region": "CA",
      "country": "United States",
      "telephone": "4574888849",
      "email": "admin@yahoo.com"
    },
    "isCrossdeviceOff": false
  },
  "errors": null,
  "timeStamp": "2017-04-18T05:22:42Z"
}

Read Advertisers (Filtered)

To retrieve a filtered list of Advertisers, make a GET call with the supported query parameters.

GET https://dspapi.admanagerplus.yahoo.com/traffic/advertisers?page={page}&limit={limit}&sort={sort}&dir={dir}&query={query}

Parameters

Name Description Type Required?
page Page number string N
limit Total number of items to return. Maximum allowed value is 100. string N
sort Column to sort by string N
dir Sort direction. Valid values: asc, desc string N
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). string N

The response will be a list of matching Advertisers.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/advertisers?page=1&limit=2

Example Response

{
  "response": [
    {
      "status": "ACTIVE",
      "timezone": "America/New_York",
      "currency": "USD",
      "id": 1,
      "name": "My Yahoo!!",
      "landingPageUrl": "http://yahoo.com",
      "iabCategoryId": 1,
      "iabSecondaryCategoryId": 101,
      "accountGroupId": 2491,
      "updatedAt": "2017-04-15T02:46:03Z",
      "isCrossdeviceOff": false
    },
    {
      "status": "ACTIVE",
      "timezone": "America/Los_Angeles",
      "currency": "USD",
      "id": 2,
      "name": "Your Retail Sales Advertiser",
      "landingPageUrl": "http://www.yourretailsalesadvertiser.com",
      "iabCategoryId": 9,
      "iabSecondaryCategoryId": 927,
      "accountGroupId": 2491,
      "updatedAt": "2015-12-18T18:57:46Z",
      "isCrossdeviceOff": false
    }
  ],
  "errors": null,
  "timeStamp": "2017-04-18T05:32:09Z"
}

Update Advertisers

Updates the advertiser specified by its ID number.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/advertisers/{id}

Partial update is supported; fields that are either not passed or passed as null will be ignored during update.

Parameters

The advertiser account ID (id) is specified in the path of the resource endpoint. Al other parameters are defined in the body of the application/json payload.

Table 22 Update Advertiser Parameters
Name Parameter Type Description Type Required
id path Specifies the advertiser account ID. integer Required
name body Specifies the name of the advertiser. string Optional
status body

Specifies the current status of the advertiser. Options include:

  • If ACTIVE, the advertiser is active.
  • If INACTIVE, the advertiser is inactive.
string Optional
landingPageUrl body Specifies the advertsier’s website URL. string Optional
iabCategoryId body

Specifies primary category of the advertiser’s business.

Use the id field from the IAB Taxonomy Types response.

integer Optional
iabSecondaryCategoryId body

Specifies secondary category of the advertiser’s business.

Use the id field from the IAB Taxonomy Types response.

string Optional
timezone body

Specifies the default time zone for the advertiser’s data; the time zone used to aggregate adveriser data in reports.

Use the tzId field from the Timezones. Some example values: America/New_York, Etc/GMT.

string Optional
currency body

Specifies the default currency for the advertiser’s data.

Use the code field from the Currency Types. For example, USD, CAD.

string Optional
billingMethodType body

Specifies the advertiser’s billing method. Options include:

  • MARGIN: oCPM
string Optional
billingPrice body Specifies adveriser’s the percentage profit margin expressed as a value between 0 and 100. number Optional
contact body

Specifies the adveriser’s primary contact information.

To learn more, see Contact Object.

object Optional
isCrossdeviceOff body

Enable or disable the optimization using cross device conversions. By default, false.

  • If true, does not track cross-device conversions. For example, if you validate conversions with vendors that cannot track mobile conversions, you may want to disable cross-device conversions.
  • If false, tracks and reports on conversions that take place across multiple devices. For example, if an impression is served to a user’s mobile device, but that user ends up converting and completing a purchase for the advertised product on their desktop, it is considered a cross-device conversion.
boolean Optional

Example Request

PUT https://dspapi.admanagerplus.yahoo.com/traffic/advertisers/1

Example Payload

{
  "status": "ACTIVE",
  "isCrossdeviceOff": true,
  "billingPrice": 23,
  "currency": "USD"
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "timezone": "Etc/GMT",
    "currency": "USD",
    "id": 1,
    "name": "My Yahoo!!",
    "landingPageUrl": "https://www.yahoo.com",
    "iabCategoryId": 5,
    "iabSecondaryCategoryId": 501,
    "updatedAt": "2017-04-18T05:22:43Z",
    "billingPrice": 23,
    "contact": {
      "firstName": "Admin",
      "lastName": "Yahoo",
      "addressLine1": "Yahoo1",
      "addressLine2": "701st Avenue",
      "city": "Sunnyvale",
      "region": "CA",
      "country": "United States",
      "telephone": "4574888849",
      "email": "admin@yahoo.com"
    },
    "isCrossdeviceOff": true
  },
  "errors": null,
  "timeStamp": "2017-04-18T05:22:42Z"
}

Create Advertisers

Creates a new advertiser.

POST /traffic/advertisers

Parameters

All parameters are specified in the body of the application/json payload.

Table 23 Create Advertiser Parameters
Name Parameter Type Description Type Required
name body Specifies the name of the advertiser. string Required
status body

Specifies the current status of the advertiser. Options include:

  • If ACTIVE, the advertiser is active.
  • If INACTIVE, the advertiser is inactive.
string Required
landingPageUrl body Specifies the advertsier’s website URL. string Required
iabCategoryId body

Specifies primary category of the advertiser’s business.

Use the id field from the IAB Taxonomy Types response.

integer Required
iabSecondaryCategoryId body

Specifies secondary category of the advertiser’s business.

Use the id field from the IAB Taxonomy Types response.

integer Optional
timezone body

Specifies the default time zone for the advertiser’s data; the time zone used to aggregate adveriser data in reports.

Use the tzId field from the Timezones. Some example values: America/New_York, Etc/GMT.

string Required
currency body

Specifies the default currency for the advertiser’s data.

Use the code field from the Currency Types. For example, USD, CAD.

string Required
billingMethodType body

Specifies the advertiser’s billing method. Options include:

  • MARGIN: oCPM
string Optional
billingPrice body Specifies adveriser’s the percentage profit margin expressed as a value between 0 and 100. number Required
contact body

Specifies the adveriser’s primary contact information.

To learn more, see Contact Object.

object Optional
isCrossdeviceOff body

Enable or disable the optimization using cross device conversions. By default, false.

  • If true, does not track cross-device conversions. For example, if you validate conversions with vendors that cannot track mobile conversions, you may want to disable cross-device conversions.
  • If false, tracks and reports on conversions that take place across multiple devices. For example, if an impression is served to a user’s mobile device, but that user ends up converting and completing a purchase for the advertised product on their desktop, it is considered a cross-device conversion.
boolean Optional

Example Request

POST /traffic/advertisers

Example Payload

{
  "name": "TEST_1_3",
  "landingPageUrl": "http://www.example.com",
  "iabCategoryId": 5,
  "timezone": "Etc/GMT",
  "currency": "USD",
  "status": "ACTIVE",
  "billingPrice": 40.5,
  "contact": {
    "addressLine1": "1 N.First St",
    "addressLine2": "",
    "city": "Sunnyvale",
    "region": "CA",
    "postalCode": "94056",
    "country": "United States"
  }
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "timezone": "Etc/GMT",
    "currency": "USD",
    "id": 1259301,
    "name": "TEST_1_3",
    "landingPageUrl": "http://www.example.com",
    "iabCategoryId": 5,
    "iabSecondaryCategoryId": -1,
    "updatedAt": "2017-04-18T05:38:40Z",
    "billingPrice": 40.5,
    "contact": {
      "addressLine1": "1 N.First St",
      "addressLine2": "",
      "city": "Sunnyvale",
      "region": "CA",
      "postalCode": "94056",
      "country": "United States"
    },
    "isCrossdeviceOff": false
  },
  "errors": null,
  "timeStamp": "2017-04-18T05:38:39Z"
}

Delete Advertiser

Advertiser deletion is not supported by the API.

Read Advertiser Beacon Lookups

To retrieve the available beacons (conversion pixels), make a GET call with the accountId parameter.

GET /traffic/advertisers/{accountId}/beaconlookups

Parameters

Table 24 Read Advertiser Beacon Lookup Parameters
Parameter Parameter Type Description Data Type Required
accountId path Specifies the advertiser ID. integer Y

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/advertisers/1356341/beaconlookups

Example Response

{
  "response": [
    {
      "id": 6508313,
      "name": "test conversion1",
      "dotPixel": true
    },
    {
      "id": 6508309,
      "name": "CPA Pixel",
      "dotPixel": true
    }
  ],
  "errors": null,
  "timeStamp": "2017-06-07T21:10:45Z"
}