Yahoo developer network
Native
Yahoo developer network logo
  • Open Source
  • APIs
  • Advertising
  • Blog
  • Events
  • Podcasts
  • Apps
  • Native
  • Documentation

    • Yahoo Native to Yahoo DSP API Migration Guide
      • Understanding Domain Models
      • Migration scenarios
      • Campaign package structure
      • Understanding DSP packages
      • Seat types
      • Authorization
      • Advertiser
      • Campaigns
      • Lines
      • Blocked cases
      • Pixels
      • Reporting
      • Targeting
      • Postman toolkit
      • Appendix
      • Sample code
        • Create DSP shell
        • Create DSP creative
        • Flatten & Filter Targeting attributes
    • What’s New
    • Latest Updates
    • Get Started - API Endpoints
    • Navigating the API
      • Authentication
      • Testing - Sandbox
      • Versioning
      • API v1 Deprecation & v2 Changes
      • FAQs
    • Objects
      • Advertisers
      • Campaigns
      • Ad Group
      • Ad
      • Keyword
      • Targeting Attribute
      • Ad Extensions
      • Shared Sitelink
      • Shared Sitelink Setting
      • Ad Site Setting
    • Matrix View of Ad Types
    • Postman API Toolkit
    • Upgraded URLs
      • Migration path
    • Yahoo Native Ads
      • Native Ad Matrix View
      • Moments Ads
      • Search Ads
      • Image Ads
      • Mail Ads
      • Carousel Ads
      • Tiles Ads
      • Native Video Ads
      • App Install Ads
    • Frequency Cap
    • Reach and Performance
    • Dynamic Product Ads
    • Enhanced Attribution
    • Account Change History
    • Bulk Operations
      • Bulk File Schema & Fields
      • Bulk Upload API
      • Bulk Download API
      • Best Practices
    • Shared Set Libraries
      • Create shared sets
      • Populate shared sets
      • Associate shared sets
    • Audience Management
      • Audiences from websites
      • Audiences from customer lists
      • Audiences from your app
      • Audiences from email lists
      • Lookalike audiences
      • Conversion rule audiences
      • Dot tags
      • Conversion rules
      • Utilize Dot tags & conversion rules
      • Custom audience strategies
    • Reporting
      • Cubes
      • Dimensions
      • FAQs
    • Reseller Management API
    • Resources
      • Dynamic Parameters
      • Data Dictionary
      • Best Practices
      • Error Codes and Responses
      • Release Notes - Archived
    • Glossary
      • Glossary of Yahoo Native Terms
    • Partner Support
      • Product bulletin 2023 January
      • Product bulletin 2022 December
      • Product bulletin 2022 November
      • Product bulletin 2022 October
      • Product bulletin 2022 September
      • Product bulletin 2022 August
    • Policies
    • Advertiser Guide - UI
    • Technical Notes
      • Search on native
      • Create, serve & filter shared sitelinks
    • Server-to-Server Specifications
      • App Install Spec
      • In-app Events Spec
      • Post-install Spec
  • Sign In
  • Language:
    • English (U.S.)
    • 中文(香港)
    • 中文(台灣)

Ad¶

Abstract¶

The AdService provides methods for adding, updating, and retrieving ads.

Overview¶

An ad is an assembly of creatives and other ad details, like title, description, landing page URL, display URL, and more.

Important

If you wish to remove optional string attributes, like mailAssetUrl or imageUrlThumbnail, you can pass an empty string on the update operation.

Technical Requirements for Images¶

We recommend using high-quality PNG files for your native ads. Include a rectangular image (1200x627 pixels) with a 1.9:1 aspect ratio, and a square image (627x627 pixels) with a 1:1 aspect ratio (required).

Larger images than 1200x627 pixels and 627x627 pixels may be used as long as they maintain the 1.9:1 aspect ratio and 1:1 aspect ratio, respectively.

Ideally, the Square Image (627x627 pixels) is derived from the Large HQ Image. Advertisers have the option to provide an alternate image. The 1.9:1 aspect ratio is highly recommended. The Square Image will be scaled down to various sizes, including 180x180 pixels.

Note

The maximum file size for images is 7MB. For animation: static images only, no animated GIFs.

For Portrait Moments native ads, we recommend using 720 to 1080 pixel high-resolution images. The dimensions for this vertical image are 1080 pixels by 1920 pixels (9:16 aspect ratio). The minimum dimension should be 720 pixels by 1280 pixels.

For Panorama Moments native ads, the image must be 2276 pixels by 1280 pixels or wider (maximum of 6826px by 1280px) high-resolution image. The image aspect ratio must be between 16:9 and 48:9.

Matrix View of Required fields When Serving Different Ad Types¶

For a comprehensive matrix view of all required fields when serving different ad types, refer to Matrix View.

Important

The programmatic 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 Yahoo Native ads.

Ad Fields¶

An ad contains the following fields:

Name

Description

Type

Add

Update

adGroupId

The ID of the ad group associated with the ad.

long

Required

Optional

advertiserId

The ID of the advertiser associated with the ad.

long

Required

Optional

videoScrolling

Optional video scrolling flag to accompany the video url provided for ad. If set to TRUE, the video will utilize mobile swiping for playback in supported native positions.

ENUM

Optional

Optional

styles

A JSON object representing additional ad styles - call to action styling and portrait template container colors when an image, video, or carousel ad gets rendered as a single image upgraded to portrait moments ad.

Possible values are

  • callToActionText, supporting only bgColor (background color) for the call to action button. Valid options are:

    • 000000 (black)

    • FFFFFF (white)

    • B50003 (red)

    • 2D6400 (green)

    • 005194 (blue)

  • container, supporting only bgColorGradientLinear1 and bgColorGradientLinear2 for background gradient color palette.

  • Formats for the color values in the container are: rgb({d},{d},{d}).

    • Each digit must be an integer between 0 and 255.

    • Hex code not including the hashtag (e.g., 99CC00). It must be a valid hex triplet six characters long.

  • container.bgColorGradientLinear1 and container.bgColorGradientLinear2 and their parent styles are all optional. However, if one is provided and the other is left blank, then the blank one should be filled in to have the same value as the provided one.

  • Both colors must maintain a given contrast ratio with either white or black (one or the other - one color maintaining with white and the other maintaining with black is not allowed).

  • Both colors must also maintain a given contrast ratio with callToActionText.bgColor (for now, 2:1, as this will allow all CTA background colors to work against both system gray and system black) - for example, if red is selected as the button color, then the background should not also be some shade of red.

  • Background colors cannot both be white (FFFFFF) - one can be white, but not both.

  • If the background colors result in a generated text color of black and the user has provided a callToActionText.bgColor value of FFFFFF (white), input will get rejected (a white button, which will be a transparent button with a white outline and white text, cannot mix with black ad text). See below this table for a code snippet with an example.

JSON object

Optional

Optional

campaignId

The ID of the campaign associated with the ad.

long

Required

Optional

description

The description of the ad. Maximum limit is 150 characters. Use {city}, {state}, {state_abbr}, {country} and {country_abbr} macros to add geo locations for user personalized ads. Use {time} macro for flash sale ads.

string

Required

Optional

displayUrl

The user-friendly URL displayed to the user. Maximum limit is 35 characters.

string

Required

Optional

id

The ID of the ad.

long

N/A

Required

imageUrl

The URL of the square image for the ad. Should be 627x627 pixels or larger (1:1 ratio). This field is required when creating an image ad or video ad.

string

Optional

Optional

imageUrlHQ

A URL to a 1200 x 627 high-resolution image that will be used in eligible native positions. This field is required for all image and video ads.

string

Optional

Optional

imagePortraitUrl

A URL to a vertical (portrait) 9:16 aspect ratio 720p to 1080p high-resolution image that will be used in eligible mobile moments and portrait native positions.

string

Optional

Optional

imagePortraitUrlBG

A URL to a vertical (portrait) 9:16 aspect ratio 720p to 1080p high-resolution image that will be used as a background image for carousel ads (both native and DPA) to allow them to render in mobile moments and portrait native positions. Recommended to allow your carousel ads to get more supply reach.

string

Optional

Optional

imagePanormaUrl

A URL to a horizontal ultra-wide 16:9 (and up to 48:9) aspect ratio 2276x1280 (maximum of 6826x1280) high-resolution image that will be used in eligible 360 panoramic mobile moments native positions. Note that imagePortraitUrl must also be provided alongside it as a fallback.

string

Optional

Optional

videoPortraitUrl

A URL to a vertical (portrait) 9:16 aspect ratio 720p to 1080p high-resolution video that will be used in eligible mobile moments and portrait video native positions. The technical requirements for video are: Format: .mp4 .m4v or .mov Max File Size: 1GB Min video length: 5sec Max video length: 30sec (for INSTALL_APP or REENGAGE_APP campaigns) or 5min (for PROMOTE_BRAND campaigns) Min video quality: 720p 750kbps. Min audio quality: If the video has audio, then it must have 2 channel stereo 64kbps. Note that imagePortraitUrl must also be provided alongside it as a fallback.

string

Optional

Optional

landingUrl

The landing page URL associated with the ad. The landing page URL is the Web address that a user is sent to after clicking on the ad. Maximum limit is 2048 characters. Use {city}, {state}, {state_abbr}, {country} and {country_abbr} macros to add geo locations for user personalized ads.

In INSTALL_APP campaigns, use this field to input the tracking URL provided by your attribution vendor. Note that the ${PIXEL_ID} and ${PIXEL_CONTEXT} macros need to be included in the tracking URL. Here is an example of a valid landingUrl for an app install ad: https://validlandingurl.com/1234567/${PIXEL_CONTEXT}${PIXEL_ID}. See the app install ad example below for more details on passing in this field.

string

Optional

Optional

mailAssetUrl

A URL to a high-resolution image or a compressed HTML file for a mail sponsored ad. This can only run on VISIT_WEB and CPC price type. Note that the image can only be a 2MB JPEG, PNG or GIF image. A compressed HTML file must be a zip file and the maximum file size is 10MB.

string

Optional

Optional

imageUrlThumbnail

A URL to a high-resolution image for an ad. The original image will be scaled to 180 x 180 pixels and can only be a JPEG or PNG image. Required for ads under MAIL_SPONSORED campaigns.

string

Optional

Optional

sponsoredBy

The string shown against the sponsored by label in the ad. This field is not shown for ads that run on mobile search, but is still a required input when creating any text ad. Maximum limit is 35 characters. For INSTALL_APP OR REENGAGE_APP campaigns, we recommend that you put the app name in this field.

string

Required

Optional

status

The status of the ad. Valid input values are:

  • ACTIVE

  • PAUSED

  • DELETED

  • REJECTED

The status field is reserved for mutable entity state and user transitions. Note that the REJECTED value here is set by the system editorial review. See the diagram below for an illustration of how this works. See also the ad level statuses table below for more details on this field.

enum

Required

Optional

editorialStatus

The editorial status of the ad. Valid values are:

  • NOT_REVIEWED

  • PENDING_REVIEW

  • APPROVED

  • REJECTED

The editorialStatus field is reserved for read-only system editorial review transitions. Note that this field is read-only for Adds (creates) and Updates.

enum

Read-only

Read-only

title

The title for the ad. Maximum limit is 50 characters. Use {city}, {state}, {state_abbr}, {country} and {country_abbr}``macros to add geo locations for user personalized ads. Use ``{time} macro for flash sale ads.

string

Required

Optional

title2

The title for the ad. Maximum limit is 30 characters. When using this attribute title is also limited to 30 characters.

string

Required

Optional

contentUrl

This field applies only to INSTALL_APP campaigns. If you have a Tumblr post you would like to associate with your ad, you can provide a valid post URL using this field. Doing this will make your ad eligible to run on Tumblr.

string

Optional

Optional

videoPrimaryUrl

In INSTALL_APP, REENGAGE_APP or PROMOTE_BRAND campaigns you can provide a url for a video, making your campaign eligible to serve in video-enabled native positions. The technical requirements for video are:

  • Format: .mp4 .m4v or .mov

  • Max File Size: 1GB

  • Min video length: 5sec

  • Max video length: 30sec (for INSTALL_APP or REENGAGE_APP campaigns) or 5min (for PROMOTE_BRAND campaigns)

  • Min video quality: 480p 300kbps. Recommended 500kbps.

  • Min audio quality: If the video has audio, then it must have 2 channel stereo 32kbps. Recommended: 64kbps.

Note that this is required for video ads running as PROMOTE_BRAND, APP_INSTALL or REENGAGE_APP campaigns.

string

Optional

Optional

videoCaptionUrl

Optional video caption file url to accompany the video url provided for video ads. Maximum url length is 1024 characters. The technical requirements for captions are:

  • Format: .vtt or .srt

  • Maximum File Size: 1MB

  • Maximum 3 lines of text per caption time entry/stamp in the file

string

Optional

Optional

videoPreviewStartTime

Optional start time (in seconds) to start the video clip or preview for Mail Trailer Video Ad. Default is 0 sec. The duration of the video clip will always be for 5 sec.

Integer

Optional. Default is 0 sec for all video ads and video trailer ads.

Optional

videoAutoloop

Optional video autoloop flag to accompany the video url provided for ad. If set to TRUE, the video will autoloop continuously.

enum

Optional. Default: FALSE

Optional

impressionTrackingUrls

The impressionTrackingUrls object is used to set third-party view tracking for your ads. Please see below for more information on how to set third-party view tracking. See app install ad example below for more details on passing in this field.

JSON object

Optional

Optional

callToActionText

Call to action buttons used to help drive users to take specific actions. See the call to action section for a list of available values.

enum

Optional

Optional

adName

This is an optional field that allows you to name ads for your internal purposes. This value is not part of the actual creative that is rendered. Character limit is 255.

string

Optional

Optional

assets

A list of JSON objects representing additional ad assets - for example, carousel image cards

array

Optional

Optional

flashSaleConfig

A configuration object containing all the necessary information for configuring a flash sale ad. Fields include:

  • countdownEndDateStr: This is mandatory and should not be in the past. The required format is yyyy/mm/dd HH:mm:ss

  • timezone: This is optional. The default value is the Advertiser’s timezone.

  • countdownPrefixText: This is optional. Valid input values are a set of values provided in the same language as in the current campaign setting. Refer to Data Dictionary.

JSON object

Optional

Optional

rejectionReasons

The list of reasons the ad was editorially rejected due to policy.

array

N/A

N/A

optimizeAssets

Supported only for carousel ads. When specified as TRUE, the best-performing card will be displayed first.

boolean

Optional for carousel card assets.

optional

runAsSingleImage

Supported only for carousel ads. When specified as TRUE, the carousel ad is allowed to run as a single image ad in some supply.

boolean

optional

optional

A styles JSON object representing additional ad styles: a call to action styling and portrait template container colors when an image, video, or carousel ad gets rendered as a single image upgraded to portrait moments ad. An example:

"styles": {
        "callToActionText": {
            "bgColor": "000000"
        },
        "container": {
             "bgColorGradientLinear1": "E5E9ED",
             "bgColorGradientLinear2": "CED3D7"
        },
     }

Entity and Editorial Status¶

The entity and editorial statuses are illustrated in the technical diagram below.

entity status and editorial status

Note

REJECTED editorial status is an end state, while APPROVED status can go back to PENDING_REVIEW if the ad data has changed.

Using the impressionTrackingUrls Object¶

The impressionTrackingUrls object is used to set third-party impression tracking for your ads. Please see below for more information on how to set third-party impression tracking.

"impressionTrackingUrls": {
      "impression": ["https: //www.impression.com"], // maximum 3 comma-separated impression URLs
      "videoQuartile100": ["https: //www.videoQuartile100.com"],
      "installAppClickButton": ["https: //www.installAppClickButton.com"]
  }

impressionTrackingUrls Fields

Field

Description

Required?

impression

Supported third-party impression tracking URLs:

  • Must be an image tag

  • Must be secure (SSL)

  • Cannot include redirect

  • Cannot include macros other than [timestamp]

Up to 3 impression URLs are supported per ad.

No

videoQuartile100

Applies only to INSTALL_APP video ads and tracks when your video was played to 100% of its length. Only one videoQuartile100 URL is supported per ad.

No

installAppClickButton

Applies only to INSTALL_APP video ads and tracks when the install button was clicked. Only one installAppClickButton URL is supported per ad.

No

Important

When an ad is displayed, a Pixel/URL in the impressionTrackingUrl field’s impression are fired. This allows 3rd parties to track when an ad is served and to track post-impression conversions. If you fire your own 3rd party impression pixel, it should line up closely with the impressions column in reporting. Post-impressions conversions are provided as a column in reports, but not in the UI.

v3 Upgraded URL Attributes¶

Important

For the v3 Native Ad Platform API, Upgraded URL (UU) attributes are now supported for the Ad object type.

The following table describes the supported UU attributes per the Ad object type in v3 Native Ad Platform API.

Object

Landing Url

Display Url

Final Url

Mobile Final Url

TrackingUrl

Custom Parameters

Display Url Path1

Display Url Path2

Ad

dp

dp

yes

yes

yes

yes

yes

yes

Note

dp stands for deprecated in the above table.

Note

The landing page url is deprecated only for search. The Final url will be eligible in a native context. Native-only ads are not required to use the final URL and may continue to use the landing page url.

For more information on Upgraded URLs in v3, refer to Upgraded URLs.

Ad level statuses¶

Any new ad undergoes automatic quality review. If no issues are raised, the ad can start running less than a minute after its creation. An ad can be in one of the following statuses:

Status

Description

ACTIVE

The ad is running.

PAUSED

The ad is paused and can be re-activated.

REJECTED

The ad was declined due to policy violations. Further information is available in the Ad Manager UI.

DELETED

Set the status of the ad to DELETED in order to delete the ad; once this is done, the ad is removed from the system and cannot be reactivated.

Endpoint¶

Resource URI

https://api.gemini.yahoo.com/v3/rest/ad/

Example Representations¶

Ad

{
  "id": 320323,
  "description": "this is the ad description",
  "adGroupId": 46758,
  "status": "ACTIVE",
  "title": "this is a test ad",
  "advertiserId": 87292,
  "landingUrl": "http://www.yahoo.com",
  "imageUrl": "http://image.jpg",
  "sponsoredBy": "Sandboxes Inc",
  "campaignId": 31369,
  "displayUrl": "http://www.yahoo.com",
  "imageUrlHQ": null,
  "contentUrl": null,
  "callToActionText": null,
  "videoPrimaryUrl": null,
  "adName": null,
  "impressionTrackingUrls": {
         "impression": null
      }
}

Ad Array

[
  {
      "id": 320324,
      "description": "this is the ad description",
      "adGroupId": 46758,
      "status": "ACTIVE",
      "title": "batch call ad 1",
      "advertiserId": 87292,
      "landingUrl": "http://www.yahoo.com",
      "imageUrl": "http://image1.jpg",
      "sponsoredBy": "Sandboxes Inc",
      "campaignId": 31369,
      "displayUrl": "http://www.yahoo.com",
      "imageUrlHQ": null,
      "contentUrl": null,
      "callToActionText": null,
      "videoPrimaryUrl": null,
      "adName": null,
      "impressionTrackingUrls": {
                 "impression": null
              }
  },
  {
      "id": 320325,
      "description": "ad description",
      "adGroupId": 46758,
      "status": "ACTIVE",
      "title": "batch call ad 2",
      "advertiserId": 87292,
      "landingUrl": "http://www.yahoo.com",
      "imageUrl": "http://image2.jpg",
      "sponsoredBy": "Sandboxes Inc",
      "campaignId": 31369,
      "displayUrl": "http://www.yahoo.com",
      "imageUrlHQ": null,
      "contentUrl": null,
      "callToActionText": null,
      "videoPrimaryUrl": null,
      "adName": null,
      "impressionTrackingUrls": {
                 "impression": null
              }
  }
]

Ad Response

{
  "errors": null,
  "response": {
      "id": 320323,
      "description": "this is the ad description",
      "adGroupId": 46758,
      "status": "ACTIVE",
      "title": "this is a test ad",
      "advertiserId": 87292,
      "landingUrl": "http://www.yahoo.com",
      "imageUrl": "http://image.jpg",
      "sponsoredBy": "Sandboxes Inc",
      "campaignId": 31369,
      "displayUrl": "http://www.yahoo.com",
      "imageUrlHQ": null,
      "contentUrl": null,
      "callToActionText": null,
      "videoPrimaryUrl": null,
      "adName": null,
      "impressionTrackingUrls": {
                 "impression": null
              }
  }
}

Example Representation of UU¶

The following is a JSON snippet of UU attributes that resides in an Ad object:

{

...

    "finalUrl": "https://www.mywebsite.com/c/10366",
    "mobileFinalUrl": "https://m.mywebsite.com/c/10366",
    "trackingUrl": "{lpurl}?source=YAHOO&kw={keyword}&mt={matchtype}&camp={campaignid}&p1={_param1}&p2={_param2}&p3={_param3}",
    "customParameters": [
         {
                 "key": "param1",
                 "value": "abc"
         },
         {
                 "key": "param2",
                 "value": "xyz"
         }
    ],
    "displayUrlPath1": "promo",
    "displayUrlPath2": null,
...

}

Important - For Advertisers Making GET Requests¶

Note the following, as described in the section below on Operations: when making GET requests only one adGroupId or advertiserId parameter is allowed to be passed in as a query parameter for all filtered list GET calls.

It is essential that when making GET requests, you explicitly pass in the advertiserId parameter. If you don’t strictly follow this recommendation, you’ll experience performance degradation based on the number of accounts associated with the advertiser.

This recommendation applies not only to “/ad…” endpoints but also to other endpoints as well. API partners need to make these changes, which will be enforced on the Native Ad Platform backend in an effort to ensure optimal performance of each advertiser account.

For resellers, any GET call needs to explicitly have the advertiserId passed.

Note that GET calls that use id(s) can remain as is.

For example:

GET https://api.gemini.yahoo.com:4080/mb_be/rest/ad/?id=818231&id=39823718

However, GET calls that do not pass id(s) should always be accompanied with the advertiserId parameter.

For example:

GET https://api.gemini.yahoo.com:4080/mb_be/rest/ad/?si=0&mr=500&exstatus=DELETED&exstatus=REJECT_INTERNAL&exstatus=MATCHED&exstatus=PROSPECT&exstatus=PROPOSAL&advertiserId=531231

Operations¶

Method: To retrieve data for a specific ad, make a GET call with the id parameter.

For example:

https://api.gemini.yahoo.com/v3/rest/ad/320325

Response: The ad associated with the given id:

{
  "errors": null,
  "response": {
      "id": 320325,
      "description": "updated description",
      "adGroupId": 46758,
      "status": "ACTIVE",
      "campaignId": 31369,
      "advertiserId": 87292,
      "title": "batch call ad 2",
      "landingUrl": "http://www.yahoo.com",
      "imageUrl": "http://image.jpg",
      "sponsoredBy": "Sandboxes Inc",
      "displayUrl": "http://www.yahoo.com",
      "imageUrlHQ": null,
      "contentUrl": null,
      "callToActionText": null,
      "videoPrimaryUrl": null,
      "adName": null,
      "impressionTrackingUrls": {
                 "impression": null
              }
  }
}

Example: GET call with multiple IDs. Please note that when you pass multiple IDs, all other filters besides id will be ignored:

https://api.gemin.yahoo.com/v3/rest/ad/?id=322113&id=322114

Response: The ads associated with the given IDs:

{
  "errors": null,
  "response": [
      {
          "id": 322113,
          "description": "this is the ad description",
          "adGroupId": 46758,
          "status": "ACTIVE",
          "advertiserId": 87292,
          "title": "Ad1",
          "landingUrl": "http://www.yahoo.com",
          "imageUrl": null,
          "campaignId": 31369,
          "sponsoredBy": "Sponsorships Inc",
          "displayUrl": "http://www.yahoo.com",
              "imageUrlHQ": null,
              "contentUrl": null,
              "callToActionText": null,
              "videoPrimaryUrl": null,
              "adName": null,
              "impressionTrackingUrls": {
                         "impression": null
                      }
      },
      {
          "id": 322114,
          "description": "this is the ad description",
          "adGroupId": 46758,
          "status": "ACTIVE",
          "advertiserId": 87292,
          "title": "Ad2",
          "landingUrl": "http://www.yahoo.com",
          "imageUrl": null,
          "campaignId": 31369,
          "sponsoredBy": "Sponsorships Inc",
          "displayUrl": "http://www.yahoo.com",
              "imageUrlHQ": null,
              "contentUrl": null,
              "callToActionText": null,
              "videoPrimaryUrl": null,
              "adName": null,
              "impressionTrackingUrls": {
                         "impression": null
                      }
      }
   ]
}

Read data for filtered list of ads

Method: To retrieve data for a filtered list of ads, make a GET call with the following parameters:

Name

Description

Type

mr

The maximum number of rows to retrieve.

int

si

The start index or the first element to retrieve.

int

adGroupId

The ID of the ad group to filter the ads by.

long

status

The ad status to filter the ads by.

enum

advertiserId

The ID of the advertiser associated with the ad.

long


Important

advertiserId parameter is a required query parameter for all filtered list GET calls.

Example: Make a GET call for a filtered list of ads:

https://api.gemini.yahoo.com/v3/rest/ad/?adGroupId=46758&advertiserid=82829

Response: The list of ads that match the given filter:

{
  "errors": null,
  "response": [
      {
          "id": 320324,
          "description": "this is the ad description",
          "adGroupId": 46758,
          "status": "PAUSED",
          "campaignId": 31369,
          "advertiserId": 87292,
          "title": "ad 1",
          "landingUrl": "http://www.yahoo.com",
          "imageUrl": "http://image1.jpg",
          "sponsoredBy": "Sandboxes Inc",
          "displayUrl": "http://www.yahoo.com",
              "imageUrlHQ": null,
              "contentUrl": null,
              "callToActionText": null,
              "videoPrimaryUrl": null,
              "adName": null,
              "impressionTrackingUrls": {
                         "impression": null
                      }
      },
      {
          "id": 320325,
          "description": "updated description",
          "adGroupId": 46758,
          "status": "ACTIVE",
          "campaignId": 31369,
          "advertiserId": 87292,
          "title": "ad 2",
          "landingUrl": "http://www.yahoo.com",
          "imageUrl": "http://image2.jpg",
          "sponsoredBy": "Sandboxes Inc",
          "displayUrl": "http://www.yahoo.com",
          "imageUrlHQ": null,
          "contentUrl": null,
          "callToActionText": null,
              "videoPrimaryUrl": null,
              "adName": null,
              "impressionTrackingUrls": {
                         "impression": null
                      }
      }
   ]
}

Example: GET call and filter by multiple ad group IDs:

https://api.gemini.yahoo.com/v3/rest/ad/?adGroupId=1&adGroupId=2&advertiserid=82829

Important

advertiserId parameter is a required query parameter for all filtered list GET calls.

Response: The list of ads that match the given filter:

{
  "errors": null,
  "response": [
      {
          "id": 27926746046,
          "description": "This is the ad description",
          "status": "ACTIVE",
          "advertiserId": 31,
          "campaignId": 31,
          "adGroupId": 1,
          "title": "test1",
          "sponsoredBy": "Sponsorship",
          "imageUrl": null,
          "landingUrl": "http://www.yahoo.com",
          "displayUrl": "http://www.yahoo.com",
          "imageUrlHQ": null,
          "contentUrl": null,
          "callToActionText": null,
              "videoPrimaryUrl": null,
              "adName": null,
              "impressionTrackingUrls": {
                         "impression": null
                      }
      },
      {
          "id": 28040349288,
          "description": "An offer you can't refuse",
          "status": "ACTIVE",
          "advertiserId": 31,
          "campaignId": 31,
          "adGroupId": 2,
          "title": "The godfather of all ads",
          "sponsoredBy": "sponsorship",
          "imageUrl": null,
          "landingUrl": "http://landing.html",
          "displayUrl": "http://www.yahoo.com",
          "imageUrlHQ": null,
          "contentUrl": null,
          "callToActionText": null,
              "videoPrimaryUrl": null,
              "adName": null,
              "impressionTrackingUrls": {
                         "impression": null
                      }
      }
  ]
}

Update existing ads

Method: To update existing ads, make a PUT call to the ad endpoint with one or more ad objects. Specify the fields to update; please note that id is the only required parameter, all other fields are optional. The response will be the list of updated ads. Partial update is supported; fields that are either not passed or passed as null will be ignored for the update.

For example, in order to update the description for an existing ad:

PUT https://api.gemini.yahoo.com/v3/rest/ad/

Data passed

{
 "id": 320325,
 "description": "updated description"
}

Example response

{
  "errors": null,
  "response": {
      "id": 320325,
      "description": "updated description",
      "adGroupId": 46758,
      "status": "ACTIVE",
      "title": "ad 2",
      "advertiserId": 87292,
      "landingUrl": "http://www.yahoo.com",
      "imageUrl": "image.jpg",
      "sponsoredBy": "Sandboxes Inc",
      "campaignId": 31369,
      "displayUrl": "http://www.yahoo.com",
      "imageUrlHQ": null,
      "contentUrl": null,
      "callToActionText": null,
      "videoPrimaryUrl": null,
      "adName": null,
      "impressionTrackingUrls": {
                 "impression": null
              }
  }
}

Create a new ad

Method: To create a new ad, make a POST call with the Ad object. The response will be the newly created ad. Batch create is supported; either an ad or an ad array can be passed. Here is an example:

POST https://api.gemini.yahoo.com/v3/rest/ad/

Data passed

[
   {
       "title": "batch call ad 1",
       "landingUrl": "http://www.yahoo.com",
       "imageUrl": "http://image1.jpg",
       "displayUrl": "http://www.yahoo.com",
       "sponsoredBy": "Sandboxes Inc",
       "adGroupId": 46758,
       "campaignId": 31369,
       "advertiserId": 87292,
       "description": "this is the ad description",
       "status": "ACTIVE",
       "imageUrlHQ": null,
       "contentUrl": null

   },
   {
       "title": "batch call ad 2",
       "landingUrl": "http://www.yahoo.com",
       "imageUrl": "http://image2.jpg",
       "displayUrl": "http://www.yahoo.com",
       "sponsoredBy": "Sandboxes Inc",
       "adGroupId": 46758,
       "campaignId": 31369,
       "advertiserId": 87292,
       "description": "this is the ad description",
       "status": "ACTIVE",
       "imageUrlHQ": null,
       "contentUrl": null
    }
 ]

Example response

{
  "errors": null,
  "response": [
      {
          "id": 320324,
          "description": "this is the ad description",
          "adGroupId": 46758,
          "status": "ACTIVE",
          "title": "batch call ad 1",
          "advertiserId": 87292,
          "landingUrl": "http://www.yahoo.com",
          "imageUrl": "http://image1.jpg",
          "sponsoredBy": "Sandboxes Inc",
          "campaignId": 31369,
          "displayUrl": "http://www.yahoo.com",
          "imageUrlHQ": null,
          "contentUrl": null,
          "callToActionText": null,
          "videoPrimaryUrl": null,
          "adName": null,
          "impressionTrackingUrls": {
                         "impression": null
                      }
      },
      {
          "id": 320325,
          "description": "this is the ad description",
          "adGroupId": 46758,
          "status": "ACTIVE",
          "title": "batch call ad 2",
          "advertiserId": 87292,
          "landingUrl": "http://www.yahoo.com",
          "imageUrl": "http://image2.jpg",
          "sponsoredBy": "Sandboxes Inc",
          "campaignId": 31369,
          "displayUrl": "http://www.yahoo.com",
          "imageUrlHQ": null,
          "contentUrl": null,
          "callToActionText": null,
          "videoPrimaryUrl": null,
          "adName": null,
          "impressionTrackingUrls": {
                         "impression": null
                      }
       }
    ]
 }

Create an app install video ad

Method: To create an app install video ad, make a POST call with a video asset:

POST https://api.gemini.yahoo.com/v3/rest/ad/

Data passed

{
 "title": "Video App Install ad",
 "description": "Amazing strategy game",
 "sponsoredBy": "yahoo",
 "displayUrl": "yahoo.com",
 "status": "ON",
 "landingUrl": "https://landingurl.com/serve?action=click&publisher_id=44&ref_id=${PIXEL_CONTEXT}&ref2_id=${PIXEL_CONTEXT}&ref2_id=${PIXEL_ID}",
 "advertiserId": 976108,
 "campaignId": 339898299,
 "adGroupId": 7902039296,
 "imageUrl": "http://image.png",
 "imageUrlHQ": "http://imagehq.png",
 "callToActionText": "Download",
 "videoPrimaryUrl": "https://video.mp4",
 "impressionTrackingUrls": {
     "impression": [
         "https://www.impression.com"
     ],
     "videoQuartile100": [
         "http://www.videoQuartile100.com"
     ],
     "installAppClickButton": [
         "https://www.installAppClickButton.com"
     ]
   }
}

Example response

{
  "errors": null,
  "response": {
      "description": "Amazing strategy game",
      "imageUrlHQ": "http://l.yimg.com/imagehq.png",
      "status": "ACTIVE",
      "id": 30258267267,
      "title": "Video App Install ad",
      "sponsoredBy": "yahoo",
      "landingUrl": "https://landingurl.com/serve?action=click&publisher_id=44&ref_id=${PIXEL_CONTEXT}&ref2_id=${PIXEL_CONTEXT}&ref2_id=${PIXEL_ID}",
      "advertiserId": 976108,
      "displayUrl": "yahoo.com",
      "imageUrl": "http://l.yimg.com/imageurl.png",
      "contentUrl": null,
      "callToActionText": "Download",
      "campaignId": 339898299,
      "adGroupId": 7902039296,
      "adName": null,
      "impressionTrackingUrls": {
          "impression": [
              "https://www.impression.com"
          ],
          "videoQuartile100": [
              "http://www.videoQuartile100.com"
          ],
          "installAppClickButton": [
              "https://www.installAppClickButton.com"
          ]
      },
      "videoPrimaryUrl": "https://video.mp4"
    }
}

Delete an ad

Method: To delete an ad, make a PUT call with the Ad object. Batch delete is supported; either an ad or an ad array can be passed. The following parameters are required:

Field

Description

id

The ID of the ad to delete.

status

The status of the ad set to DELETED to delete the ad.


Note

In v2, the DELETE operation is supported for both single and multiple ids.

For example:

PUT https://api.gemini.yahoo.com/v3/rest/ad/
DELETE https://api.gemini.yahoo.com/v3/rest/ad/{id}
DELETE https://api.gemini.yahoo.com/v3/rest/ad?id=123&id=1234&...

Data passed

{
  "id": 320323,
  "status": "DELETED"
}

Example response

{
  "errors": null,
  "response": {
      "id": 320323,
      "description": "updated description",
      "status": "DELETED",
      "advertiserId": 87292,
      "title": "ad 2",
      "campaignId": 31369,
      "landingUrl": "http://www.yahoo.com",
      "imageUrl": "http://image.jpg",
      "sponsoredBy": "Sandboxes Inc",
      "displayUrl": "http://www.yahoo.com",
      "imageUrlHQ": null,
      "contentUrl": null,
      "callToActionText": "null",
      "videoPrimaryUrl": null,
      "adName": null,
      "impressionTrackingUrls": {
                 "impression": null
              }
  }
}

Preview an ad

You can fetch a preview of either an existing ad or of a new ad that has not yet been created using the preview service. The service outputs either a raw HTML source file or an iFrame with previews of the ad in different placements.

To preview an existing ad, make a GET call passing in the following parameters:

Name

Description

Type

adid

Required. The id of the ad to be previewed.

long

displayType

Optional. Either handheld, tablet, or screen. Defaults to handheld.

enum

responseType

Optional. Either html or iframe. Defaults to iframe.

enum

Here is a sample GET call:

https://api.gemini.yahoo.com/v3/rest/preview/?adId=3131&displayType=handheld&responseType=iframe

You can also get a preview for an ad that has not yet been created in Native & Search, by making a POST call passing in the ad spec and some campaign info in the request body.

Here is an example for previewing a native ad under a VISIT_WEB campaign.

POST https://api.gemini.yahoo.com/v3/rest/preview

Data passed

{
  "settings": {
      "displayType": "screen"
  },
  "ad": {
      "description": "Your ad description",
      "displayUrl": "www.displayurl.com",
      "imageUrlHQ": "http://highresimage.jpg",
      "adGroupId": 7120485005,
      "title": "Your ad title",
      "sponsoredBy": "Your company Name",
      "imageUrl": "http://imageurl.png",
      "landingUrl": "http://www.destinationurl.com"
  },
  "campaign": {
      "objective": "VISIT_WEB",
      "language": "en"
  }
}

Example response

Ad preview HTML

Here is an example for previewing a native video ad under a INSTALL_APP campaign:

POST https://api.gemini.yahoo.com/v3/rest/preview

Data passed

{
  "settings": {
      "displayType": "handheld",
      "responseType": "iframe"
  },
  "ad": {
      "description": "Your ad description",
      "imageUrlHQ": "highresimage.jpg",
      "adFormat": "VIDEO",
      "displayUrl": "www.displayurl.com",
      "title": "Your app install video ad",
      "sponsoredBy": "Company Name",
      "imageUrl": "http://image.jpeg",
      "landingUrl": "http://www.destinationurl.com"
  },
  "campaign": {
      "language": "en",
      "isNativeChannel": true,
      "objective": "INSTALL_APP",
      "isSearchChannel": false
  }
}

Example response

An iframe tag.

Create a flash sale ad

Method: To create a flash sale ad, make a POST call with the Ad object. The response will be the newly created flash sale ad.

POST https://api.gemini.yahoo.com/v3/rest/ad/

Example request

{
      "title": "Sale ends in {time}",
      "description": "Store sale ends in {time}",
      "flashSaleConfig": {
              "countdownEndDateStr": "2020/01/01 12:00:00",
              "timezone": "Europe/Dublin",
              "countdownPrefixText”: “Ends in"
      },
      ….
}

Example response

{
      "title": "Sale ends in {time}",
      "description": "Store sale ends in {time}",
      "status": "ACTIVE",
      "id": 27712589018,
      "flashSaleConfig": {
              "timezone": "Europe/Dublin",
              "countdownEndDateStr": "3020/01/01 12:00:00",
              "countdownPrefixText”: “Ends in”
      }
          ...
}

Pass in the following parameters:

Name

Description

Type

countdownEndDateStr

Required. Should not be in the past.

string

timezone

Optional. The default value is the Advertiser’s time zone.

string

countdownPrefixText

Optional. Valid values can be found in the data dictionary API.

string

Delete a flash sale ad

Method: To delete a flash sale ad, make a PUT call with the Ad object. The response will be the deleted flash sale ad.

PUT https://api.gemini.yahoo.com/v3/rest/ad/

Example request

{
      "id": 27712589020,
      "title": "Sale ends",
      "description": "Store sale ends",
      "status": "ACTIVE",
      "flashSaleConfig": {
              "countdownEndDateStr": "",
              "timezone": null,
              "countdownPrefixText": ""
      }
}

Example response

{
  "title": "Sale ends",
      "description": "Store sale ends",
      "status": "ACTIVE",
      "id": 27712589020,
      "flashSaleConfig": null
    ...
}

Erasing a flash sale configuration for a flash sale ad

Method: To erase a flash sale configuration, make a PUT call with the Ad object. Batch delete is supported; either an ad or an ad array can be passed. The following parameters are required:

Field

Description

id

The ID of the flash sale ad to erase.

status

The status of the flash sale ad set to DELETED to erase the ad.


Note

In v2, the DELETE operation is supported for both single and multiple ids.

For example:

PUT https://api.gemini.yahoo.com/v3/rest/ad/
DELETE https://api.gemini.yahoo.com/v3/rest/ad/{id}
DELETE https://api.gemini.yahoo.com/v3/rest/ad?id=123&id=1234&...

Data passed

{
  "id": 320323,
  "status": "DELETED"
}

Example response

{
  "errors": null,
  "response": {
      "id": 320323,
      "description": "updated description",
      "status": "DELETED",
      "advertiserId": 87292,
      "title": "ad 2",
      "campaignId": 31369,
      "landingUrl": "http://www.yahoo.com",
      "imageUrl": "http://image.jpg",
      "sponsoredBy": "Sandboxes Inc",
      "displayUrl": "http://www.yahoo.com",
      "imageUrlHQ": null,
      "contentUrl": null,
      "callToActionText": "null",
      "videoPrimaryUrl": null,
      "adName": null,
      "impressionTrackingUrls": {
                 "impression": null
              }
  }
}

View the editorial reasons for a rejected ad

Method: To view the reasons for a rejected ad, make a GET call with the Ad object. This is only for ad rejections for native in the v3 Native Ad Platform API. The following parameters are required:

Field

Description

id

The ID of the rejected ad.

status

The status of the rejected ad set to REJECTED to get the editorial reasons for the rejected the ad.

Data passed

{
  "id": 320323,
  "status": "REJECTED"
}

Example response

{
  "errors": null,
  "response": {
      "id": 320323,
      "description": "this is the ad description",
      "adGroupId": 46758,
      "status": "REJECTED",
      "rejectionReasons": ["Ad Copy Language and Style", "Misleading or Irrelevant", ...],
      "title": "this is a test ad",
      "advertiserId": 87292,
      ...
      "landingUrl": "http://www.yahoo.com"
  }
}

Ad Asset Fields¶

You can create and manage additional ad assets, using these fields. The following fields are available for creating and managing ad assets:

Name

Description

Type

Add

Update

id

The ID of the ad asset.

long

N/A

required

title

Title text used for the ad asset. Maximum limit is 50 characters. Use {city}, {state}, {state_abbr}, {country} and {country_abbr} macros to add geo locations for user personalized ads. Use {time} macro for flash sale ads.

string

Required for carousel card assets. Ignored for other assets types.

optional

description

Description text displayed when your ad asset appears in content streams or in the other eligible native ad positions. Maximum 150 characters. Use {city}, {state}, {state_abbr}, {country} and {country_abbr} macros to add geo locations for user personalized ads. Use {time} macro for flash sale ads.

string

Required for carousel card assets. Ignored for other assets types.

optional

name

Name for the asset used for reporting purposes only, not for ad rendering.

string

Optional for touchpoint assets. Ignored for other asset types.

Optional

assetUrl

For an image tile asset, a valid image URL. Minimum size is 200x200. Maximum size is 2MB. For a video tile asset, a valid video URL.

  • Format: .mp4, .mp4v or .mov

  • Max File Size: 1GB

  • Min video length: 5sec

  • Max video length: 5min

  • Min video quality: 480p 500kbps.

  • Min audio quality: If the video has audio, then it must have 2 channel stereo 64kbps.

For text tile asset, a valid HTML URL. Maximum number of embedded links (hrefs) in the HTML is 3. Whitelisted HTML tags:

  • <a>

  • <br>

  • <div>

  • <p>

  • <section>

  • <span>

  • <strong>

  • <b>

  • <i>

  • <button>

Whitelisted CSS attributes
  • color

  • background-color

  • padding

  • padding-bottom

  • padding-left

  • padding-right

  • padding-top

  • text-align

  • font-family

  • font-size

  • font-style

  • font-weight

  • text-decoration

  • outline

  • outline-color

  • line-height

For button tile asset, a valid HTML URL. No embedded links (hrefs) are allowed. Whitelisted HTML tags:

  • <a>

  • <br>

  • <div>

  • <em>

  • <p>

  • <section>

  • <span>

  • <strong>

  • <b>

  • <i>

Whitelisted CSS attributes
  • color

  • background-color

  • padding

  • padding-bottom

  • padding-left

  • padding-right

  • padding-top

  • text-align

  • font-family

  • font-size

  • font-style

  • font-weight

  • text-decoration

  • outline

  • outline-color

  • line-height

string

Required for tile assets. Ignored for other asset types.

optional

imageUrl

For a carousel card asset, a valid URL for a square image that will be displayed when your ad appears in content streams or in the other eligible native ad positions. The ideal image size is 627x627. The maximum size is 7MB. For a touchpoint asset, a valid URL for a modal image that will be displayed when a touchpoint asset is clicked for this popup image to appear. The ideal image size must have an aspect ratio between 3:4 and 1:1. Minimum width is 612px (which means the height must be between 612px and 816px for an image with 612px width). Maximum width is 1500px (which means the height must be between 1500px and 2000px). The effective minimum dimensions are therefore 612x612 and maximum dimensions are 1500x2000. The maximum size is 7MB.

string

Required for carousel card assets. Ignored for tile assets. Optional for touchpoint assets.

optional

imageUrlHQ

For a carousel card asset, a valid URL to a high resolution image that will be used. The ideal image size is 1200x627; smaller images will not be accepted. Larger images with either the same aspect ratio or with a height and width that are off the ideal dimensions by up to a combined 10% will be accepted as well as will be automatically cropped at the center. The maximum file size is 7MB.

string

Required for carousel card assets. Ignored for other assets types.

optional

videoPrimaryUrl

For carousel card asset, a valid video URL:

  • Format: .mp4, .m4v or .mov

  • Max File Size: 1GB

  • Min video length: 5sec

  • Max video length: 30sec (for App Install) or 5min otherwise)

  • Min video quality: 480p 500kbps.

  • Min audio quality: If the video has audio, then it must have 2 channel stereo 64kbps.

string

Optional for carousel card assets. Ignored for other assets types.

Optional

videoCaptionUrl

Optional video caption file url to accompany the video url provided for carousel or video tile assets. Maximum url length is 1024 characters. The technical requirements for captions are:

  • Format: .vtt or .srt

  • Maximum File Size: 1MB

  • Maximum 3 lines of text per caption time entry/stamp in the file

string

Applicable for carousel card or video tile assets. Ignored for other assets types.

optional

videoAutoloop

Optional video autoloop flag to accompany the video url provided for carousel or video tile assets. If set to TRUE, the video will autoloop continuously.

enum

Optional. Default: FALSE. Applicable for carousel card or video tile assets. Ignored for other asset types.

Optional

status

The status of the ad asset. Valid values are:

  • ACTIVE
    • DELETED

Ad assets are defaulted to ACTIVE if no status is provided upon creation. DELETED is used to remove assets.

enum

optional

optional

callToActionText

Call to action buttons used to help drive users to take specific actions. The supported call-to-action text values are same as ones defined for ads: Refer to Call to action text values

enum

Optional for carousel card assets. Not applicable for other asset types.

optional

type

The type of ad asset. Valid values are:

Carousel card ads:

  • MULTI_IMAGE

Title ads:

  • TILES_IMAGE

  • TILES_VIDEO

  • TILES_TEXT

  • TILES_BUTTON

Touchpoint ads:

  • TOUCHPOINT_PORTRAIT

  • TOUCHEPOINT_PANORAMA

enum

required

optional

templateType

The template type of an ad asset. Valid values are:

  • DEFAULT

  • TAG_LIGHT

  • TAG_DARK

  • PLUS_LIGHT

  • PLUS_DARK

  • DOT_LIGHT

  • DOT_DARK

enum

Optional for touchpoint assets. Selected option results in the icon used for the touchpoint. Ignored for other asset types

optional

index

Horizontal index ordering of assets. For carousel card assets (type=MULTI_IMAGE), the values must be unique for every active asset and must be between 0 and 4. Minimum 3 total assets are required for carousel ad. For tile assets the pair of horizontal index and vertical index values must be unique for every active asset. Horizontal index must be between 0 and 4. Minimum 3 assets are required for horizontal tiles. 3-5 image or video tiles grouped with the same horizontal index are considered one carousel grouped tile. No more than 3 carousel grouped tiles per tiles ad. Only image and video tiles are allowed for carousel group.

integer

Required for carousel card assets and tile assets. Ignored for touchpoint assets.

optional

verticalIndex

Vertical index ordering of assets. Not applicable for carousel assets. For tile assets the pair of horizontal index and vertical index values must be unique for every active asset. Vertical index must be between 0 and 19. Minimum 1 asset is required for vertical tiles. Maximum 20 total tiles.

integer

Required for tile assets. Ignored for other asset types.

optional

landingUrl

The landing URL associated with the asset. The landing URL is the web address that a user is sent to after clicking on the ad. Maximum limit is 2048 characters. The landing URL should include the tracking params provided by the tracking partner that was specified at the campaign level for app installs. Use {city}, {state}, {state_abbr}, {country} and {country_abbr} macros to add geo locations for user personalized carousel ads.

string

Required for carousel card assets and touchpoint assets. Optional for image and video tile assets. Not applicable for text tiles.

optional

fixedPosition

The position of the tile asset. Supported for button tile asset only. Values are:
  • NONE

  • BOTTOM (snap globally to bottom. Only one button asset can have this setting for entire tiles ad.)

enum

Optional. Default: NONE. Applicable for button tiles only.

optional

fitToHeight

Whether to fit the image tile asset to height (true) or width (false).

boolean

Optional. Default: FALSE (i.e., fit to width). Applicable for image tile only.

optional

styles

Ad asset styles stored as key-value pair JSON.

Possible values are:

  • x (x-coordinate)

  • y (y-coordinate)

  • w (width)

  • h (height)

    Validations:

  • x, y are required.

  • x, y, w, h must all fit within the background image.

  • w and h are optional, but if w is provided, then h must be as well (and vice versa). Default w and h are 48px.
    • Touchpoints cannot overlap. So a 10x10 touchpoint at (15, 15) cannot co-exist with a 10x10 touchpoint at (24, 13).

  • Touchpoints also need to be a minimum distance from the edges. - 130px from left/right - 0px from bottom - 107px from top

boolean

Optional. Default: FALSE (i.e., fit to width). Applicable for image tile only.

optional

"styles": {
            "x": "40",
            "y": "100",
            "w": "75",
            "h": "75"
        }

Example Carousel Asset Object¶

    {
             "assets": [
                     {
                             "id": 411,
                             "type": "MULTI_IMAGE",
                             "status": "ACTIVE",
                             "index": 0,
                             "title": "title0",
                             "description": "description0,
                             "landingUrl": "https://www.verizonmedia.com",
                             "imageUrl": "https://myimage.jpg",
                             "imageUrlHQ": "https://www.verizonmedia.com"
                     },
                     {
                             "id": 412,
                             "type": "MULTI_IMAGE",
                             "status": "ACTIVE",
                             "index": 1,
                             "title": "title1",
                             "description": "description1",
                             "landingUrl": "https://www.verizonmedia.com",
                             "imageUrl": "https://myimage.jpg",
                             "imageUrlHQ": "https://myhqimage.jpg"
                     },
                     {
                             "id": 413,
                             "type": "MULTI_IMAGE",
                             "status": "ACTIVE",
                             "index": 2,
                             "title": "title2",
                             "description": "description2",
                             "landingUrl": "https://www.verizonmedia.com",
                             "imageUrl": "http://myimage.jpg",
                             "imageUrlHQ": "http://myhqimage.jpg"
                     },
                     {
                             "id": 414,
                             "type": "MULTI_IMAGE",
                             "status": "ACTIVE",
                             "index": 3,
                             "title": "title3",
                             "description": "description3",
                             "landingUrl": "https://www.verizonmedia.com",
                             "imageUrl": "http://myimage.jpg",
                             "imageUrlHQ": "http://myhqimage.jpg"
                     }
             ],
             "optimizeAssets": TRUE,

     }
}

Example Carousel with Portrait Background Image¶

...
“imageUrl”:  null,
“imageUrlHQ”:  null,
“imageUrlThumbnail”:  null,
“imagePortraitUrl”:  null,
“imagePortraitUrlBG” : "https://s.yimg.com/av/ads/1539886327922-6353.jpg",
“videoPrimaryUrl”: null,
“videoPortraitUrl”: null,
“runAsSingleImage”: “FALSE”,
...
"assets" : [

{
"id" : 88861982,
"type" : MULTI_IMAGE,
"status" : ACTIVE,
"index" : 1,
"title" : We Ranked Them: The Best Car Movies Ever Made,
"description" : Wait until you see number 1!,
"callToActionText" : ,
"landingUrl" : https:\/\/yeahmotor.com\/cars\/greatest-car-movies\/?version=X1&utm_source=YHYM movies desk 1023 b&utm_medium=yahoo&utm_campaign=YHYM movies desk 1023 b,
"videoCaptionUrl" : ,
"imageUrl" : https:\/\/s.yimg.com\/av\/ads\/1540307655171-7728.jpg,
"imageUrlHQ" : https:\/\/s.yimg.com\/av\/ads\/1540307654939-2033.jpg
},
{
"id" : 88861984,
"type" : MULTI_IMAGE,
"status" : ACTIVE,
"index" : 0,
"title" : We Ranked Them: The Best Car Movies Ever Made,
"description" : Wait until you see number 1!,
"callToActionText" : ,
"landingUrl" : https:\/\/yeahmotor.com\/cars\/greatest-car-movies\/?version=X1&utm_source=YHYM movies desk 1023 b&utm_medium=yahoo&utm_campaign=YHYM movies desk 1023 b,
"videoCaptionUrl" : ,
"imageUrl" : https:\/\/s.yimg.com\/av\/ads\/1540307820427-9357.jpg,
"imageUrlHQ" : https:\/\/s.yimg.com\/av\/ads\/1540307814224-2533.jpg
}
]

Example Portrait Image Ad¶

...
“imageUrl”:  null,
“imageUrlHQ”:  null,
“imageUrlThumbnail”:  null,
“imagePortraitUrlBG”:  null,
“imagePortraitUrl” : "https://s.yimg.com/av/ads/1539886327922-6353.jpg",
“videoPrimaryUrl”: null,
“videoPortraitUrl”: http://www.video.portrait.com,
“runAsSingleImage”: “FALSE”,
...

Example Portrait Video Ad¶

...
“imageUrl”:  null,
“imageUrlHQ”:  null,
“imageUrlThumbnail”:  null,
“imagePortraitUrlBG”:  null,
“imagePortraitUrl” : "https://s.yimg.com/av/ads/1539886327922-6353.jpg",
“videoPrimaryUrl”: null,
“videoPortraitUrl”: http://www.video.portrait.com,
“videoCaptionUrl”: http://www.video.caption.com,
“videoAutoloop”: “FALSE”,
...

Example Panorama Ad¶

...
“imageUrl”:  null,
“imageUrlHQ”:  null,
“imageUrlThumbnail”:  null,
“imagePortraitUrlBG”:  null,
“imagePortraitUrl” : "https://s.yimg.com/av/ads/1539886327922-6353.jpg",
“imagePanoramaUrl”: “https://s.yimg.com/av/ads/1547243990086-5293.jpg”,
“videoPrimaryUrl”: null,
“videoPortraitUrl”: http://www.video.portrait.com,
“runAsSingleImage”: “FALSE”,
...

Example Portrait Touchpoints Ad¶

...
“imageUrl”:  null,
“imageUrlHQ”:  null,
“imageUrlThumbnail”:  null,
“imagePortraitUrlBG”:  null,
“imagePortraitUrl” : "https://s.yimg.com/av/ads/1539886327922-6353.jpg",
“videoPrimaryUrl”: null,
“videoPortraitUrl”: http://www.video.portrait.com,
“runAsSingleImage”: “FALSE”,
assets":[
         {
            "type":"TOUCHPOINT_PORTRAIT",
            "status":"ACTIVE",
            "index":150,
            "title":null,
            "description":null,
            "callToActionText":null,
            "templateType":"DOT_DARK",
            "landingUrl":"http://yahoo.com",
            "videoCaptionUrl":null,
            "verticalIndex":150,
            "fixedPosition":null,
            "fitToHeight":null,
            "styles":{
               "x":"150",
               "y":"150",
               "z":null,
               "w":"50",
               "h":"50",
               "ic":null,
               "oc":null,
               "callToActionText":null
            },
            "lights":null,
            "imageUrl":"https://s3.us-west-1.amazonaws.com/gemini-dev-public/curveball/ads/gi/RESIZE/627x627/68888f55d1f7906fec41055313c50aab.jpeg",
            "videoAutoloop":null,
            "assetJSON":null
         }
      ]

...

Important

For Carousel Ads – Native Ad Platform accepts a maximum of 5 carousel card assets in the assets array. Set the index in the assets array between 0 and 4. A minimum of 3 carousel card assets are required.

Example Tile Asset Object¶

{
  "assets": [
    {
      "index": 0,
      "verticalIndex": 0,
      "type": "TILES_IMAGE",
      "assetUrl": "https://myimage.jpg",
      "landingUrl": "http://www.yahoo.com",
      "fitToHeight": "TRUE"
    },
    {
      "index": 0,
      "verticalIndex": 1,
      "type": "TILES_VIDEO",
      "assetUrl": "https://myvideo.mp4",
      "videoCaptionUrl": "https://myvideocaption.vtt",
      "videoAutoloop": "TRUE"
    },
    {
      "index": 0,
      "verticalIndex": 2,
      "type": "TILES_TEXT",
      "assetUrl": "https://mytextcontent.html"
    },
    {
      "index": 0,
      "verticalIndex": 3,
      "type": "TILES_BUTTON",
      "assetUrl": "https://mybuttoncontent.html",
      "landingUrl": "http://www.yahoo.com",
      "fixedPosition": "BOTTOM"
    }
  ]
}

Example Panorama Touchpoints Ad¶

...
“imageUrl”:  null,
“imageUrlHQ”:  null,
“imageUrlThumbnail”:  null,
“imagePortraitUrlBG”:  null,
“imagePortraitUrl” : "https://s.yimg.com/av/ads/1539886327922-6353.jpg",
“imagePanoramaUrl”: “https://s.yimg.com/av/ads/1547243990086-5293.jpg”,
“videoPrimaryUrl”: null,
“videoPortraitUrl”: http://www.video.portrait.com,
“runAsSingleImage”: “FALSE”,
assets":[
         {
            "type":"TOUCHPOINT_PORTRAIT",
            "status":"ACTIVE",
            "index":150,
            "title":null,
            "description":null,
            "callToActionText":null,
            "templateType":"DOT_DARK",
            "landingUrl":"http://yahoo.com",
            "videoCaptionUrl":null,
            "verticalIndex":150,
            "fixedPosition":null,
            "fitToHeight":null,
            "styles":{
               "x":"150",
               "y":"150",
               "z":null,
               "w":"50",
               "h":"50",
               "ic":null,
               "oc":null,
               "callToActionText":null
            },
            "lights":null,
            "imageUrl":"https://s3.us-west-1.amazonaws.com/gemini-dev-public/curveball/ads/gi/RESIZE/627x627/68888f55d1f7906fec41055313c50aab.jpeg",
            "videoAutoloop":null,
            "assetJSON":null
         }
      ]

...

Example Image Ad with Portrait Template Colors¶

...
      "description":"test test",
      "adGroupId":281002,
      "trackingUrl":null,
      "optimizeAssets":null,
      "styles":{
         "callToActionText":{
            "bgColor":"000000"
         },
         "container":{
            "bgColorGradientLinear1":"F0F0F0",
            "bgColorGradientLinear2":"FFFFFF"
         }
      },
...

Important

Native Ad Platform accepts a maximum of 5 assets in the assets array. Set the index in the assets array between 0 and 4. A minimum of 3 assets are required.

Call to action buttons¶

The Native Ad Platform API enables you to add call to action buttons to your native ads, encouraging users to take specific actions after seeing your ad. A call to action value can be set using the callToActionText field in the Ad object.

For a list of available values, refer to Call to Action Buttons.

Support
Terms and Privacy Policy
Your Privacy Choices
About Us Jobs Developer Privacy Developer Terms Developer Policies Site Feedback
Brands Yahoo Developer Yahoo Ads SDK Analytics Reporting Yahoo Edgecast Developer Ad Platform Help Center
Group 5 Group 7 Group 4 Group 3 Group 14
Yahoo Logo