API docs by Redocly

SmartNews Marketing API (2.0.0)

Download OpenAPI specification:Download

About This Document

This document provides the API specifications for the Ads Management system on the SmartNews Ads Platform. It is intended for developers who use the API to automate advertising operations.

To use the SmartNews Ads API, you must agree to the SmartNews Ads API Terms of Service.

Contact Information

API Help Page: https://help-ads.smartnews.com/item-4207/

For inquiries, please contact us through the following link: https://smartnews-ads.zendesk.com/hc/ja/requests/new?ticket_form_id=&u=1723081408

  • Category: Select “Standard Adsに関するお問い合わせ”
  • Ads Manager Version: Select “広告マネージャーV2”
  • Inquiry Type: Select “APIの仕様・不具合について”

Change Log

August 2024 - Initial release.

October 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.
  • (campaign) Removed unsupported query parameters sort_by, sort_order, offset, limit.
  • (ad-group) Removed field frequency_control from audience object in response.

November 2024

  • (ad-group) Added locations and iab_interest_categories endpoints for use with AdGroup targeting.
  • (oauth) Changed oauth access_token endpoint to /api/oauth/v1/access_tokens.
  • (developer app) Added new endpoint for getting a list of ad accounts associated with a specific developer app.
  • (media-file) Added Create Media File endpoint.

Base URL

The base URL for all API requests is https://ads.smartnews.com/.

For example, to call the GET Campaign endpoint, the request URL will be https://ads.smartnews.com/api/ma/v2/ad_accounts/{ad_account_id}/campaigns/{campaign_id}

Rate Limit

Details will be shared.

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.

oauth

Generate an access token

Generate an access token for the developer application

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

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
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_count_d1_retention" "metrics_cvr_d1_retention" "metrics_cpa_d1_retention" "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
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_count_d1_retention" "metrics_cvr_d1_retention" "metrics_cpa_d1_retention" "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" "D1_RETENTION"

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 n/a
SALES PURCHASE, ADD_TO_CART, COMPLETE_REGISTRATION, VIEW_CONTENT, 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
AWARENESS n/a
APP_PROMOTION INSTALL, D1_RETENTION

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
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" "D1_RETENTION"

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 n/a
SALES PURCHASE, ADD_TO_CART, COMPLETE_REGISTRATION, VIEW_CONTENT, 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
AWARENESS n/a
APP_PROMOTION INSTALL, D1_RETENTION

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": {
    }
}

media-file

Create a Media File

Create a Media File which can be used in Ad Creatives.

Authorizations:
ApiKeyAuth
path Parameters
ad_account_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: multipart/form-data
file_name
required
string

The filename of the uploaded file.

media_type
required
string (MediaType)
Enum: "IMAGE" "VIDEO"

The type of the media file.

media_file
required
string <binary>

If the same file has been uploaded under the same ad account in the past, the existing media file will be returned.

There are 2 types of media which can be uploaded:

  • IMAGE
  • VIDEO

1. IMAGE

Actual Image file to be uploaded to represent the visual image.
Max File Size: 5 MiB
An image which width exceeds Full Size Max Width will be automatically resized to Full Size Max Width.
A small size image can be uploaded if its width exceeds Min Width.
The aspect ratio of the image must match one the of pre-defined aspect ratios.
Min Width and Full Size Max Width for each pre-defined Aspect Ratio Type are as follows:

Pre-defined aspect ratio Min Width Full Size Max Width Example image size
1:1 300 pixels 600 pixels 300px x 300px
6:5 500 pixels 1080 pixels 600px x 500px
16:9 600 pixels 1280 pixels 1280px x 720px
1.91:1 600 pixels 1280 pixels 1200px x 628px

Allowed Format

  • JPEG
  • PNG

2. VIDEO

Actual Video file to be uploaded to represent the visual video.

Videos that pass the below conditions are allowed to upload:

  • Video Length: 3 (seconds) <= video length <= 60 (seconds)
  • Aspect Ratio: 16:9
  • Minimum Video Resolution: 360p
  • Maximum File size: 100 MiB

Allowed Format

  • MP4

Responses

Response samples

Content type
application/json
{
  • "media_file_id": 0,
  • "ad_account_id": 0,
  • "media_type": "IMAGE",
  • "file_name": "string",
  • "images": {
    },
  • "videos": {
    },
  • "thumbnail_media_file_id": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

locations

List Locations

Returns an array of locations for the specified region (prefectures for JP, states for US).

Each location contains an array of children objects, representing cities inside that prefecture for JP, and counties inside that state for US.

Display names are provided in Japanese and English via the ja and en fields.

Authorizations:
ApiKeyAuth
query Parameters
region
string (Region)
Enum: "JP" "US"

The region to obtain locations for.

There are currently two regions: JP and US.

  • JP: contains all the prefectures and their cities in Japan.
  • US: contains all the states and their counties in the US.

If a value is not specified, the default is JP.

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

interests

List Interests

Returns an array of IAB interest categories which can be used for AdGroup level interest targeting.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

developer-app

Get a list of ad accounts associated with a specific developer app

Get a list of ad accounts associated with a specific developer app.

Authorizations:
ApiKeyAuth

Responses

Response samples

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