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 February
      • Product bulletin 2023 January
      • Product bulletin 2022 December
      • Product bulletin 2022 November
      • Product bulletin 2022 October
      • Product bulletin 2022 September
    • 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.)
    • 中文(香港)
    • 中文(台灣)

Shared Sitelink¶

Abstract¶

The SharedSiteLinkService provides methods for creating, updating, and retrieving shared sitelinks.

Overview¶

Shared SiteLinks are created on the advertiser account level using the shared sitelink endpoint. Once created, you can share and link these to any campaign or ad group. The linking to campaigns or ad groups is handled by the Shared Sitelink Setting endpoint, described in the section below.

Fields¶

Shared SiteLinks include the following fields:

Name

Description

Type

Add

Update

id

The ID of the shared sitelink.

long

required

required

advertiserId

The ID of the advertiser.

long

required

optional

status

The status of the shared sitelink. Valid values:

  • 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.

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 of the shared sitelink.

string

required

optional

description

The description of the shared sitelink.

string

optional

optional

landingUrl

The landing url of the shared sitelink.

string

required

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


The Entity Status and Editorial Status

entity v2 status and editorial status

v3 Upgraded URL Attributes¶

Important

For the v3 Yahoo Native API, Upgraded URL attributes are now supported for the Shared Sitelink object type.

The following table describes the supported UU attributes per the Shared Sitelink object type in v3 Yahoo Native API.

Object

Landing Url

Display Url

Final Url

Mobile Final Url

Tracking Template

Custom Parameters

Display Url Path1

Display Url Path2

Shared Sitelink

dp

no

yes

yes

yes

yes

no

no

Note

dp means 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 (UUs) in v3, refer to Upgraded URLs.

Shared Sitelink Statuses¶

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

Status

Description

ACTIVE

The sitelink is running.

PAUSED

The sitelink is paused and can be re-activated.

REJECTED

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

DELETED

Set the status of the sitelink 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/sharedsitelink/

Example Representations¶

Shared Sitelink

{
 "title": "Sales",
 "landingUrl": "www.yahoo.com",
 "description": "Sales - site link",
 "status": "ACTIVE",
 "id": 103002,
 "advertiserId": 925746
}

Shared Sitelink Array

[
 {
   "title": "Sales",
   "landingUrl": "www.yahoo.com",
   "description":  "Sales - site link",
   "status": "ACTIVE",
   "id": 103002,
   "advertiserId": 925746
 },
 {
   "title": "Awesome",
   "landingUrl": "www.yahoo.com",
   "description": "Awesome - site link",
   "status": "ACTIVE",
   "id": 103003,
   "advertiserId": 925746
 }
]

Shared Sitelink Response

{
"errors": null,
"response": [
   {
       "title": "Sales",
       "landingUrl": "www.yahoo.com",
       "description": "Sales - site link",
       "status": "ACTIVE",
       "id": 103002,
       "advertiserId": 925746
   }
 ]
}

Operations¶

Read

Method: To retrieve data for a specific shared sitelink, make a GET call with the ID parameter:

GET https://api.gemini.yahoo.com/v3/rest/sharedsitelink/1234

The response will be the shared sitelink associated with the id:

{
  "errors": null,
  "response": [
     {
         "title": "Sales",
         "landingUrl": "www.yahoo.com",
         "description": "Sales - site link",
         "status": "ACTIVE",
         "id": 1234,
         "advertiserId": 925746
     }
  ]
}

Method: To retrieve data for a shared sitelink with multiple IDs, make a GET call with the ID parameter:

GET https://api.gemini.yahoo.com/v3/rest/sharedsitelink?id=1234&id=5678

    The response will be the shared sitelinks associated with multiple ids:

    {
      "errors": null,
      "response": [
         {
             "title": "Sales",
             "landingUrl": "www.yahoo.com",
             "description": "Sales - site link",
             "status": "ACTIVE",
             "id": 1234,
             "advertiserId": 925746
         },
         {
             "title": "Sports",
             "landingUrl": "www.yahoo.com",
             "description": "Sports - site link",
             "status": "ACTIVE",
             "id": 5678,
             "advertiserId": 925746
         }
      ]
    }

Read data for a filtered list of shared sitelinks

Method: To retrieve data for a filtered list of shared sitelinks, 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

advertiserId

The ID of the advertiser to filter the shared sitelinks by.

long

status

The shared sitelink status to filter by.

enum


Important

Only one advertiserId parameter is allowed to be passed in as a query parameter for all filtered lists of shared sitelink calls.

Endpoint¶

Resource URI

https://api.gemini.yahoo.com/v3/rest/sharedsitelink?advertiserId=1111

Create a new shared sitelink

Method: To create a new shared set, make a POST call. The response will be the newly created shared sitelink.

For example:

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

Update existing shared sitelink

Method: To update existing shared sitelink, make a PUT call. The result will be the list of updated shared sitelink.

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

Delete a shared sitelink

Method: To delete a shared sitelink, make a PUT call.

Note

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

For example:

DELETE  https://api.gemini.yahoo.com/v3/rest/sharedsitelink/1234
DELETE  https://api.gemini.yahoo.com/v3/rest/sharedsitelink?id=1234&id=5678

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

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

Read data for shared sitelink for carousel card assets (imageUrlHQ or imageUrl)

Method: To retrieve data for a shared sitelink with carousel card assets, make a GET call:

GET  https://api.gemini.yahoo.com/v3/rest/sharedsitelink/
{
  "errors": null,
  "timestamp": "2021-03-23 2:00:40",
  "response": {
      "description": "Sales - site link",
      "landingUrl": "http://www.yahoo.com",
      "customParameters": null,
      "trackingUrl": null,
      "finalUrl": null,
      "title": "Sales",
      "mobileFinalUrl": null,
      "status": "ACTIVE",
      "advertiserId": 280,
      "id": 100010,
      "lastUpdateDate": 1615224905618,
      "createdDate": 1615221566639,
      "imageUrlHQ": null,
      "imageUrl": null,
      "editorialStatus": "PENDING_REVIEW"
   }
 }

Update existing shared sitelink for carousel card assets (imageUrlHQ or imageUrl)

Method: To update an existing shared sitelink for carousel card assets, make a PUT call:

PUT  https://api.gemini.yahoo.com/v3/rest/sharedsitelink/
{
  "description": "Sales - site link",
  "landingUrl": "http://www.yahoo.com",
  "customParameters": null,
  "trackingUrl": null,
  "finalUrl": null,
  "title": "Sales",
  "mobileFinalUrl": null,
  "status": "ACTIVE",
  "advertiserId": 280,
  "id": 100010,
  "imageUrlHQ": "https://s.yimg.com/av/ads/1614745956105-8787.jpg",
  "imageUrl": "https://s.yimg.com/av/ads/1614745955282-1136.jpg"
}

Response

{
  "errors": null,
  "timestamp": "2021-03-23 2:02:36",
  "response": {
      "description": "Sales - site link",
      "landingUrl": "http://www.yahoo.com",
      "customParameters": null,
      "trackingUrl": null,
      "finalUrl": null,
      "title": "Sales",
      "mobileFinalUrl": null,
      "status": "ACTIVE",
      "advertiserId": 280,
      "id": 100010,
      "lastUpdateDate": 1616464956197,
      "createdDate": 1615221566639,
      "imageUrlHQ": "https://s3.us-west-1.amazonaws.com/gemini-dev-public/curveball/ads/gi/RESIZE_AND_CROP/1200x627/8603962bcba3b24c720ee73f9653ab5f.jpeg",
      "imageUrl": "https://s3.us-west-1.amazonaws.com/gemini-dev-public/curveball/ads/gi/RESIZE/627x627/405a14ab2a5f75a2ae989781a219bd04.jpeg",
      "editorialStatus": "PENDING_REVIEW"
  }
}

Delete existing shared sitelink for carousel card assets (imageUrlHQ or imageUrl)

To delete imageUrlHQ or imageUrl, you can pass the empty string “” in the PUT payload like this:

{
  "description": "Sales - site link",
  "landingUrl": "http://www.yahoo.com",
  "customParameters": null,
  "trackingUrl": null,
  "finalUrl": null,
  "title": "Sales",
  "mobileFinalUrl": null,
  "status": "ACTIVE",
  "advertiserId": 280,
  "id": 100010,
  "imageUrlHQ": "",
  "imageUrl": ""
}

Response should be:

{
  "errors": null,
  "timestamp": "2021-03-23 2:04:59",
  "response": {
      "description": "Sales - site link",
      "landingUrl": "http://www.yahoo.com",
      "customParameters": null,
      "trackingUrl": null,
      "finalUrl": null,
      "title": "Sales",
      "mobileFinalUrl": null,
      "status": "ACTIVE",
      "advertiserId": 280,
      "id": 100010,
      "lastUpdateDate": 1616465099168,
      "createdDate": 1615221566639,
      "imageUrlHQ": null,
      "imageUrl": null,
      "editorialStatus": "PENDING_REVIEW"
  }
}
Support
Terms and Privacy Policy
Your Privacy Choices
About Us Jobs Developer Privacy Developer Terms Developer Policies Site Feedback
Brands Yahoo Developer Analytics Reporting Yahoo Edgecast Developer Ad Platform Help Center
Group 5 Group 7 Group 4 Group 3 Group 14
Yahoo Logo