Objects

The Verizon Media API provides you with a set of RESTful Objects that you can use to create, manage and retrieve advertiser data for your ads, ad groups and campaigns programmatically.

Using these RESTful Objects, you can access HTTP resources, which return a set of JSON representations along with their corresponding data types.

Data Model

The data model for the Verizon Media v3 API is not based on services, but rather on calling the same RESTful object with a different HTTP method.

To better understand the relationships between the entities and data objects, you may wish to study this diagram.

v2 api gemini data model

Each object type with associated fields, endpoints and example representations is described in detail in the Objects list.

Note

The Verizon Media v3 API includes a library of shared sets. For more information on these new objects, refer to Shared Sets Library.

Object Representation

Each object representation – Ad, Ad Group, Advertiser, Campaign – includes a field description that lists, in table format, its name and data type, as well as additional information for adding and updating. The Endpoint for the resource URI is then provided, followed by example representations with RESTful responses associated with standard GET, PUT and POST calls.

To retrieve data for an ad campaign, for example, you would make a GET call with an ID parameter that you’ve specified (31336), like this:

https://api.gemini.yahoo.com/v2/rest/campaign/31336


{
  "errors": null,
  "response": {
      "id": 31336,
      "status": "PAUSED",
      "advertiserId": 87292,
      "campaignName": "SampleCampaign",
      "budget": 100,
      "language": "en",
      "budgetType": "LIFETIME",
      "channel": "SEARCH_AND_NATIVE",
      "objective": "PROMOTE_BRAND",
      "isPartnerNetwork": "TRUE",
      "defaultLandingUrl": null
  }
}

The response is then the campaign associated with the given ID, as shown above.

If you want to clear the value of any optional string field, for example, you would pass in an empty string when you update the object. As shown below, to clear the landing url for the keyword id 1234, you would make a PUT call to the keyword endpoint, like this, passing in:

{
  "id": 1234,
  "landingUrl": ""
}

The response would be:

{
  "errors": null,
  "response": {
      "exclude": "FALSE",
      "bidSet": null,
      "status": "ACTIVE",
      "id": 1234,
      "advertiserId": 99,
      "landingUrl": null,
      "parentType": "ADGROUP",
      "parentId": 5678,
      "matchType": "BROAD",
      "adParamValues": null,
      "value": "keyword value"
   }
}

Important

The Verizon Media API exposes lastUpdateDate and createdDate as read-only fields in API responses for all Verizon Media API objects. These fields provide UNIX timestamps for when an object was created and last updated.

Partial Updates

In general, Verizon Media APIs support partial updates for each RESTful object represented in the v3 API. Note that partial updates are ignored if you pass NULL in your JSON response. For string attributes, you need to pass an empty string “” to explicitly erase the value. Integers are handled differently, and may be erased with 0 or -1 on a case-by-case basis. See specific object attributes documentation for those details.

Limits

The following table provides details on the object limits supported in the Verizon Media API:

Object

Limit

Campaigns per advertiser account

10,000

Ad groups per campaign

10,000

Keywords per advertiser account

5,000,000

Keywords per ad group

10,000

Ads per ad group

50

Negative keywords per advertiser account

5,000,000

Location targeting objects per advertiser account

100,000

Location WOEID targeting per campaign or adgroup

10,000

Maximum number of objects passed in API call

500

Shared Sets per account

20

Negative Keywords per Shared Set

5000

Shared Sitelinks per account

5000

Important

The total number of campaigns per account for advertisers is 10,000. Once you reach that limit and go beyond it, an error message is returned. There are no restrictions on the number of campaigns you can create daily. Note that for location WOEID targeting per campaign or adgroup, there is also a 10,000 maximum limit.

[New] Matrix View of Search Changes When Serving Eligible Channels

The following table describes the behavior (current and new) for Search when serving eligible channels. For terminology: SON means Search on Native, SRN means Search Retargeting on Native, KRT means Keyword Retargeting. Note that for SON, the sub_channel can be SRN_AND_SEARCH or SRN_ONLY.

Input Channel

Input Sub-Channel

Current

New

SEARCH

SRN_AND_SEARCH

SEARCH, SON

SON

SEARCH

NULL

SEARCH, SON (based on the advertiser’s setup. Category 1 -> Search Only. Category [2|3|4] -> SEARCH, SON)

No OP., or SON (based on the Advertiser’s setup. Category 1 -> No OP. Category [2|3|4] -> SON)

NATIVE

SRN_ONLY

NATIVE KRT

NATIVE KRT

SEARCH AND NATIVE

NULL

SEARCH, NATIVE

NATIVE


The following table describes the current behavior (unchanged) for Search when serving eligible channels.

Input Channel

Input Sub-Channel

Current

New

SEARCH

SRN_ONLY

SON

SON

NATIVE

SRN_AND_SEARCH

Throws an exception

Throws an exception

NATIVE

NULL

NATIVE

NATIVE

SEARCH AND NATIVE

SRN_AND_SEARCH

Throws an exception

Throws an exception

SEARCH and NATIVE

SRN_ONLY

Throws an exception

Throws an exception

Matrix View of Required fields When Serving Different Ad Types

The Verizon Media API provides you with methods for adding, updating, and retrieving ads. The following table is a matrix view of required fields when serving different ad types:

Ad Type

Campaign-Channel

Campaign-Objective

Campaign-defaultLandingUrl

Bid types

Ad-imageUrl

Ad-imageUrlHQ

Ad-videoPrimaryUrl

Assets

Ad-mailAssetUrl

Ad-imageUrlThumbnail

Ad-videoPreviewStartTime

Search Ad

Search, Search_and_Native

VISIT_WEB

CPC

Yahoo Mail Ad

Native

VISIT_WEB, MAIL_SPONSORED

CPC

required

required

Native Stream Ad

Native, Search_and_Native

VISIT_WEB, PROMOTE_BRAND

CPC, CPM

required for CPM

required for CPM

Native Magazine Ad

Native, Search_and_Native

VISIT_WEB, PROMOTE_BRAND

CPC, CPM

required

required

Video Ad (Native)

Native

PROMOTE_BRAND, VISIT_WEB

CPM, CPV, CPC

required

required

required

Video Ad (App Install)

Native

INSTALL_APP

app store url

CPC

required

required

required

Install App

Native

INSTALL_APP

app store url

CPC

required

required

Reengage App

Native

REENGAGE_APP

app store url

CPC

required

required

Native Carousel Ad

Native

VISIT_WEB, PROMOTE_BRAND

CPC, CPM

required

required

required

Yahoo Mail Trailer Video Ad

Native

VISIT_WEB, MAIL_SPONSORED

CPV, CPC

required

required

required

required

recommended


Important

The programmatic Verizon Media API does not rely explicitly on ad types, but rather on a combination of assets and objectives when targeting users and serving ads. This combination is based on campaign settings and objectives, targeting attributes and bid types, as well as landing page URLs, and other required fields used to serve Verizon Media Ad Platform ads.

For more information on the Verizon Media Ad object, refer to Ad.

Changes to Landing URLs or Text Attributes

Any changes to either the landing urls or the text attributes of the following entities – Ad, Keywords and Sitelinks – will result in an editorial status review, with the following values: NOT_REVIEWED, PENDING_REVIEW, APPROVED, OR REJECTED. Note that our SLA is 24 hours; however, in practice, most ads are re-activated in 1 to 2 hours. Please plan your edits and sync logic, accordingly.