Advertisers / Accounts

Overview

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

Endpoint

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

Fields

The Advertiser object contains the following fields:

Name Description Type Add Update
id ID of the advertiser. integer N/A Required
name Name of the advertiser (up to 25 characters). text Required Optional
status

Current status of the advertiser.

  • ACTIVE - Active.
  • INACTIVE - Inactive
text Required Optional
landingPageUrl URL of the advertiser’s website. text Required Optional
iabCategoryId Primary category for the advertiser’s business. Use the id field from the IAB Taxonomy Types response. integer Required Optional
iabSecondaryCategoryId Secondary category for the advertiser’s business. Use the id field from the IAB Taxonomy Types response. integer Optional Optional
timezone Default timezone in which the advertiser’s data will be aggregated for running reports. Use the tzId field from Timezones response. Some example values: America/New_York, Etc/GMT. text Required Optional
currency Currency in which transactions should be displayed for this advertiser. Use the code field from the Currency Types response. Some example values: USD, CAD. text Required Optional
billingMethodType

Advertiser billing method.

  • MARGIN - oCPM
text Optional Optional
billingPrice % Profit Margin. This value must be a percentage between 0 and 100 if billingMethodType is MARGIN. float Optional Optional
contact Advertiser primary contact information. Refer to contact object. object Optional Optional
isCrossdeviceOff

Enable or disable the Optimize using Cross Device Conversions.

  • 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.
  • false - (Default Value) 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

contact object

The contact object contains the following fields:

Name Description Type Add Update
id ID of the contact. integer N/A N/A
firstName First Name of the advertiser’s primary contact. text Required Optional
lastName Last Name of the advertiser’s primary contact. text Required Optional
addressLine1 Address Line 1 text Required Optional
addressLine2 Address Line 2 text Optional Optional
city City” text Required Optional
region State text Required Optional
postalCode Zip/Postal Code text Required Optional
country Country text Required Optional
telephone Telephone text Optional Optional
email email address for the advertiser contact. text 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.

GET https://dspapi.admanagerplus.yahoo.com/traffic/advertisers/{id}
Name Description Type Required?
id Advertiser ID integer Y

The response will be the Advertiser associated with the given ID.

Example Request

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

Example Response

{
  "response": {
    "status": "ACTIVE",
    "timezone": "Etc/GMT",
    "currency": "USD",
    "billingMethodType": "MARGIN",
    "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}
Name Description Type Required?
page Page number integer N
limit Total number of items to return. Maximum allowed value is 100. integer N
sort Column to sort by text N
dir Sort direction. Valid values: asc, desc text N
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text 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 Advertiser

To update an existing Advertiser, make a PUT call with a payload body and id parameter. The response will be the updated Advertiser.

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

PUT https://dspapi.admanagerplus.yahoo.com/traffic/advertisers/{id}
Name Description Type Required?
id Advertiser ID integer Y

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",
    "billingMethodType": "MARGIN",
    "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 Advertiser

To create a new Advertiser, make a POST call with a payload body. The response will be the newly created Advertiser.

Example Request

POST https://dspapi.admanagerplus.yahoo.com/traffic/advertisers

Example Payload

{
  "name": "TEST_1_3",
  "landingPageUrl": "http://www.example.com",
  "iabCategoryId": 5,
  "timezone": "Etc/GMT",
  "currency": "USD",
  "status": "ACTIVE",
  "billingMethodType": "MARGIN",
  "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",
    "billingMethodType": "MARGIN",
    "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 https://dspapi.admanagerplus.yahoo.com/traffic/advertisers/{accountId}/beaconlookups
Name Description Type Required?
accountId Advertiser ID integer Y

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/advertisers/491/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"
}