API docs by Redocly

SmartNews Marketing API (2.0.0)

Download OpenAPI specification:Download

URL: https://smartnews-ads.zendesk.com/hc/ja/requests/new?ticket_form_id=&u=1723081408

Documentation for the SmartNews Marketing API for AMv2.

Authentication / Authorization

To set the JWT token in the HTTP header based on the provided OpenAPI definition, please include the Authorization header with the following format:

Authorization: Bearer <access token>

Access tokens are generated using the OAuth API. Please refer to the OAuth API for more information.

Rate Limit

Details will be shared.

Change Log

Aug 2024 - Initial release.

Oct 2024

  • Added new endpoints and a security scheme for API Auth.
  • (insights) Deprecated conversion_attribution_mode and added new fields click_attribution_window and vimp_attribution_window
  • (insights) Added metadata_ad_creative_format and metrics_spent_before_this_month to fields.
  • (insights) Added county to breakdown_type.
  • (campaigns) Added INSTALL_WITH_IN_APP_EVENT for optimization_goal.
  • (ad-group) Added new field dynamic_ads_config (targeting_type, recency_days)
  • (ad) Added catalog_image_creative_info to creative.

Base URL

Details will be shared.

oauth

Generate an access token

Generate an access token for the developer application

Authorizations:
ApiKeyAuth
Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string

The grant type of the request. It should be 'client_credentials'.

client_id
required
integer <int64>

The client id(developer app id) of the developer app.

client_secret
required
string

The client secret of the developer app. Client secret is a credential generated when the developer app is created.

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "expires_in": 86400,
  • "token_type": "Bearer",
  • "scope": "ads-manager"
}

Revoke all active access tokens for the developer application

Revoke all active access tokens for the developer application

Authorizations:
ApiKeyAuth
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
integer <int64>

The client id(developer app id) of the developer app.

client_secret
required
string

The client secret of the developer app. Client secret is a credential generated when the developer app is created.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

insights

Insights

Get a list of metadata and metrics information for objects matching the query for the specified layer (Campaign/AdGroup/Ad).

The fields to include in the response must be specified by the API caller, using the fields parameter.

Note: Only Ads Manager v2 objects can be retrieved by this API.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
layer
required
string (Layer)
Enum: "campaigns" "ad_groups" "ads"
query Parameters
parent_ids
Array of strings

Only applies to AdGroup and Ad. Filter by parent id(s) (campaign_id for AdGroup, and ad_group_id for Ad)

since
required
string <date-time>
Example: since=2024-08-15T15:00:00Z

Only include metrics from this datetime (inclusive).

It must be specified in ISO 8601 format with UTC timezone (ends with Z).

until
string <date-time>
Example: until=2024-08-15T15:00:00Z

Only include metrics until this datetime (inclusive).

It must be specified in ISO 8601 format with UTC timezone (ends with Z).

fields
required
Array of strings (Field)
Items Enum: "metadata_name" "metadata_created_at" "metadata_updated_at" "metadata_configured_status" "metadata_campaign_id" "metadata_campaign_name" "metadata_ad_group_id" "metadata_ad_group_name" "metadata_delivery_status" "metadata_is_migrated_from_v1" "metadata_has_any_video_ads" "metadata_objective" "metadata_optimization_event" "metadata_optimization_goal" "metadata_start_date_time" "metadata_end_date_time" "metadata_daily_budget_amount_micro" "metadata_daily_budget_amount" "metadata_ready_for_delivery" "metadata_is_large_unit_ads" "metadata_thumbnails" "metadata_video" "metadata_moderation_status" "metadata_submission_status" "metadata_ad_headline" "metadata_ad_description" "metadata_ad_creative_format" "metrics_viewable_impression" "metrics_click" "metrics_ctr" "metrics_cpc" "metrics_cpm" "metrics_count_web_conversion" "metrics_cvr_web_conversion" "metrics_cpa_web_conversion" "metrics_count_purchase" "metrics_cvr_purchase" "metrics_cpa_purchase" "metrics_count_add_to_cart" "metrics_cvr_add_to_cart" "metrics_cpa_add_to_cart" "metrics_count_initiate_checkout" "metrics_cvr_initiate_checkout" "metrics_cpa_initiate_checkout" "metrics_count_submit_form" "metrics_cvr_submit_form" "metrics_cpa_submit_form" "metrics_count_subscribe" "metrics_cvr_subscribe" "metrics_cpa_subscribe" "metrics_count_complete_registration" "metrics_cvr_complete_registration" "metrics_cpa_complete_registration" "metrics_count_contact" "metrics_cvr_contact" "metrics_cpa_contact" "metrics_count_sign_up" "metrics_cvr_sign_up" "metrics_cpa_sign_up" "metrics_count_view_content" "metrics_cvr_view_content" "metrics_cpa_view_content" "metrics_count_add_payment_info" "metrics_cvr_add_payment_info" "metrics_cpa_add_payment_info" "metrics_count_add_to_wish_list" "metrics_cvr_add_to_wish_list" "metrics_cpa_add_to_wish_list" "metrics_count_visit_cart" "metrics_cvr_visit_cart" "metrics_cpa_visit_cart" "metrics_count_customize_product" "metrics_cvr_customize_product" "metrics_cpa_customize_product" "metrics_count_search" "metrics_cvr_search" "metrics_cpa_search" "metrics_count_booking" "metrics_cvr_booking" "metrics_cpa_booking" "metrics_count_download" "metrics_cvr_download" "metrics_cpa_download" "metrics_count_start_trial" "metrics_cvr_start_trial" "metrics_cpa_start_trial" "metrics_count_share" "metrics_cvr_share" "metrics_cpa_share" "metrics_count_login" "metrics_cvr_login" "metrics_cpa_login" "metrics_count_donate" "metrics_cvr_donate" "metrics_cpa_donate" "metrics_count_find_location" "metrics_cvr_find_location" "metrics_cpa_find_location" "metrics_count_time_spent" "metrics_cvr_time_spent" "metrics_cpa_time_spent" "metrics_count_install" "metrics_cvr_install" "metrics_cpa_install" "metrics_budget_spent" "metrics_lifetime_spent" "metrics_spent_before_this_month" "metrics_video_views" "metrics_video_views_p25" "metrics_video_views_p50" "metrics_video_views_p75" "metrics_video_views_p95" "metrics_video_views_completed" "metrics_reach" "metrics_frequency"

The fields to include in the response. For a detailed description of each field, see the response section under metadata or metrics.

The prefix indicates whether the field will be present in the metadata or metrics object of the response.

  • Starts with metadata_: Is a metadata field.
  • Starts with metrics_: Is a metrics field.
  • metrics_reach and metrics_frequency are only supported when Accept header is text/csv

Layer Specific Metadata fields

Campaign

  • metadata_objective
  • metadata_daily_budget_amount
  • metadata_start_date_time
  • metadata_end_date_time
  • metadata_optimization_event
  • metadata_optimization_goal

Ad Group

  • metadata_campaign_id
  • metadata_campaign_name
  • metadata_campaign_id
  • metadata_campaign_name
  • metadata_ad_group_id
  • metadata_ad_group_name
  • metadata_submission_status
  • metadata_moderation_status
  • metadata_thumbnails
  • metadata_video
  • metadata_ad_headline
  • metadata_ad_description
  • metadata_ad_creative_format
breakdown_type
string (BreakdownType)
Enum: "age" "gender" "age_and_gender" "prefecture" "city" "connection_type" "os" "device_type" "carrier_type" "state" "county"
Example: breakdown_type=age

When specified, the report is broken down by the specified audience breakdown type. The breakdown can be found inside the metrics_breakdown field in the response.

breakdown_period
string (BreakdownPeriod)
Enum: "hour" "day"
Example: breakdown_period=hour

The time period to breakdown the report by. The breakdown can be found inside the metrics_breakdown field in the response.

This option combines with the breakdown_type param. For example breakdown_type=age&breakdown_period=day results in one breakdown row for each day and age combination within the specified date range.

include_deleted
boolean (IncludeDeleted)
Default: false

Boolean flag for including deleted objects in the response.

conversion_attribution_mode
string (ConversionAttributionMode)
Deprecated
Enum: "all" "click_through"

Please use click_attribution_window and vimp_attribution_window instead. For conversion_attribution_mode = all, use the combination of click_attribution_window and vimp_attribution_window. For conversion_attribution_mode = click_through, use click_attribution_window and vimp_attribution_window = none`.

mobile_app_attribution_mode
string (MobileAppAttributionMode)
Enum: "all" "mmp_only"

The mobile app attribution mode for counting conversions of app campaigns only. The mobile app attribution mode will not be applied for web campaigns. The counting conversions for web campaigns is affected by conversion_attribution_mode only. There are two modes: all and mmp_only. all mode counts all app campaigns' conversions including those attributed by a Mobile Measurement Partner and SmartNews attribution. mmp_only mode only counts app campaigns' conversions attributed by a Mobile Measurement Partner.

click_attribution_window
string (ClickAttributionWindow)
Enum: "days_30" "days_14" "days_7" "day_1"

The attribution window for counting conversions. Calculate the conversions that occur within the specified time window after a click. The default value is 30 days.

vimp_attribution_window
string (VimpAttributionWindow)
Enum: "day_1" "none"

The attribution window for counting conversions. Calculate the conversions that occur within the specified time window after a viewable impression. The default value is 1 day.

target_ids
Array of integers <int64> [ items <int64 > ]

Filter by target id(s) (campaign_id for Campaign, ad_group_id for AdGroup, ad_id for Ad) Only the ad object id of the specified layer (determined by the layer in the path) is supported.

header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
{
  • "data": [
    ]
}

Aggregated Insights

Get aggregated metrics information for objects matching the query for the specified layer (Campaign/AdGroup/Ad).

The fields to include in the response must be specified by the API caller, using the fields parameter.

Note: Only Ads Manager v2 metrics can be retrieved by this API.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
layer
required
string (Layer)
Enum: "campaigns" "ad_groups" "ads"
query Parameters
parent_ids
Array of strings

Only applies to AdGroup and Ad. Filter by parent id(s) (campaign_id for AdGroup, and ad_group_id for Ad)

since
required
string <date-time>

Show only records after and including this datetime; datetime must be specified in ISO 8601 format

until
string <date-time>

Show only records before and including this datetime; date must be specified in ISO 8601 format

fields
Array of strings (Field)
Items Enum: "metadata_name" "metadata_created_at" "metadata_updated_at" "metadata_configured_status" "metadata_campaign_id" "metadata_campaign_name" "metadata_ad_group_id" "metadata_ad_group_name" "metadata_delivery_status" "metadata_is_migrated_from_v1" "metadata_has_any_video_ads" "metadata_objective" "metadata_optimization_event" "metadata_optimization_goal" "metadata_start_date_time" "metadata_end_date_time" "metadata_daily_budget_amount_micro" "metadata_daily_budget_amount" "metadata_ready_for_delivery" "metadata_is_large_unit_ads" "metadata_thumbnails" "metadata_video" "metadata_moderation_status" "metadata_submission_status" "metadata_ad_headline" "metadata_ad_description" "metadata_ad_creative_format" "metrics_viewable_impression" "metrics_click" "metrics_ctr" "metrics_cpc" "metrics_cpm" "metrics_count_web_conversion" "metrics_cvr_web_conversion" "metrics_cpa_web_conversion" "metrics_count_purchase" "metrics_cvr_purchase" "metrics_cpa_purchase" "metrics_count_add_to_cart" "metrics_cvr_add_to_cart" "metrics_cpa_add_to_cart" "metrics_count_initiate_checkout" "metrics_cvr_initiate_checkout" "metrics_cpa_initiate_checkout" "metrics_count_submit_form" "metrics_cvr_submit_form" "metrics_cpa_submit_form" "metrics_count_subscribe" "metrics_cvr_subscribe" "metrics_cpa_subscribe" "metrics_count_complete_registration" "metrics_cvr_complete_registration" "metrics_cpa_complete_registration" "metrics_count_contact" "metrics_cvr_contact" "metrics_cpa_contact" "metrics_count_sign_up" "metrics_cvr_sign_up" "metrics_cpa_sign_up" "metrics_count_view_content" "metrics_cvr_view_content" "metrics_cpa_view_content" "metrics_count_add_payment_info" "metrics_cvr_add_payment_info" "metrics_cpa_add_payment_info" "metrics_count_add_to_wish_list" "metrics_cvr_add_to_wish_list" "metrics_cpa_add_to_wish_list" "metrics_count_visit_cart" "metrics_cvr_visit_cart" "metrics_cpa_visit_cart" "metrics_count_customize_product" "metrics_cvr_customize_product" "metrics_cpa_customize_product" "metrics_count_search" "metrics_cvr_search" "metrics_cpa_search" "metrics_count_booking" "metrics_cvr_booking" "metrics_cpa_booking" "metrics_count_download" "metrics_cvr_download" "metrics_cpa_download" "metrics_count_start_trial" "metrics_cvr_start_trial" "metrics_cpa_start_trial" "metrics_count_share" "metrics_cvr_share" "metrics_cpa_share" "metrics_count_login" "metrics_cvr_login" "metrics_cpa_login" "metrics_count_donate" "metrics_cvr_donate" "metrics_cpa_donate" "metrics_count_find_location" "metrics_cvr_find_location" "metrics_cpa_find_location" "metrics_count_time_spent" "metrics_cvr_time_spent" "metrics_cpa_time_spent" "metrics_count_install" "metrics_cvr_install" "metrics_cpa_install" "metrics_budget_spent" "metrics_lifetime_spent" "metrics_spent_before_this_month" "metrics_video_views" "metrics_video_views_p25" "metrics_video_views_p50" "metrics_video_views_p75" "metrics_video_views_p95" "metrics_video_views_completed" "metrics_reach" "metrics_frequency"

The fields to include in the response. For a detailed description of each field, see the response section under metrics.

Note: only fields beginning with metrics_ are supported for aggregated insights.

include_deleted
boolean (IncludeDeleted)
Default: false

Boolean flag for including deleted objects in the response.

conversion_attribution_mode
string (ConversionAttributionMode)
Deprecated
Enum: "all" "click_through"

Please use click_attribution_window and vimp_attribution_window instead. For conversion_attribution_mode = all, use the combination of click_attribution_window and vimp_attribution_window. For conversion_attribution_mode = click_through, use click_attribution_window and vimp_attribution_window = none`.

mobile_app_attribution_mode
string (MobileAppAttributionMode)
Enum: "all" "mmp_only"

The mobile app attribution mode for counting conversions of app campaigns only. The mobile app attribution mode will not be applied for web campaigns. The counting conversions for web campaigns is affected by conversion_attribution_mode only. There are two modes: all and mmp_only. all mode counts all app campaigns' conversions including those attributed by a Mobile Measurement Partner and SmartNews attribution. mmp_only mode only counts app campaigns' conversions attributed by a Mobile Measurement Partner.

click_attribution_window
string (ClickAttributionWindow)
Enum: "days_30" "days_14" "days_7" "day_1"

The attribution window for counting conversions. Calculate the conversions that occur within the specified time window after a click. The default value is 30 days.

vimp_attribution_window
string (VimpAttributionWindow)
Enum: "day_1" "none"

The attribution window for counting conversions. Calculate the conversions that occur within the specified time window after a viewable impression. The default value is 1 day.

target_ids
Array of integers <int64> [ items <int64 > ]

Filter by target id(s) (campaign_id for Campaign, ad_group_id for AdGroup, ad_id for Ad) Only the ad object id of the specified layer (determined by the layer in the path) is supported.

header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
application/json
{
  • "total_objects": 0,
  • "data": {
    }
}

campaign

Create a Campaign

Create a campaign object. An ad account can only have up to 1,000 campaigns.

When the number of campaigns exceed the limit, the API returns a Business Error.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
query Parameters
source
string (Source)
Value: "copy"

The way how this campaign object is created. This parameter is used to distinguish whether the campaign is created normally (from scratch) or by using the copy feature.
By default, we assume all the newly created campaigns are created from scratch, so the only accepted value for this parameter is copy.

header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Request Body schema: application/json
name
required
string (Name) [ 1 .. 256 ] characters

The name of the campaign.

Note: The maximum length is calculated by our standard length calculation rules: See details

objective
required
string (CampaignObjective)
Enum: "TRAFFIC" "SALES" "AWARENESS" "APP_PROMOTION"

The objective of the campaign. It defines the business goal that customers pursue during a campaign.

website_tracking_tag
string or null (WebsiteTrackingTag)

The pixel tag id that is used to report web events generated through a campaign.
Required if Objective is SALES and Click Destination Type is WEB_VIEW

This field is not updatable when ready_for_delivery is true.

daily_budget_amount_micro
required
integer <int64> (DailyBudgetAmountMicro)

The average budget per day in micros of the ad account currency base unit.

Ad Account's currency Minimum value Maximum Value Minimum unit
JPY 100,000,000 100,000,000,000,000 1,000,000
USD 1,000,000 1,000,000,000,000 10,000

The API will return an error if the provided value is not divisible by the minimum unit.

bid_strategy
required
string (BidStrategy)
Enum: "MANUAL" "HIGHEST_VOLUME" "TARGET_COST"

The strategy that defines how the amount of bid is decided.

Objective Available bid strategies
TRAFFIC HIGHEST_VOLUME
TRAFFIC MANUAL
SALES HIGHEST_VOLUME
SALES TARGET_COST
AWARENESS HIGHEST_VOLUME
AWARENESS MANUAL
APP_PROMOTION HIGHEST_VOLUME
APP_PROMOTION TARGET_COST
target_cost_micro
integer or null <int64> (TargetCostMicro)

The cost per acquisition in micros of the ad account currency base unit.
This is only required and configurable if and only if the bidding strategy is TARGET_COST.

Ad Account's currency Minimum value Maximum Value Minimum unit
JPY 50,000,000 1,000,000,000,000 1,000,000
USD 500,000 10,000,000,000 10,000

The API will return an error if the provided value is not divisible by the minimum unit.

bid_amount_micro
integer or null <int64> (BidAmountMicro)

The bidding amount for MANUAL bidding strategy in micros of the ad account currency base unit.
This field is configurable and required if and only if the bid_strategy is MANUAL.

Ad Account's currency Minimum value Maximum Value Minimum unit
JPY 1,000,000 1,000,000,000,000 1,000,000
USD 10,000 10,000,000,000 10,000

The API will return an error if the provided value is not divisible by the minimum unit.
If the billing event is IMPRESSION, then the bidding amount is the price the campaign bids for 1000 VIMPs.

billing_event
required
string
Enum: "CLICK" "VIEWABLE_IMPRESSION"

The type of event that the ad account wants to pay for the campaign.

Objective Available billing events
TRAFFIC CLICK
SALES CLICK
AWARENESS VIEWABLE_IMPRESSION
APP_PROMOTION CLICK

This field is not updatable when ready_for_delivery is true.

optimization_goal
string or null (OptimizationGoal)
Enum: "CLICKS" "OFFSITE_CONVERSIONS" "VIEWABLE_IMPRESSIONS" "INSTALL" "INSTALL_WITH_IN_APP_EVENT"

Optimization goal defines how the campaign is optimized.

This is required and configurable unless bidding strategy is MANUAL.

Objective Bid Strategy Available Optimization Goal
TRAFFIC HIGHEST_VOLUME CLICKS
TRAFFIC MANUAL null
SALES HIGHEST_VOLUME OFFSITE_CONVERSIONS
SALES TARGET_COST OFFSITE_CONVERSIONS
AWARENESS HIGHEST_VOLUME VIEWABLE_IMPRESSIONS
AWARENESS MANUAL null
APP_PROMOTION HIGHEST_VOLUME INSTALL, INSTALL_WITH_IN_APP_EVENT
APP_PROMOTION TARGET_COST INSTALL, INSTALL_WITH_IN_APP_EVENT

This field is not updatable when ready_for_delivery is true.

delivery_type
string or null (DeliveryType)
Enum: "STANDARD" "ACCELERATED"

Delivery type adjusts the speed of budget spending throughout the day.
A delivery type must be configured for MANUAL or TARGET_COST bid strategy, while it must be null for HIGHEST_VOLUME \

If null is provided during the creation of a campaign, a default value is assigned by the system as following:

Objective Bid Strategy Default Delivery Type
TRAFFIC HIGHEST_VOLUME null
TRAFFIC MANUAL ACCELERATED
SALES HIGHEST_VOLUME null
SALES TARGET_COST ACCELERATED
AWARENESS HIGHEST_VOLUME null
AWARENESS MANUAL STANDARD
APP_PROMOTION TARGET_COST ACCELERATED
APP_PROMOTION HIGHEST_VOLUME null
optimization_event
string or null (OptimizationEvent)
Enum: "PURCHASE" "ADD_TO_CART" "INITIATE_CHECKOUT" "SUBMIT_FORM" "SUBSCRIBE" "COMPLETE_REGISTRATION" "CONTACT" "SIGN_UP" "VIEW_CONTENT" "ADD_PAYMENT_INFO" "ADD_TO_WISH_LIST" "VISIT_CART" "CUSTOMIZE_PRODUCT" "SEARCH" "BOOKING" "DOWNLOAD" "START_TRIAL" "SHARE" "LOGIN" "DONATE" "FIND_LOCATION" "TIME_SPENT" "INSTALL"

Optimization event defines which conversion event the campaign is optimized for.

This is required and configurable if and only if the optimization_goal is OFFSITE_CONVERSIONS.

Objective Available optimization events
TRAFFIC (no available values for now)
SALES PURCHASE, ADD_TO_CART, COMPLETE_REGISTRATION, VIEW_CONTENT, SUBSCRIBE
AWARENESS (no available values for now)
APP_PROMOTION INSTALL

This field is not updatable when ready_for_delivery is true.

start_date_time
required
string <date-time> (StartDateTime)

The date-time at which the campaign is scheduled to start.

Minimum value: ≥ today (ad account based timezone)
Maximum value: 2099-12-31T23:58:00 (ad account based timezone)

The API rejects the value if seconds / milliseconds are specified except 0.

This field is not updatable when ready_for_delivery is true.

end_date_time
string or null <date-time> (EndDateTime)

The date-time at which the campaign is scheduled to end.

Minimum value: max(current_date_time, start_date_time)
Maximum value: 2099-12-31T23:59:00 (ad account based timezone)

The API rejects the value if seconds / milliseconds are specified except 0.

This field is nullable. When it is set to null, it means the campaign runs indefinitely.

configured_status
required
string (ConfiguredStatus)
Enum: "ACTIVE" "PAUSED" "DELETED"

The status of the object configured by an ad operator.

spending_limit_micro
integer <int64> (SpendingLimitMicro)

The life-time spending limit in micros of the ad account currency base unit. Null means there is no limit.

Ad Account's currency Minimum value (creation only) Maximum Value Minimum unit
JPY 100,000,000 1,000,000,000,000,000 1,000,000
USD 1,000,000 10,000,000,000,000 10,000

The API will return an error if the provided value is not divisible by the minimum unit. After the creation, please refer to the minimal_spending_limit_micro field for the minimum value.

object (ViewabilityMeasurement)

Configuration for 3rd party viewability measurement provider. It is not editable when the campaign is ready for delivery. Currently, only MOAT is supported.

click_destination_type
string or null (ClickDestinationType)
Enum: "WEB_VIEW" "BROWSER" "APP" "APP_STORE"

This defines which components SmartNews opens after an ad is clicked.

If click_destination_type = null when creating campaign then default value is set as below:

  1. click_destination_type = APP / APP_STORE for APP_PROMOTION objective
  2. click_destination_type = WEB_VIEW for remaining available objectives
Objective Available click destination types
TRAFFIC WEB_VIEW, BROWSER
SALES WEB_VIEW, BROWSER
AWARENESS WEB_VIEW, BROWSER
APP_PROMOTION APP, APP_STORE
is_large_unit_ads
boolean (IsLargeUnitAds)

A boolean flag that indicates whether ads from this campaign are displayed in the app using the large unit format. Currently Only effective for awareness campaigns

is_dynamic_ads
boolean (IsDynamicAds)
Default: false

A boolean flag that indicates whether the campaign is dynamic ads or standard ads.

Currently supported objectives for dynamic ads campaigns:

  • TRAFFIC
object (DynamicAdsInfo)

Configuration specific to dynamic ads campaigns.

If is_dynamic_ads is true, this field is required.

budget_auto_target_cpa_micro
integer or null <int64> (BudgetAutoTargetCpaMicro)
Default: null

Budget Auto-adjustment Expected CPA in micros of the ad account currency base unit.

This value is only able to be set when campaign objective is SALES and bidding strategy is HIGHEST_VOLUME. Otherwise it must be null.

object (AppPromotionInfo)

Configuration specific to App Promotion objective campaigns. It is required when objective is APP_PROMOTION

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "objective": "TRAFFIC",
  • "website_tracking_tag": "89d2b4523c7245ee9ec773a8",
  • "daily_budget_amount_micro": 10000000000,
  • "bid_strategy": "MANUAL",
  • "target_cost_micro": 0,
  • "bid_amount_micro": 0,
  • "billing_event": "CLICK",
  • "optimization_goal": "CLICKS",
  • "delivery_type": "STANDARD",
  • "optimization_event": "PURCHASE",
  • "start_date_time": "2046-01-07T16:02:00Z",
  • "end_date_time": "2046-02-07T16:02:00Z",
  • "configured_status": "ACTIVE",
  • "spending_limit_micro": 10000000000,
  • "viewability_measurement": {},
  • "click_destination_type": "WEB_VIEW",
  • "is_large_unit_ads": true,
  • "is_dynamic_ads": false,
  • "dynamic_ads_info": {
    },
  • "budget_auto_target_cpa_micro": 10000000000,
  • "app_promotion_info": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "objective": "TRAFFIC",
  • "website_tracking_tag": "89d2b4523c7245ee9ec773a8",
  • "daily_budget_amount_micro": 10000000000,
  • "bid_strategy": "MANUAL",
  • "target_cost_micro": 0,
  • "bid_amount_micro": 0,
  • "billing_event": "CLICK",
  • "optimization_goal": "CLICKS",
  • "delivery_type": "STANDARD",
  • "optimization_event": "PURCHASE",
  • "start_date_time": "2046-01-07T16:02:00Z",
  • "end_date_time": "2046-02-07T16:02:00Z",
  • "configured_status": "ACTIVE",
  • "spending_limit_micro": 10000000000,
  • "viewability_measurement": {},
  • "click_destination_type": "WEB_VIEW",
  • "is_large_unit_ads": true,
  • "is_dynamic_ads": false,
  • "dynamic_ads_info": {
    },
  • "budget_auto_target_cpa_micro": 10000000000,
  • "app_promotion_info": {
    },
  • "campaign_id": 0,
  • "ad_account_id": 0,
  • "buying_type": "AUCTION",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "ready_for_delivery": true,
  • "delivery_status": {
    },
  • "total_spending": "10000",
  • "minimal_spending_limit_micro": 10000000000,
  • "has_any_video_ads": true,
  • "is_migrated_from_v1": true
}

List Campaigns

Get an array of campaign objects.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
query Parameters
sort_by
string
Enum: "campaign_id" "name" "objective" "configured_status" "daily_budget_amount_micro" "optimization_goal" "start_date_time" "end_date_time"

The field of a campaign that is used for sorting

sort_order
string (SortOrder)
Enum: "ASC" "DESC"

The order of the sorting. Must be specified if and only if sort_by is specified.

offset
integer <int32> (PageOffset) >= 0

The number of page when pagination is applied. The nubmer start from 0. 0 if not specified.

limit
integer <int32> (PageLimit) >= 50

The maximum of each page when pagination is applied. The minimum number is 50. 50 if not specified.

include_deleted
boolean (IncludeDeleted)
Default: false

Boolean flag for including deleted campaigns in the response.

header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a Campaign

Get a single campaign object.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
campaign_id
required
integer <int64>
header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "objective": "TRAFFIC",
  • "website_tracking_tag": "89d2b4523c7245ee9ec773a8",
  • "daily_budget_amount_micro": 10000000000,
  • "bid_strategy": "MANUAL",
  • "target_cost_micro": 0,
  • "bid_amount_micro": 0,
  • "billing_event": "CLICK",
  • "optimization_goal": "CLICKS",
  • "delivery_type": "STANDARD",
  • "optimization_event": "PURCHASE",
  • "start_date_time": "2046-01-07T16:02:00Z",
  • "end_date_time": "2046-02-07T16:02:00Z",
  • "configured_status": "ACTIVE",
  • "spending_limit_micro": 10000000000,
  • "viewability_measurement": {},
  • "click_destination_type": "WEB_VIEW",
  • "is_large_unit_ads": true,
  • "is_dynamic_ads": false,
  • "dynamic_ads_info": {
    },
  • "budget_auto_target_cpa_micro": 10000000000,
  • "app_promotion_info": {
    },
  • "campaign_id": 0,
  • "ad_account_id": 0,
  • "buying_type": "AUCTION",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "ready_for_delivery": true,
  • "delivery_status": {
    },
  • "total_spending": "10000",
  • "minimal_spending_limit_micro": 10000000000,
  • "has_any_video_ads": true,
  • "is_migrated_from_v1": true
}

Update a Campaign

Update an existing campaign by using the JSON Merge Patch specification, described in RFC 7396.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
campaign_id
required
integer <int64>
header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Request Body schema: application/merge-patch+json
name
string (Name) [ 1 .. 256 ] characters

The name of the campaign.

Note: The maximum length is calculated by our standard length calculation rules: See details

configured_status
string (ConfiguredStatus)
Enum: "ACTIVE" "PAUSED" "DELETED"

The status of the object configured by an ad operator.

daily_budget_amount_micro
integer <int64> (DailyBudgetAmountMicro)

The average budget per day in micros of the ad account currency base unit.

Ad Account's currency Minimum value Maximum Value Minimum unit
JPY 100,000,000 100,000,000,000,000 1,000,000
USD 1,000,000 1,000,000,000,000 10,000

The API will return an error if the provided value is not divisible by the minimum unit.

website_tracking_tag
string or null (WebsiteTrackingTag)

The pixel tag id that is used to report web events generated through a campaign.
Required if Objective is SALES and Click Destination Type is WEB_VIEW

This field is not updatable when ready_for_delivery is true.

optimization_event
string or null (OptimizationEvent)
Enum: "PURCHASE" "ADD_TO_CART" "INITIATE_CHECKOUT" "SUBMIT_FORM" "SUBSCRIBE" "COMPLETE_REGISTRATION" "CONTACT" "SIGN_UP" "VIEW_CONTENT" "ADD_PAYMENT_INFO" "ADD_TO_WISH_LIST" "VISIT_CART" "CUSTOMIZE_PRODUCT" "SEARCH" "BOOKING" "DOWNLOAD" "START_TRIAL" "SHARE" "LOGIN" "DONATE" "FIND_LOCATION" "TIME_SPENT" "INSTALL"

Optimization event defines which conversion event the campaign is optimized for.

This is required and configurable if and only if the optimization_goal is OFFSITE_CONVERSIONS.

Objective Available optimization events
TRAFFIC (no available values for now)
SALES PURCHASE, ADD_TO_CART, COMPLETE_REGISTRATION, VIEW_CONTENT, SUBSCRIBE
AWARENESS (no available values for now)
APP_PROMOTION INSTALL

This field is not updatable when ready_for_delivery is true.

start_date_time
string <date-time> (StartDateTime)

The date-time at which the campaign is scheduled to start.

Minimum value: ≥ today (ad account based timezone)
Maximum value: 2099-12-31T23:58:00 (ad account based timezone)

The API rejects the value if seconds / milliseconds are specified except 0.

This field is not updatable when ready_for_delivery is true.

end_date_time
string or null <date-time> (EndDateTime)

The date-time at which the campaign is scheduled to end.

Minimum value: max(current_date_time, start_date_time)
Maximum value: 2099-12-31T23:59:00 (ad account based timezone)

The API rejects the value if seconds / milliseconds are specified except 0.

This field is nullable. When it is set to null, it means the campaign runs indefinitely.

bid_strategy
string (BidStrategy)
Enum: "MANUAL" "HIGHEST_VOLUME" "TARGET_COST"

The strategy that defines how the amount of bid is decided.

Objective Available bid strategies
TRAFFIC HIGHEST_VOLUME
TRAFFIC MANUAL
SALES HIGHEST_VOLUME
SALES TARGET_COST
AWARENESS HIGHEST_VOLUME
AWARENESS MANUAL
APP_PROMOTION HIGHEST_VOLUME
APP_PROMOTION TARGET_COST
target_cost_micro
integer or null <int64> (TargetCostMicro)

The cost per acquisition in micros of the ad account currency base unit.
This is only required and configurable if and only if the bidding strategy is TARGET_COST.

Ad Account's currency Minimum value Maximum Value Minimum unit
JPY 50,000,000 1,000,000,000,000 1,000,000
USD 500,000 10,000,000,000 10,000

The API will return an error if the provided value is not divisible by the minimum unit.

bid_amount_micro
integer or null <int64> (BidAmountMicro)

The bidding amount for MANUAL bidding strategy in micros of the ad account currency base unit.
This field is configurable and required if and only if the bid_strategy is MANUAL.

Ad Account's currency Minimum value Maximum Value Minimum unit
JPY 1,000,000 1,000,000,000,000 1,000,000
USD 10,000 10,000,000,000 10,000

The API will return an error if the provided value is not divisible by the minimum unit.
If the billing event is IMPRESSION, then the bidding amount is the price the campaign bids for 1000 VIMPs.

optimization_goal
string or null (OptimizationGoal)
Enum: "CLICKS" "OFFSITE_CONVERSIONS" "VIEWABLE_IMPRESSIONS" "INSTALL" "INSTALL_WITH_IN_APP_EVENT"

Optimization goal defines how the campaign is optimized.

This is required and configurable unless bidding strategy is MANUAL.

Objective Bid Strategy Available Optimization Goal
TRAFFIC HIGHEST_VOLUME CLICKS
TRAFFIC MANUAL null
SALES HIGHEST_VOLUME OFFSITE_CONVERSIONS
SALES TARGET_COST OFFSITE_CONVERSIONS
AWARENESS HIGHEST_VOLUME VIEWABLE_IMPRESSIONS
AWARENESS MANUAL null
APP_PROMOTION HIGHEST_VOLUME INSTALL, INSTALL_WITH_IN_APP_EVENT
APP_PROMOTION TARGET_COST INSTALL, INSTALL_WITH_IN_APP_EVENT

This field is not updatable when ready_for_delivery is true.

delivery_type
string or null (DeliveryType)
Enum: "STANDARD" "ACCELERATED"

Delivery type adjusts the speed of budget spending throughout the day.
A delivery type must be configured for MANUAL or TARGET_COST bid strategy, while it must be null for HIGHEST_VOLUME \

If null is provided during the creation of a campaign, a default value is assigned by the system as following:

Objective Bid Strategy Default Delivery Type
TRAFFIC HIGHEST_VOLUME null
TRAFFIC MANUAL ACCELERATED
SALES HIGHEST_VOLUME null
SALES TARGET_COST ACCELERATED
AWARENESS HIGHEST_VOLUME null
AWARENESS MANUAL STANDARD
APP_PROMOTION TARGET_COST ACCELERATED
APP_PROMOTION HIGHEST_VOLUME null
spending_limit_micro
integer <int64> (SpendingLimitMicro)

The life-time spending limit in micros of the ad account currency base unit. Null means there is no limit.

Ad Account's currency Minimum value (creation only) Maximum Value Minimum unit
JPY 100,000,000 1,000,000,000,000,000 1,000,000
USD 1,000,000 10,000,000,000,000 10,000

The API will return an error if the provided value is not divisible by the minimum unit. After the creation, please refer to the minimal_spending_limit_micro field for the minimum value.

object (ViewabilityMeasurement)

Configuration for 3rd party viewability measurement provider. It is not editable when the campaign is ready for delivery. Currently, only MOAT is supported.

click_destination_type
string or null (ClickDestinationType)
Enum: "WEB_VIEW" "BROWSER" "APP" "APP_STORE"

This defines which components SmartNews opens after an ad is clicked.

If click_destination_type = null when creating campaign then default value is set as below:

  1. click_destination_type = APP / APP_STORE for APP_PROMOTION objective
  2. click_destination_type = WEB_VIEW for remaining available objectives
Objective Available click destination types
TRAFFIC WEB_VIEW, BROWSER
SALES WEB_VIEW, BROWSER
AWARENESS WEB_VIEW, BROWSER
APP_PROMOTION APP, APP_STORE
is_large_unit_ads
boolean (IsLargeUnitAds)

A boolean flag that indicates whether ads from this campaign are displayed in the app using the large unit format. Currently Only effective for awareness campaigns

budget_auto_target_cpa_micro
integer or null <int64> (BudgetAutoTargetCpaMicro)
Default: null

Budget Auto-adjustment Expected CPA in micros of the ad account currency base unit.

This value is only able to be set when campaign objective is SALES and bidding strategy is HIGHEST_VOLUME. Otherwise it must be null.

object (PatchAppPromotionInfo)

It contains the fields of AppPromotionInfo which are updatable.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "configured_status": "ACTIVE",
  • "daily_budget_amount_micro": 10000000000,
  • "website_tracking_tag": "89d2b4523c7245ee9ec773a8",
  • "optimization_event": "PURCHASE",
  • "start_date_time": "2046-01-07T16:02:00Z",
  • "end_date_time": "2046-02-07T16:02:00Z",
  • "bid_strategy": "MANUAL",
  • "target_cost_micro": 0,
  • "bid_amount_micro": 0,
  • "optimization_goal": "CLICKS",
  • "delivery_type": "STANDARD",
  • "spending_limit_micro": 10000000000,
  • "viewability_measurement": {},
  • "click_destination_type": "WEB_VIEW",
  • "is_large_unit_ads": true,
  • "budget_auto_target_cpa_micro": 10000000000,
  • "app_promotion_info": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "objective": "TRAFFIC",
  • "website_tracking_tag": "89d2b4523c7245ee9ec773a8",
  • "daily_budget_amount_micro": 10000000000,
  • "bid_strategy": "MANUAL",
  • "target_cost_micro": 0,
  • "bid_amount_micro": 0,
  • "billing_event": "CLICK",
  • "optimization_goal": "CLICKS",
  • "delivery_type": "STANDARD",
  • "optimization_event": "PURCHASE",
  • "start_date_time": "2046-01-07T16:02:00Z",
  • "end_date_time": "2046-02-07T16:02:00Z",
  • "configured_status": "ACTIVE",
  • "spending_limit_micro": 10000000000,
  • "viewability_measurement": {},
  • "click_destination_type": "WEB_VIEW",
  • "is_large_unit_ads": true,
  • "is_dynamic_ads": false,
  • "dynamic_ads_info": {
    },
  • "budget_auto_target_cpa_micro": 10000000000,
  • "app_promotion_info": {
    },
  • "campaign_id": 0,
  • "ad_account_id": 0,
  • "buying_type": "AUCTION",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "ready_for_delivery": true,
  • "delivery_status": {
    },
  • "total_spending": "10000",
  • "minimal_spending_limit_micro": 10000000000,
  • "has_any_video_ads": true,
  • "is_migrated_from_v1": true
}

Delete a Campaign

Delete an existing campaign and all of its ad-groups and ads. The API returns a business error if the campaign cannot be deleted due to business logic constraints.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
campaign_id
required
integer <int64>
header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

ad-group

Get an Ad Group

Get a single Ad Group object.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
ad_group_id
required
integer <int64>
header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "audience": {
    },
  • "frequency_control": {
    },
  • "configured_status": "ACTIVE",
  • "dynamic_ads_config": {
    },
  • "campaign_id": 0,
  • "ad_group_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "parent": {
    },
  • "delivery_status": {
    },
  • "has_any_video_ads": true,
  • "is_migrated_from_v1": true
}

Update an Ad Group

Update an existing ad group by using the JSON Merge Patch specification, described in RFC 7396.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
ad_group_id
required
integer <int64>
header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Request Body schema: application/merge-patch+json
name
string (AdGroupSchemas_Name) [ 1 .. 256 ] characters

The name of the ad group.

Note: The maximum length is calculated by our standard length calculation rules: See details

configured_status
string (ConfiguredStatus)
Enum: "ACTIVE" "PAUSED" "DELETED"

The status of the object configured by an ad operator.

object or null (FrequencyControl)

Frequency control settings for the ads to be delivered. Only available for Awareness campaign.

object (AudienceRequest)

In Patch Request, if you omit the property, the data will remain unchanged.

If you want to remove the current settings, set individual fields to either null or an empty array.

e.g. This will remove the current settings of ages and genders, while keeping the locations and other audience fields unchanged:

{
  ages: [],
  genders: null,
}
object (DynamicAdsConfigSchema)

The Configuration of the dynamic ads. If campaign is for dynamic ads, this object is required.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "configured_status": "ACTIVE",
  • "frequency_control": {
    },
  • "audience": {
    },
  • "dynamic_ads_config": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "audience": {
    },
  • "frequency_control": {
    },
  • "configured_status": "ACTIVE",
  • "dynamic_ads_config": {
    },
  • "campaign_id": 0,
  • "ad_group_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "parent": {
    },
  • "delivery_status": {
    },
  • "has_any_video_ads": true,
  • "is_migrated_from_v1": true
}

Delete an Ad Group

Delete an existing ad-group and its children(ad). The API returns a business error if the ad-group has any ads that cannot be deleted.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
ad_group_id
required
integer <int64>
header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List Ad Groups By Ad Account

Get an array of adgroup under a specified ad account

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
query Parameters
include_deleted
boolean (IncludeDeleted)
Default: false

Boolean flag for including deleted ad groups in the response.

header Parameters
Accept-Language
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create an Ad Group

Create an ad group object. A campaign can only have up to 1,000 ad groups.

When the number of ad groups exceed the limit, the API returns a Business Error.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
campaign_id
required
integer <int64>
query Parameters
source
string (Source)
Value: "copy"

The way how this ad group object is created. This parameter is used to distinguish whether the campaign is created normally (from scratch) or by using the copy feature.
By default, we assume all the newly created ad groups are created from scratch, so the only accepted value for this parameter is copy.

header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Request Body schema: application/json
name
required
string (AdGroupSchemas_Name) [ 1 .. 256 ] characters

The name of the ad group.

Note: The maximum length is calculated by our standard length calculation rules: See details

object (AudienceRequest)

In Patch Request, if you omit the property, the data will remain unchanged.

If you want to remove the current settings, set individual fields to either null or an empty array.

e.g. This will remove the current settings of ages and genders, while keeping the locations and other audience fields unchanged:

{
  ages: [],
  genders: null,
}
object or null (FrequencyControl)

Frequency control settings for the ads to be delivered. Only available for Awareness campaign.

configured_status
required
string (ConfiguredStatus)
Enum: "ACTIVE" "PAUSED" "DELETED"

The status of the object configured by an ad operator.

object (DynamicAdsConfigSchema)

The Configuration of the dynamic ads. If campaign is for dynamic ads, this object is required.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "audience": {
    },
  • "frequency_control": {
    },
  • "configured_status": "ACTIVE",
  • "dynamic_ads_config": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "audience": {
    },
  • "frequency_control": {
    },
  • "configured_status": "ACTIVE",
  • "dynamic_ads_config": {
    },
  • "campaign_id": 0,
  • "ad_group_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "parent": {
    },
  • "delivery_status": {
    },
  • "has_any_video_ads": true,
  • "is_migrated_from_v1": true
}

List Ad Groups By Campaign

Get an array of adgroup under a specified campaign_id.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
campaign_id
required
integer <int64>
query Parameters
include_deleted
boolean (IncludeDeleted)
Default: false

If true, deleted Ad Groups are included in the response.

header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

Controls the language of response text.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

ad

List Ads By Ad Account

Get an array of ads under one ad account

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
query Parameters
include_deleted
boolean (IncludeDeleted)
Default: false

When true, deleted ads are included in the response.

header Parameters
Accept-Language
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create an Ad

Create an ad object. A single Ad Group can have up to 100 ads.

When the number of ads exceed the limit, the API returns a Business Error.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
ad_group_id
required
integer <int64>
query Parameters
source
string (Source)
Value: "copy"

The way how this ad object is created. This parameter is used to distinguish whether the campaign is created normally (from scratch) or by using the copy feature.
By default, we assume all the newly created ads are created from scratch, so the only accepted value for this parameter is copy.

header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Request Body schema: application/json
name
required
string (AdSchemas_Name) [ 1 .. 256 ] characters

Name of an Ad. It is only used by customers to distinguish their Ads on Ads Manager.

Note: Our standard length calculation rules apply to length validation: See details

landing_page_url
string (LandingPageUrl) [ 1 .. 1024 ] characters

URL of the Website which is opened when an Ad is clicked.
It is required when the parent campaign's click_destination_type is one of the following. It cannot be set if the parent campaign has any other click_destination_type.

  1. WEB_VIEW
  2. BROWSER The API will return a Validation Error if the field doesn't follow the below rules:
  3. URL format should follow the RFC 3986 spec
  4. All characters should be escaped accordingly, except macro parameters.
  5. Only http and https are allowed protocols.
  6. The following macro parameters are supported. The curly brackets characters { or } can only be used as part of the macro parameters.
  • {ad_account_id}
  • {campaign_id}
  • {ad_group_id}
  • {ad_id}
  • {click_id}
cta_label
string or null (CtaLabel)
Enum: "BOOK_NOW" "START_BOOKING" "CONTACT_US" "CALL_US" "REGISTER" "SIGN_UP" "SHOP_NOW" "START_ORDER" "SEE_MORE" "LEARN_MORE" "WATCH_MORE" "REPLY" "APPLY_NOW" "REQUEST_CATALOG" "RESPOND_TO_SURVEY" "PLAY_GAME" "USE_APP" "DOWNLOAD" "INSTALL" "LAUNCH_APP"

If specified, a call to action button with the specified option is displayed on the ad (may not be displayed in all placements).

configured_status
required
string (ConfiguredStatus)
Enum: "ACTIVE" "PAUSED" "DELETED"

The status of the object configured by an ad operator.

object or null (AdImpressionMeasurement)

Configuration for 3rd party ad impression measurement

required
object

The creative to configure for the ad.

Depending on the format, the corresponding *_info object is required.

For example, if format is IMAGE, image_creative_info is required. If format is VIDEO, video_creative_info is required, and so on.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "landing_page_url": "string",
  • "cta_label": "BOOK_NOW",
  • "configured_status": "ACTIVE",
  • "impression_measurement": {},
  • "creative": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "landing_page_url": "string",
  • "cta_label": "BOOK_NOW",
  • "configured_status": "ACTIVE",
  • "impression_measurement": {},
  • "ad_id": 0,
  • "click_destination_type": "WEB_VIEW",
  • "moderation_status": "NOT_REVIEWED",
  • "rejection_reasons": [
    ],
  • "submission_status": "BEFORE_SUBMISSION",
  • "creative": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "parent": {
    },
  • "delivery_status": {
    },
  • "is_migrated_from_v1": true
}

List Ads By Ad Group

Get an array of ad objects.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
ad_group_id
required
integer <int64>
query Parameters
include_deleted
boolean (IncludeDeleted)
Default: false

Boolean flag for including deleted ads in the response.

header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get an Ad

Get a single ad object.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
ad_id
required
integer <int64>
header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "landing_page_url": "string",
  • "cta_label": "BOOK_NOW",
  • "configured_status": "ACTIVE",
  • "impression_measurement": {},
  • "ad_id": 0,
  • "click_destination_type": "WEB_VIEW",
  • "moderation_status": "NOT_REVIEWED",
  • "rejection_reasons": [
    ],
  • "submission_status": "BEFORE_SUBMISSION",
  • "creative": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "parent": {
    },
  • "delivery_status": {
    },
  • "is_migrated_from_v1": true
}

Update an Ad

Update an existing Ad by using the JSON Merge Patch specification, described in RFC 7396.
The API returns an business error when a request updates one or more of the following fields when the submission_status before this API call is SUBMITTED\

  • landing_page_url\
  • cta_label\
  • creative.headline\
  • creative.description\
  • creative.sponsored_name\
  • creative.media_file_ids
Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
ad_id
required
integer <int64>
header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Request Body schema: application/merge-patch+json
name
string (AdSchemas_Name) [ 1 .. 256 ] characters

Name of an Ad. It is only used by customers to distinguish their Ads on Ads Manager.

Note: Our standard length calculation rules apply to length validation: See details

configured_status
string (ConfiguredStatus)
Enum: "ACTIVE" "PAUSED" "DELETED"

The status of the object configured by an ad operator.

landing_page_url
string (LandingPageUrl) [ 1 .. 1024 ] characters

URL of the Website which is opened when an Ad is clicked.
It is required when the parent campaign's click_destination_type is one of the following. It cannot be set if the parent campaign has any other click_destination_type.

  1. WEB_VIEW
  2. BROWSER The API will return a Validation Error if the field doesn't follow the below rules:
  3. URL format should follow the RFC 3986 spec
  4. All characters should be escaped accordingly, except macro parameters.
  5. Only http and https are allowed protocols.
  6. The following macro parameters are supported. The curly brackets characters { or } can only be used as part of the macro parameters.
  • {ad_account_id}
  • {campaign_id}
  • {ad_group_id}
  • {ad_id}
  • {click_id}
cta_label
string or null (CtaLabel)
Enum: "BOOK_NOW" "START_BOOKING" "CONTACT_US" "CALL_US" "REGISTER" "SIGN_UP" "SHOP_NOW" "START_ORDER" "SEE_MORE" "LEARN_MORE" "WATCH_MORE" "REPLY" "APPLY_NOW" "REQUEST_CATALOG" "RESPOND_TO_SURVEY" "PLAY_GAME" "USE_APP" "DOWNLOAD" "INSTALL" "LAUNCH_APP"

If specified, a call to action button with the specified option is displayed on the ad (may not be displayed in all placements).

submission_status
string (SubmissionStatus)
Enum: "BEFORE_SUBMISSION" "SUBMITTED"

This is the status of the ad to know whether our customers submit the ad to moderation or not.

object (CreativePatchRequest)
object or null (AdImpressionMeasurement)

Configuration for 3rd party ad impression measurement

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "configured_status": "ACTIVE",
  • "landing_page_url": "string",
  • "cta_label": "BOOK_NOW",
  • "submission_status": "BEFORE_SUBMISSION",
  • "creative": {
    },
  • "impression_measurement": {}
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "landing_page_url": "string",
  • "cta_label": "BOOK_NOW",
  • "configured_status": "ACTIVE",
  • "impression_measurement": {},
  • "ad_id": 0,
  • "click_destination_type": "WEB_VIEW",
  • "moderation_status": "NOT_REVIEWED",
  • "rejection_reasons": [
    ],
  • "submission_status": "BEFORE_SUBMISSION",
  • "creative": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "parent": {
    },
  • "delivery_status": {
    },
  • "is_migrated_from_v1": true
}

Delete an Ad

Delete an existing ad.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_id
required
integer <int64>
ad_id
required
integer <int64>
header Parameters
Accept-Language
string (AcceptLanguage)
Example: en-US

The language to use for system generated text within API responses.

The currently supported languages are English (en, en-*) and Japanese (ja, ja-JP)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}