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 |
|---|---|---|---|---|
|
The ID of the ad group associated with the ad. |
long |
Required |
Optional |
|
The ID of the advertiser associated with the ad. |
long |
Required |
Optional |
|
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 |
|
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
|
JSON object |
Optional |
Optional |
|
The ID of the campaign associated with the ad. |
long |
Required |
Optional |
|
The description of the ad. Maximum limit is 150 characters. Use |
string |
Required |
Optional |
|
The user-friendly URL displayed to the user. Maximum limit is 35 characters. |
string |
Required |
Optional |
|
The ID of the ad. |
long |
N/A |
Required |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 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 |
|
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 |
|
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 |
|
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 |
|
The status of the ad. Valid input values are:
The |
enum |
Required |
Optional |
|
The editorial status of the ad. Valid values are:
The |
enum |
Read-only |
Read-only |
|
The title for the ad. Maximum limit is 50 characters. Use |
string |
Required |
Optional |
|
The title for the ad. Maximum limit is 30 characters. When using this attribute |
string |
Required |
Optional |
|
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 |
|
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:
Note that this is required for video ads running as PROMOTE_BRAND, APP_INSTALL or REENGAGE_APP campaigns. |
string |
Optional |
Optional |
|
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:
|
string |
Optional |
Optional |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A list of JSON objects representing additional ad assets - for example, carousel image cards |
array |
Optional |
Optional |
|
A configuration object containing all the necessary information for configuring a flash sale ad. Fields include:
|
JSON object |
Optional |
Optional |
|
The list of reasons the ad was editorially rejected due to policy. |
array |
N/A |
N/A |
|
Supported only for carousel ads. When specified as TRUE, the best-performing card will be displayed first. |
boolean |
Optional for carousel card assets. |
optional |
|
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.
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? |
|---|---|---|
|
Supported third-party impression tracking URLs:
Up to 3 impression URLs are supported per ad. |
No |
|
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 |
|
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 |
|---|---|
|
The ad is running. |
|
The ad is paused and can be re-activated. |
|
The ad was declined due to policy violations. Further information is available in the Ad Manager UI. |
|
Set the status of the ad to |
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 |
|---|---|---|
|
The maximum number of rows to retrieve. |
int |
|
The start index or the first element to retrieve. |
int |
|
The ID of the ad group to filter the ads by. |
long |
|
The ad status to filter the ads by. |
enum |
|
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 |
|---|---|
|
The ID of the ad to delete. |
|
The status of the ad set to |
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 |
|---|---|---|
|
Required. The id of the ad to be previewed. |
long |
|
Optional. Either handheld, tablet, or screen. Defaults to handheld. |
enum |
|
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 |
|---|---|---|
|
Required. Should not be in the past. |
string |
|
Optional. The default value is the Advertiser’s time zone. |
string |
|
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 |
|---|---|
|
The ID of the flash sale ad to erase. |
|
The status of the flash sale ad set to |
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 |
|---|---|
|
The ID of the rejected ad. |
|
The status of the rejected ad set to |
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 |
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 |
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.
For text tile asset, a valid HTML URL. Maximum number of embedded links (hrefs) in the HTML is 3. Whitelisted HTML tags:
For button tile asset, a valid HTML URL. No embedded links (hrefs) are allowed. Whitelisted HTML tags:
|
string |
Required for tile assets. Ignored for other asset types. |
optional |
|
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 |
|
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 |
|
For carousel card asset, a valid video URL:
|
string |
Optional for carousel card assets. Ignored for other assets types. |
Optional |
|
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:
|
string |
Applicable for carousel card or video tile assets. Ignored for other assets types. |
optional |
|
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:
Ad assets are defaulted to ACTIVE if no status is provided upon creation. DELETED is used to remove assets. |
enum |
optional |
optional |
|
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 |
|
The type of ad asset. Valid values are:
|
enum |
required |
optional |
|
The template type of an ad asset. Valid values are:
|
enum |
Optional for touchpoint assets. Selected option results in the icon used for the touchpoint. Ignored for other asset types |
optional |
|
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 |
|
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 |
|
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 |
string |
Required for carousel card assets and touchpoint assets. Optional for image and video tile assets. Not applicable for text tiles. |
optional |
|
|
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 |
|
Ad asset styles stored as key-value pair JSON.
|
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.