Advertisers

7 Minutes to read

Advertisers

7 Minutes to read

Article summary

Did you find this summary helpful?

Thank you for your feedback!

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

Overview

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

Endpoint

/traffic/advertisers

The action taken depends on the HTTP method and the parameters specified.

Use the GET method to read an existing advertiser.
Use the POST method to create a new advertiser.
Use the PUT method to update an existing advertiser.

Resources

Advertiser Object

The advertisers resource is defined by the following following fields:

Name	Description	Type	Create	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 advertiser’s website URL.	`string`	Required	Optional
`iabCategoryId`	Specifies the primary category of the advertiser’s business. Use the `id` field from the IAB Taxonomy Categories response where the `type` field is set to `PRIMARY`.	`integer`	Required	Optional
`iabSecondaryCategoryId`	Specifies a secondary category of the advertiser’s business. Use the `id` field from the IAB Taxonomy Categories response where the `type` field is set to `SECONDARY`.	`integer`	Required	Optional
`timezone`	Specifies the default time zone for the advertiser’s data; the time zone used to aggregate advertiser data in reports. Use the `tzId` field from the Timezones response. Some example values: `America/New_York`, `Etc/GMT`.	`string`	Required	N/A
`currency`	Specifies the default currency for the advertiser’s data. Use the `code` field from the Currency Types response. For example, `USD`, `CAD`.	`string`	Required	N/A
`billingPrice`	Specifies the advertiser’s percentage profit margin expressed as a value between 0 and 100.	`number`	Required	Optional
`contact`	Specifies the advertiser’s primary contact information. To learn more, refer to Contact Object.	`object`	Required	N/A
`billingContact`	Specifies the advertiser’s billing contact information. Billing contact fields are only included in the response for certain seats. To learn more, refer to Billing Contact Object.	`object`	Optional	N/A
`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:

Name	Description	Type	Add	Update
`firstName`	Specifies the first name of the contact.	`string`	Optional	Optional
`lastName`	Specifies the last name of the contact.	`string`	Optional	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`	Optional	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": "[email protected]"
  }
}

Billing Contact Object

Billing contact fields are only included in the response for certain seats that need to comply with country-specific laws (i.e. the Sapin II Law in France). The billingContact object contains the following fields:

Name	Description	Type	Add	Update
`firstName`	Specifies the first name of the billing contact.	`string`	Required	Required
`lastName`	Specifies the last name of the billing contact.	`string`	Required	Required
`email`	Specifies the email address of the advertiser billing contact.	`string`	Required	Required
`addressLine1`	Specifies the first line of the billing contact information.	`string`	Required	Required
`addressLine2`	Specifies the second line of the billing contact information.	`string`	Optional	Optional
`addressLine3`	Specifies the third line of the billing contact information.	`string`	Optional	Optional
`city`	Specifies the billing contact’s city.	`string`	Required	Required
`region`	Specifies the billing contact’s region or state.	`string`	Optional	Optional
`postalCode`	Specifies the billing contact’s postal code.	`string`	Optional	Optional
`country`	Specifies the billing contact’s country.	`string`	Required	Required
`vatNumber`	Specifies the billing contact’s VAT Number.	`string`	Optional	Optional
`legalMandateConfirmation`	Confirms sending the legal mandate to the account manager.	`boolean`	Required	Required

Example Payload

{
  "billingContact": {
    "firstName": "Admin",
    "lastName": "Yahoo",
    "email": "[email protected]",
    "addressLine1": "Yahoo1",
    "addressLine2": "701st Avenue",
    "city": "Sunnyvale",
    "region": "CA",
    "postalCode": "94089",
    "country": "United States",
    "vatNumber": "123456789",
    "legalMandateConfirmation": true
  }
}

Read Advertiser

Get data for a specific advertiser.

Parameters

Parameter	Parameter Type	Description	Data Type	Required
`id`	path	Specifies the advertiser ID.	`integer`	Y

Example Request URL

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": "[email protected]"
    },
    "isCrossdeviceOff": false
  },
  "errors": null,
  "timeStamp": "2017-04-18T05:22:42Z"
}

For seats that need to comply with country-specific laws (such as France’s Sapin II law) the response contains an additional billing contact section.

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": "[email protected]"
    },
    "billingContact": {
      "firstName": "Admin",
      "lastName": "Yahoo",
      "email": "[email protected]",
      "addressLine1": "Yahoo1",
      "addressLine2": "701st Avenue",
      "city": "Sunnyvale",
      "region": "CA",
      "postalCode": "94089",
      "country": "United States",
      "vatNumber": "123456789",
      "legalMandateConfirmation": true
    },
    "isCrossdeviceOff": false
  },
  "errors": null,
  "timeStamp": "2017-04-18T05:22:42Z"
}

Read Advertisers

Get a filtered list of advertisers.

GET /traffic/advertisers?query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}

Parameters

Parameter	Parameter Type	Description	Data Type	Required
`query`	query	Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a `+` or `%20`).	`string`	N
`page`	query	Specifies the page number.	`integer`	N
`limit`	query	Specifies the total number of items to return. Maximum allowed value is `100`.	`integer`	N
`sort`	query	Specifies the column to sort by.	`string`	N
`dir`	query	Specifies the sort direction. Allowed values: `ASC`: data is sorted in ascending order. `DESC`: data is sorted in descending order.	`string`	N

Example Request URL

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"
}

Create Advertiser

Create a new advertiser.

POST /traffic/advertisers

Parameters

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

Example Request URL

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

Example Request Body

{
  "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"
}

For seats that need to comply with country-specific laws (such as France’s Sapin II law) the payload should contain the billing contact fields.

Example Request Body

{
  "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"
  },
  "billingContact": {
    "firstName": "Admin",
    "lastName": "Yahoo",
    "email": "[email protected]",
    "addressLine1": "Yahoo1",
    "addressLine2": "701st Avenue",
    "city": "Sunnyvale",
    "region": "CA",
    "postalCode": "94089",
    "country": "United States",
    "vatNumber": "123456789",
    "legalMandateConfirmation": true
   }
}

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"
    },
    "billingContact": {
      "firstName": "Admin",
      "lastName": "Yahoo",
      "email": "[email protected]",
      "addressLine1": "Yahoo1",
      "addressLine2": "701st Avenue",
      "city": "Sunnyvale",
      "region": "CA",
      "postalCode": "94089",
      "country": "United States",
      "vatNumber": "123456789",
      "legalMandateConfirmation": true
    },
    "isCrossdeviceOff": false
  },
  "errors": null,
  "timeStamp": "2017-04-18T05:38:39Z"
}

Update Advertiser

Update an existing advertiser.

PUT /traffic/advertisers/{id}

Partial updates are supported; values of supported fields that are not in the payload remain unchanged. For seats that need to comply with country-specific laws (such as France’s Sapin II law) the payload can contain the billing contact fields.

Parameters

The Advertiser id is specified in the url path. All other fields are specified in the body of the application/json payload.

Example Request URL

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

Sample Request Body

{
  "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": "[email protected]",
      "postalCode": "94056"
    },
    "isCrossdeviceOff": true
  },
  "errors": null,
  "timeStamp": "2017-04-18T05:22:42Z"
}

Delete Advertiser

The DSP Traffic API does not support deletion of advertisers.

Read Advertiser Beacon Lookups

Get available beacons.

GET /traffic/advertisers/{accountId}/beaconlookups

Parameters

Parameter	Parameter Type	Description	Data Type	Required
`accountId`	path	Specifies the advertiser ID.	`integer`	Y

Example Request URL

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"
}

Was this article helpful?

What's Next

About Audiences

Contents

Overview
Endpoint
Resources
Read Advertiser
Read Advertisers
Create Advertiser
Update Advertiser
Delete Advertiser
Read Advertiser Beacon Lookups