What’s New

To stay current with changes, updates and new features in the Yahoo Native API, you’ll want to read this section. The What’s New is updated on a weekly cadence for API partners and developers.

Each month the Yahoo Native API Product Bulletin summarizes the latest updates and changes based on input from the Yahoo Native team. Be sure to read the Bulletins to retrieve information that may impact your product development.

Important - For Advertisers Making GET Requests

Note that all GET request calls require a single advertiser parameter, if you are not fetching objects by ids.

When making GET requests for ads, for example, only one adGroupId or advertiserId parameter is allowed to be passed in as a query parameter for all filtered list GET calls. Similarly, when making GET requests for campaigns, only a single advertiserId parameter is allowed to be passed in as a query parameter for filtered list campaign 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 to all endpoints. API partners need to make these changes, which will be enforced on the Yahoo 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://iws.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://iws.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

Release Notes

Yahoo Native API Release Notes are now archived in Resources and available if you wish to review past changes.

Yahoo Native v3 API

The v3 API was released on 25 July 2017. This release provides partners and developers with the following features and capabilities:

  • Support for Upgraded URLs (UUs), which enable you to better define and control the landing page and tracking of your URLs. For more information on Upgraded URLs (UUs) in v3, refer to Upgraded URLs.

  • Greater API object stability, as well as improved management of API changes, building on the enhancements in v2 API.

  • Support for Site X Device Targeting with new available targeting attributes. For more information, refer to Targeting Attributes. Note that Site X Device targeting is also supported in the v2 Native & Search API.

  • New reporting cubes available for querying at the ad group level:

    • site_performance_stats for use when querying for native ads campaign data.

    • campaign_bid_performance_stats for use when evaluating group-level bid modifiers.

For more information, refer to Cubes.

  • New reporting dimensions available for querying at the advertiser, ad, campaign, ad group and keyword levels. For more information, refer to Dimensions.

  • Postman examples added for Upgraded URLs (v3) and Bid by Site (v2). For more information, refer to Postman API Toolkit.

  • Additional bug and error fixes for improved performance and stability.


Developers are encouraged to migrate to the v3 Native Ad Platform API in order to maintain access to the latest features and functionality. Note that new features are only added to the current version.

Yahoo Native v2 API

The v2 API includes the following changes:

  • Yahoo Native v2 API has been released. Starting on 1 June 2016, Yahoo Native will migrate the programmatic Yahoo Native API from v1 to v2; the current version of the Yahoo Native API will be v2. Be sure to read the sections on Versioning and API v1 Deprecation, plus the FAQs for details.

  • Developers are encouraged to migrate to the v2 Yahoo Native API in order to maintain access to the latest features and functionality. Please note that new features are only added to the current version. In the event of a special situation that would require a fundamental change across all versions, a migration path will be provided. For any migration, you will have at least a 90-day window to migrate and integrate your app.


The Native v1 API will be supported for 90 days beyond the June 1, 2016 deprecation date. After that date, starting on September 1, 2016, the Native v1 API will be available for one year. After that time, it will be relegated to End of Life (EOL) status.

  • With the v2 release, new v2 Shared Set Libraries have been added that enable you to create, populate and associate shared sets to your campaigns and ad groups. New v2 Shared Site Link has been added with methods for creating, updating and retrieving shared sitelinks.


In the v2 API, only one parentId parameter is allowed to be passed in as a query parameter for all filtered list GET calls. This change will have impact when you filter lists of GET calls on ad, ad group, campaign, ad extensions, keyword, targeting, shared sitelinks, and created, populated and associated shared set calls. Refer to each of the relevant sections in the documentation for details.

v2 Data Model

The v2 Yahoo Native API introduces a new data model with new entities, as shown in the diagram below. The v2 data model illustrates how shared sets and the new shared site link objects work and connect.

v2 api gemini data model

For more information, see the v2 Shared Set Libraries and the v2 Shared Site Link sections.

Other New Features, Changes & Enhancements

  • New call_extension_stats cube has been added to Reporting. Use this cube to get detailed information about conversions on click 2 call ad extensions at the account, campaign and adgroup levels. For more information, see call_extension_stats.

  • Note the following: Any changes to either the landing urls or the text attributes of the following entities – Ad, Keywords and Sitelinks – will result in a state transition to ON_HOLD for the purposes of editorial review. Note that our SLA is 24 hours; however, in practice, most ads are re-activated in 1 to 2 hours. Plan your edits and sync logic, accordingly.

  • New, detailed explanation of Steps to follow before you begin OAuth 2.0 authentication. If you’re new to the Native Ad Platform API, you should read the section and follow the steps listed. Note also in the section on OAuth refresh tokens that access tokens will expire after 60 minutes.

  • New Keyword status and editorialStatus fields added in v2. Also, new Ad status and editorialStatus fields added in v2.

  • New Bulk schema upload and download changes in v2, providing partners and developers with a unified format for bulk operations and data representation. To consolidate all targeting attributes in bulk files to a single, unified standard, as well as expose targeting attribute entity IDs for all objects, the v2 API includes the changes described in Bulk schema upload and download.

  • New, re-architected Yahoo Native API Table of Contents for easier navigation and retrieval of documentation topics and information. With the introduction of v2, we’ve organized and consolidated much of the technical content, so that each topic folder contains the specific information you need when coding and integrating your apps. If you’ve bookmarked topics in the v1 API, you may find some of those links broken; you’ll need to bookmark new links that are relevant to your development efforts.

Release Notes - Archived

The Release Notes section is now an Archive of notes in Resources, dating back to the initial release of the v1 Yahoo Native API. Explore these if you need to track changes, updates and enhancements to the API over time.


You may wish to check out these additional, external resources dedicated to working with Yahoo Native and the API: