SmartNews Marketing API (3.0.0)

Download OpenAPI specification:Download

Previous Versions

SmartNews Marketing API (2.0.0): https://ads.smartnews.com/developers/deprecated/v2/index.html
- API v2 will be sunset on June 30, 2026 (JST). Please ensure that your system is updated to use API v3 by that date.

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.

English Version: https://ads.smartnews.com/developers/tos-en.html
Japanese Reference Translation: https://ads.smartnews.com/developers/tos-ja.html

Contact Information

API Help Page:

For inquiries:

For the Japan region

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

カテゴリ: Select "Standard Adsに関するお問い合わせ"
該当の項目: Select "APIの仕様・不具合について"
対象のAPI: Select "Marketing API"

For the US region

Please contact us through the following link: https://business.smartnews.com/get-started-ads

Change Log

January 2026

Released Marketing API v3 version which requires pagination parameters for insights and list campaign/adgroup/ad endpoints.
- See How to Upgrade From Marketing API v2 to v3
- To access the old docs, visit https://ads.smartnews.com/developers/deprecated/v2/index.html
- API v2 will be sunset on June 30, 2026 (JST). Please ensure that your system is updated to use API v3 by that date.

How to Upgrade From Marketing API v2 to v3

The main change is pagination; affected endpoints are as follows:
- /api/ma/v3/ad_accounts/{ad_account_id}/insights/{layer}
- /api/ma/v3/ad_accounts/{ad_account_id}/campaigns
- /api/ma/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id}/ad_groups
- /api/ma/v3/ad_accounts/{ad_account_id}/ad_groups
- /api/ma/v3/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/ads
- /api/ma/v3/ad_accounts/{ad_account_id}/ads
For the above endpoints, page_size and page query parameters are added with default values.
The full list of objects for an account can no longer be retrieved by a single request if the number of objects exceeds the maximum page_size (differs per endpoint, please check endpoint documentation for details).
Newly added pagination object in response provides the total number of available objects and pages. Please use this information to fetch all pages as required.
For insights API, currently only JSON response format is supported. CSV support is coming soon. Please continue to use v2 insights if CSV support is required.

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/v3/ad_accounts/{ad_account_id}/campaigns/

Rate Limit

Requests are limited per developer app ID. Making too many requests in a short time will result in a 429 error.

In this case, please wait a short time and retry the request again.

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.

About Currency Units

The SmartNews Ads Marketing API uses the _micro notation for monetary amounts, representing currency values as integers. Examples include daily_budget_amount_micro and bid_amount_micro in campaign level.

This integer representation multiplies the actual currency amount by 1,000,000.

Examples:

Currency	API notation (micro)	Actual amount
USD	1,500,000	$1.50 USD
USD	2,500,000	$2.50 USD
JPY	5,000,000	¥5 JPY
JPY	120,000,000	¥120 JPY

In practice, when specifying monetary amounts via the API, you should use an integer value equal to 1,000,000 times the intended actual amount.

Available currencies are set at the advertising account level.

Simultaneous Update Operation Limitation

The following applies to Campaign, AdGroup, Ad POST, PATCH and DELETE endpoints:

There are limitations on doing simultaneous operations on related objects ("simultaneous" means starting a second request before receiving a response from the first request).

The following cases are not allowed and will result in a 409 Conflict error:

Creating, updating or deleting multiple children of the same parent simultaneously.
- Example 1: Updating two Ads which both belong to the same Campaign at the same time.
- Example 2: Creating an Ad and deleting another Ad which both belong to the same Campaign.
- Example 3: Creating two AdGroups which both belong to the same Campaign.
- Example 4: Creating an AdGroup and an Ad which both belong to the same Campaign.
Creating, updating or deleting objects at the same time as its parent object.
- Example 1: Updating a Campaign and its child AdGroup at the same time.
- Example 2: Updating an AdGroup and deleting one of its Ads at the same time.

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

200
400
401

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

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

401

Content type

application/json

{"error": {"message": "string",
"retriable": true
}
}

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.

Currently only JSON response format is supported. CSV support is coming soon.

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 (FieldV3) 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_ad_account_name" "metadata_ad_account_id" "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" "metadata_ready_for_delivery" "metadata_is_large_unit_ads" "metadata_spending_limit" "metadata_thumbnails" "metadata_video" "metadata_moderation_status" "metadata_submission_status" "metadata_ad_headline" "metadata_ad_description" "metadata_ad_creative_format" "metadata_ad_landing_page_url" "metadata_ad_creative_media_file_aspect_ratio" "metrics_viewable_impression" "metrics_click" "metrics_ctr" "metrics_cpc" "metrics_cpm" "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" "metrics_count_skan_install" "metrics_cvr_skan_install" "metrics_cpa_skan_install" "metrics_count_lead" "metrics_cvr_lead" "metrics_cpa_lead" 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 not currently supported 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` `metadata_spending_limit` Ad Group `metadata_campaign_id` `metadata_campaign_name` Ad `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" "hyper_location_segment" 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. When included in a JSON request, the following restrictions apply: cannot use the `city`, `OS`, or `device` breakdown. cannot use `breakdown_type` together with `breakdown_period`.
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. When included in a JSON request, the following restrictions apply: When using `hour` breakdown period, 1-5 object IDs must be specified using the `target_ids` parameter. cannot use `breakdown_type` together with `breakdown_period`.
include_deleted	boolean (IncludeDeleted) Default: false Boolean flag for including deleted objects in the response.
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. 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> [ 1 .. 100 ] items [ items <int64 > ] Example: target_ids=1,2,3 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. When included in a JSON request, this field is required when either of the following parameters is specified: breakdown_type breakdown_period Note: when `breakdown_period` is `hour`, the maximum size of `target_ids` is 5, not 100.
page_size	integer [ 1 .. 100 ] Example: page_size=100 The number of objects to return per page. The maximum page size is 100.
page	integer (Page) >= 1 Default: 1 Example: page=2 The page of data to retrieve. The first page starts at 1, and each page will contain at most `page_size` items (the last page may contain less). To get the maximum available page number, refer to the `total_pages` field in the response's `pagination` object.
sort	Array of strings (SortParameter) [ 1 .. 2 ] items [^[a-zA-Z_]+:(asc\|desc)$] Example: sort=metrics_click:desc,metadata_name:asc Specify an array of fields and orders to sort the response by. The format of each item is `{field}:{order}`. If not specified, the default sort order is by `id` descending. Order must be either `asc` or `desc`. For available values of `field`, see the `SortableField` enum, which includes: Sortable Metadata fields: `metadata_configured_status` `metadata_name` `metadata_start_date_time` `metadata_end_date_time` `metadata_objective` `metadata_daily_budget_amount` `metadata_spending_limit` `metadata_submission_status` `metadata_moderation_status` `metadata_campaign_name` `metadata_ad_group_name` Sortable Metrics fields: All fields starting with `metrics_` are available for sorting, except for: `metrics_reach` `metrics_frequency` `metrics_spent_before_this_month` `metrics_lifetime_spent`
search	string [ 1 .. 256 ] characters Example: search=My Campaign Name Filter by objects in the specified layer whose name or ID contains the search query.
parent_ids	Array of integers <int64> [ 1 .. 100 ] items [ items <int64 > ] Example: parent_ids=1,2,3 Only available when `layer` is `ad_groups` or `ads`. A comma separated list of parent IDs to filter the result by. In `ad_groups` layer, it represents the `campaign_id` of the campaign(s) which own the ad groups. In `ads` layer, it represents the `ad_group_id` of the ad group(s) which own the ads.

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": [{"type": "CAMPAIGN",
"id": 0,
"metadata": {"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"configured_status": "ACTIVE",
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"ad_account_name": "string",
"ad_account_id": 0,
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"optimization_goal": "CLICKS",
"start_date_time": "2046-01-07T16:02:00Z",
"end_date_time": "2046-02-07T16:02:00Z",
"daily_budget_amount": "123.4",
"ready_for_delivery": true,
"has_any_video_ads": true,
"is_migrated_from_v1": true,
"is_large_unit_ads": true,
"spending_limit": "123.4"
},
"metrics": {"viewable_impression": 0,
"click": 0,
"ctr": "0.03",
"cpc": "1.2",
"cpm": "2.34",
"count_purchase": 0,
"cvr_purchase": "2.34",
"cpa_purchase": "2.34",
"count_add_to_cart": 0,
"cvr_add_to_cart": "2.34",
"cpa_add_to_cart": "2.34",
"count_initiate_checkout": 0,
"cvr_initiate_checkout": "2.34",
"cpa_initiate_checkout": "2.34",
"count_submit_form": 0,
"cvr_submit_form": "2.34",
"cpa_submit_form": "2.34",
"count_subscribe": 0,
"cvr_subscribe": "2.34",
"cpa_subscribe": "2.34",
"count_complete_registration": 0,
"cvr_complete_registration": "2.34",
"cpa_complete_registration": "2.34",
"count_contact": 0,
"cvr_contact": "2.34",
"cpa_contact": "2.34",
"count_sign_up": 0,
"cvr_sign_up": "2.34",
"cpa_sign_up": "2.34",
"count_view_content": 0,
"cvr_view_content": "2.34",
"cpa_view_content": "2.34",
"count_add_payment_info": 0,
"cvr_add_payment_info": "2.34",
"cpa_add_payment_info": "2.34",
"count_add_to_wish_list": 0,
"cvr_add_to_wish_list": "2.34",
"cpa_add_to_wish_list": "2.34",
"count_visit_cart": 0,
"cvr_visit_cart": "2.34",
"cpa_visit_cart": "2.34",
"count_customize_product": 0,
"cvr_customize_product": "2.34",
"cpa_customize_product": "2.34",
"count_search": 0,
"cvr_search": "2.34",
"cpa_search": "2.34",
"count_booking": 0,
"cvr_booking": "2.34",
"cpa_booking": "2.34",
"count_download": 0,
"cvr_download": "2.34",
"cpa_download": "2.34",
"count_start_trial": 0,
"cvr_start_trial": "2.34",
"cpa_start_trial": "2.34",
"count_share": 0,
"cvr_share": "2.34",
"cpa_share": "2.34",
"count_login": 0,
"cvr_login": "2.34",
"cpa_login": "2.34",
"count_donate": 0,
"cvr_donate": "2.34",
"cpa_donate": "2.34",
"count_find_location": 0,
"cvr_find_location": "2.34",
"cpa_find_location": "2.34",
"count_time_spent": 0,
"cvr_time_spent": "2.34",
"cpa_time_spent": "2.34",
"count_install": 0,
"cvr_install": "2.34",
"cpa_install": "2.34",
"count_d1_retention": 0,
"cvr_d1_retention": "2.34",
"cpa_d1_retention": "2.34",
"budget_spent": "123.4",
"lifetime_spent": "123.4",
"spent_before_this_month": "123.4",
"video_views": 0,
"video_views_p25": 0,
"video_views_p50": 0,
"video_views_p75": 0,
"video_views_p95": 0,
"video_views_completed": 0,
"reach": 0,
"frequency": "0.2",
"count_skan_install": 0,
"cvr_skan_install": "0.2",
"cpa_skan_install": "0.2",
"count_lead": 0,
"cvr_lead": "2.34",
"cpa_lead": "2.34"
},
"metrics_breakdown": [{"segment_name": "21-24 & MALE",
"period": "2023-11-28, 2023-11-28 12:00",
"viewable_impression": 0,
"click": 0,
"ctr": "0.03",
"cpc": "1.2",
"cpm": "2.34",
"count_purchase": 0,
"cvr_purchase": "2.34",
"cpa_purchase": "2.34",
"count_add_to_cart": 0,
"cvr_add_to_cart": "2.34",
"cpa_add_to_cart": "2.34",
"count_initiate_checkout": 0,
"cvr_initiate_checkout": "2.34",
"cpa_initiate_checkout": "2.34",
"count_submit_form": 0,
"cvr_submit_form": "2.34",
"cpa_submit_form": "2.34",
"count_subscribe": 0,
"cvr_subscribe": "2.34",
"cpa_subscribe": "2.34",
"count_complete_registration": 0,
"cvr_complete_registration": "2.34",
"cpa_complete_registration": "2.34",
"count_contact": 0,
"cvr_contact": "2.34",
"cpa_contact": "2.34",
"count_sign_up": 0,
"cvr_sign_up": "2.34",
"cpa_sign_up": "2.34",
"count_view_content": 0,
"cvr_view_content": "2.34",
"cpa_view_content": "2.34",
"count_add_payment_info": 0,
"cvr_add_payment_info": "2.34",
"cpa_add_payment_info": "2.34",
"count_add_to_wish_list": 0,
"cvr_add_to_wish_list": "2.34",
"cpa_add_to_wish_list": "2.34",
"count_visit_cart": 0,
"cvr_visit_cart": "2.34",
"cpa_visit_cart": "2.34",
"count_customize_product": 0,
"cvr_customize_product": "2.34",
"cpa_customize_product": "2.34",
"count_search": 0,
"cvr_search": "2.34",
"cpa_search": "2.34",
"count_booking": 0,
"cvr_booking": "2.34",
"cpa_booking": "2.34",
"count_download": 0,
"cvr_download": "2.34",
"cpa_download": "2.34",
"count_start_trial": 0,
"cvr_start_trial": "2.34",
"cpa_start_trial": "2.34",
"count_share": 0,
"cvr_share": "2.34",
"cpa_share": "2.34",
"count_login": 0,
"cvr_login": "2.34",
"cpa_login": "2.34",
"count_donate": 0,
"cvr_donate": "2.34",
"cpa_donate": "2.34",
"count_find_location": 0,
"cvr_find_location": "2.34",
"cpa_find_location": "2.34",
"count_time_spent": 0,
"cvr_time_spent": "2.34",
"cpa_time_spent": "2.34",
"count_install": 0,
"cvr_install": "2.34",
"cpa_install": "2.34",
"count_d1_retention": 0,
"cvr_d1_retention": "2.34",
"cpa_d1_retention": "2.34",
"budget_spent": "123.4",
"lifetime_spent": "123.4",
"spent_before_this_month": "123.4",
"video_views": 0,
"video_views_p25": 0,
"video_views_p50": 0,
"video_views_p75": 0,
"video_views_p95": 0,
"video_views_completed": 0,
"reach": 0,
"frequency": "0.2",
"count_skan_install": 0,
"cvr_skan_install": "0.2",
"cpa_skan_install": "0.2",
"count_lead": 0,
"cvr_lead": "2.34",
"cpa_lead": "2.34"
}
],
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
}
}
],
"pagination": {"page": 1,
"page_size": 100,
"total_pages": 10,
"total_objects": 987
}
}

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> 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	Array of strings (FieldV3) 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_ad_account_name" "metadata_ad_account_id" "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" "metadata_ready_for_delivery" "metadata_is_large_unit_ads" "metadata_spending_limit" "metadata_thumbnails" "metadata_video" "metadata_moderation_status" "metadata_submission_status" "metadata_ad_headline" "metadata_ad_description" "metadata_ad_creative_format" "metadata_ad_landing_page_url" "metadata_ad_creative_media_file_aspect_ratio" "metrics_viewable_impression" "metrics_click" "metrics_ctr" "metrics_cpc" "metrics_cpm" "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" "metrics_count_skan_install" "metrics_cvr_skan_install" "metrics_cpa_skan_install" "metrics_count_lead" "metrics_cvr_lead" "metrics_cpa_lead" 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.
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. 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.
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.
breakdown_type	string (AggregatedInsightsBreakdownType) Enum: "age" "gender" "prefecture" 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.

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": {"metadata": {"name": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"configured_status": "ACTIVE",
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"ad_account_name": "string",
"ad_account_id": 0,
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"optimization_goal": "CLICKS",
"start_date_time": "2046-01-07T16:02:00Z",
"end_date_time": "2046-02-07T16:02:00Z",
"daily_budget_amount": "123.4",
"ready_for_delivery": true,
"has_any_video_ads": true,
"is_migrated_from_v1": true,
"is_large_unit_ads": true,
"spending_limit": "123.4"
},
"metrics": {"viewable_impression": 0,
"click": 0,
"ctr": "0.03",
"cpc": "1.2",
"cpm": "2.34",
"count_purchase": 0,
"cvr_purchase": "2.34",
"cpa_purchase": "2.34",
"count_add_to_cart": 0,
"cvr_add_to_cart": "2.34",
"cpa_add_to_cart": "2.34",
"count_initiate_checkout": 0,
"cvr_initiate_checkout": "2.34",
"cpa_initiate_checkout": "2.34",
"count_submit_form": 0,
"cvr_submit_form": "2.34",
"cpa_submit_form": "2.34",
"count_subscribe": 0,
"cvr_subscribe": "2.34",
"cpa_subscribe": "2.34",
"count_complete_registration": 0,
"cvr_complete_registration": "2.34",
"cpa_complete_registration": "2.34",
"count_contact": 0,
"cvr_contact": "2.34",
"cpa_contact": "2.34",
"count_sign_up": 0,
"cvr_sign_up": "2.34",
"cpa_sign_up": "2.34",
"count_view_content": 0,
"cvr_view_content": "2.34",
"cpa_view_content": "2.34",
"count_add_payment_info": 0,
"cvr_add_payment_info": "2.34",
"cpa_add_payment_info": "2.34",
"count_add_to_wish_list": 0,
"cvr_add_to_wish_list": "2.34",
"cpa_add_to_wish_list": "2.34",
"count_visit_cart": 0,
"cvr_visit_cart": "2.34",
"cpa_visit_cart": "2.34",
"count_customize_product": 0,
"cvr_customize_product": "2.34",
"cpa_customize_product": "2.34",
"count_search": 0,
"cvr_search": "2.34",
"cpa_search": "2.34",
"count_booking": 0,
"cvr_booking": "2.34",
"cpa_booking": "2.34",
"count_download": 0,
"cvr_download": "2.34",
"cpa_download": "2.34",
"count_start_trial": 0,
"cvr_start_trial": "2.34",
"cpa_start_trial": "2.34",
"count_share": 0,
"cvr_share": "2.34",
"cpa_share": "2.34",
"count_login": 0,
"cvr_login": "2.34",
"cpa_login": "2.34",
"count_donate": 0,
"cvr_donate": "2.34",
"cpa_donate": "2.34",
"count_find_location": 0,
"cvr_find_location": "2.34",
"cpa_find_location": "2.34",
"count_time_spent": 0,
"cvr_time_spent": "2.34",
"cpa_time_spent": "2.34",
"count_install": 0,
"cvr_install": "2.34",
"cpa_install": "2.34",
"count_d1_retention": 0,
"cvr_d1_retention": "2.34",
"cpa_d1_retention": "2.34",
"budget_spent": "123.4",
"lifetime_spent": "123.4",
"spent_before_this_month": "123.4",
"video_views": 0,
"video_views_p25": 0,
"video_views_p50": 0,
"video_views_p75": 0,
"video_views_p95": 0,
"video_views_completed": 0,
"reach": 0,
"frequency": "0.2",
"count_skan_install": 0,
"cvr_skan_install": "0.2",
"cpa_skan_install": "0.2",
"count_lead": 0,
"cvr_lead": "2.34",
"cpa_lead": "2.34"
},
"metrics_breakdown": [{"segment_name": "21-24 & MALE",
"period": "2023-11-28, 2023-11-28 12:00",
"viewable_impression": 0,
"click": 0,
"ctr": "0.03",
"cpc": "1.2",
"cpm": "2.34",
"count_purchase": 0,
"cvr_purchase": "2.34",
"cpa_purchase": "2.34",
"count_add_to_cart": 0,
"cvr_add_to_cart": "2.34",
"cpa_add_to_cart": "2.34",
"count_initiate_checkout": 0,
"cvr_initiate_checkout": "2.34",
"cpa_initiate_checkout": "2.34",
"count_submit_form": 0,
"cvr_submit_form": "2.34",
"cpa_submit_form": "2.34",
"count_subscribe": 0,
"cvr_subscribe": "2.34",
"cpa_subscribe": "2.34",
"count_complete_registration": 0,
"cvr_complete_registration": "2.34",
"cpa_complete_registration": "2.34",
"count_contact": 0,
"cvr_contact": "2.34",
"cpa_contact": "2.34",
"count_sign_up": 0,
"cvr_sign_up": "2.34",
"cpa_sign_up": "2.34",
"count_view_content": 0,
"cvr_view_content": "2.34",
"cpa_view_content": "2.34",
"count_add_payment_info": 0,
"cvr_add_payment_info": "2.34",
"cpa_add_payment_info": "2.34",
"count_add_to_wish_list": 0,
"cvr_add_to_wish_list": "2.34",
"cpa_add_to_wish_list": "2.34",
"count_visit_cart": 0,
"cvr_visit_cart": "2.34",
"cpa_visit_cart": "2.34",
"count_customize_product": 0,
"cvr_customize_product": "2.34",
"cpa_customize_product": "2.34",
"count_search": 0,
"cvr_search": "2.34",
"cpa_search": "2.34",
"count_booking": 0,
"cvr_booking": "2.34",
"cpa_booking": "2.34",
"count_download": 0,
"cvr_download": "2.34",
"cpa_download": "2.34",
"count_start_trial": 0,
"cvr_start_trial": "2.34",
"cpa_start_trial": "2.34",
"count_share": 0,
"cvr_share": "2.34",
"cpa_share": "2.34",
"count_login": 0,
"cvr_login": "2.34",
"cpa_login": "2.34",
"count_donate": 0,
"cvr_donate": "2.34",
"cpa_donate": "2.34",
"count_find_location": 0,
"cvr_find_location": "2.34",
"cpa_find_location": "2.34",
"count_time_spent": 0,
"cvr_time_spent": "2.34",
"cpa_time_spent": "2.34",
"count_install": 0,
"cvr_install": "2.34",
"cpa_install": "2.34",
"count_d1_retention": 0,
"cvr_d1_retention": "2.34",
"cpa_d1_retention": "2.34",
"budget_spent": "123.4",
"lifetime_spent": "123.4",
"spent_before_this_month": "123.4",
"video_views": 0,
"video_views_p25": 0,
"video_views_p50": 0,
"video_views_p75": 0,
"video_views_p95": 0,
"video_views_completed": 0,
"reach": 0,
"frequency": "0.2",
"count_skan_install": 0,
"cvr_skan_install": "0.2",
"cpa_skan_install": "0.2",
"count_lead": 0,
"cvr_lead": "2.34",
"cpa_lead": "2.34"
}
]
}
}

campaign

List Campaigns (Paginated)

Get a paginated list of campaign objects.

This endpoint returns campaigns with pagination support, including pagination metadata in the response.

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.
campaign_ids	Array of integers <int64> [ 1 .. 100 ] items [ items <int64 > ] Example: campaign_ids=1,2,3 Filter the response by a target list of campaign_ids
page_size	integer (PageSize) [ 1 .. 1000 ] Default: 1000 Example: page_size=100 The number of objects to return per page. The maximum page size is 1000 and the default is 1000.
page	integer (Page) >= 1 Default: 1 Example: page=2 The page of data to retrieve. The first page starts at 1, and each page will contain at most `page_size` items (the last page may contain less). To get the maximum available page number, refer to the `total_pages` field in the response's `pagination` object.

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": [{"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",
"conversion_attribution_window": "ONE_DAY",
"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": {"vendor_type": "MOAT",
"vendor_key": "string",
"verification_parameters": "{\"campaign_name\": \"{campaign_name}\"}",
"verification_script_url": "https://z.moatads.com/mydisplayads248228380663/moatad.js"
},
"click_destination_type": "WEB_VIEW",
"is_large_unit_ads": true,
"is_large_unit_square_ads": true,
"is_multi_order_attribution": false,
"is_skadnetwork_enabled": false,
"is_dynamic_ads": false,
"dynamic_ads_info": {"catalog_id": 0
},
"budget_auto_target_cpa_micro": 10000000000,
"app_promotion_info": {"promotion_type": "INSTALL",
"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
},
"app_tracking_configs": [{"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
}
],
"daily_schedules": [{"start_time": "09:00",
"end_time": "17:00"
}
],
"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": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"total_spending": "10000",
"minimal_spending_limit_micro": 10000000000,
"has_any_video_ads": true,
"is_migrated_from_v1": true,
"is_permanently_disabled": false
}
],
"pagination": {"page": 1,
"page_size": 100,
"total_pages": 10,
"total_objects": 987
}
}

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

Note: Only TRAFFIC and SALES objectives are usable for US region ad account.

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	Usable for US region ad accounts
TRAFFIC	HIGHEST_VOLUME	TRUE
TRAFFIC	MANUAL	TRUE
SALES	HIGHEST_VOLUME	TRUE
SALES	TARGET_COST	TRUE
AWARENESS	HIGHEST_VOLUME	FALSE
AWARENESS	MANUAL	FALSE
APP_PROMOTION	HIGHEST_VOLUME	FALSE
APP_PROMOTION	TARGET_COST	FALSE

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 (BillingEvent)

Enum: "CLICK" "VIEWABLE_IMPRESSION"

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

Objective	Available billing events
TRAFFIC	VIEWABLE_IMPRESSION (non-DA campaign only), CLICK
SALES	VIEWABLE_IMPRESSION (non-DA campaign only), CLICK
AWARENESS	VIEWABLE_IMPRESSION
APP_PROMOTION	VIEWABLE_IMPRESSION, CLICK

This field is not updatable when ready_for_delivery is true.

VIEWABLE_IMPRESSION for non-awareness campaign is coming soon.

VIEWABLE_IMPRESSION is not supported for DA campaigns.

optimization_goal

string or null (OptimizationGoal)

Enum: "CLICKS" "OFFSITE_CONVERSIONS" "VIEWABLE_IMPRESSIONS" "INSTALL" "INSTALL_WITH_IN_APP_EVENT" "ROAS"

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, ROAS
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. ROAS is only allowed to Dynamic Ads campaign with SALES Objective.

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

STANDARD delivery type is not usable for US region ad accounts.

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

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

Optimization Goal	Available optimization events
VIEWABLE_IMPRESSIONS	n/a
CLICK	n/a
OFFSITE_CONVERSIONS	PURCHASE, ADD_TO_CART, COMPLETE_REGISTRATION, VIEW_CONTENT, SUBSCRIBE, CONTACT, SIGN_UP, ADD_PAYMENT_INFO, ADD_TO_WISH_LIST, VISIT_CART, CUSTOMIZE_PRODUCT, SEARCH, BOOKING, DOWNLOAD, START_TRIAL, SHARE, LOGIN, DONATE, FIND_LOCATION, TIME_SPENT, INITIATE_CHECKOUT, SUBMIT_FORM
ROAS (Dynamic Ads only)	ADD_TO_CART, VIEW_CONTENT, PURCHASE, LEAD
INSTALL	INSTALL
INSTALL_WITH_IN_APP_EVENT	D1_RETENTION, PURCHASE, ADD_TO_CART, INITIATE_CHECKOUT, SUBMIT_FORM, SUBSCRIBE, COMPLETE_REGISTRATION, CONTACT, SIGN_UP, VIEW_CONTENT

Note:

This field is not updatable when ready_for_delivery is true.
LEAD event is only available for dynamic ads campaigns.
For dynamic ads campaigns, only the following optimization events are supported:

ADD_TO_CART
VIEW_CONTENT
PURCHASE
LEAD

conversion_attribution_window

string (ConversionAttributionWindow)

Enum: "ONE_DAY" "SEVEN_DAYS" "FOURTEEN_DAYS" "THIRTY_DAYS"

It specifies the time frame in which conversions are counted for the campaign.

The default value is THIRTY_DAYS if not specified.

Available values are dependent on the campaign objective:

SALES: All values are available.
others: Only THIRTY_DAYS is available.

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:

click_destination_type = APP / APP_STORE for APP_PROMOTION objective
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

BROWSER is not usable for US region ad accounts.

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.

This feature is only available when objective is AWARENESS.

This field's value cannot be changed if the campaign already has 1 or more ads.

Note: This field is not settable for US region ad accounts.

is_large_unit_square_ads

boolean (IsLargeUnitSquareAds)

A boolean flag that indicates whether ads from this campaign are displayed in the app using the large unit square format.

This feature is only available when objective is AWARENESS.

This field's value cannot be changed if the campaign already has 1 or more ads.

Note: This field is not settable for US region ad accounts.

is_multi_order_attribution

boolean (IsMultiOrderAttribution)

If enabled, multiple Purchase event postbacks generated from the same click are recorded as separate Purchase events. Otherwise, only the first postback will be recorded.

The default value is false if not specified.

Note: only usable when campaign objective is SALES, optimization event is PURCHASE and bid strategy is not TARGET_COST.

is_skadnetwork_enabled

boolean (IsSKAdNetworkEnabled)

[Coming Soon] This feature is not yet available but will be supported soon.

A boolean flag that indicates whether the campaign is using SKAdNetwork to collect data.

The default value is false if not specified.

Note: only usable when campaign objective is APP_PROMOTION and targets an iOS app.

is_dynamic_ads

boolean (IsDynamicAds)

Default: false

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

Note: The US region ad accounts are not allowed to create dynamic ads campaigns.

Currently supported objectives for dynamic ads campaigns:

TRAFFIC
SALES

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

Array of objects (AppTrackingConfigs) <= 2 items

This field is used to configure app tracking when conversions from both the app and the web need to be tracked.

If the campaign's objective = APP_PROMOTION, then please set campaign.app_promotion_info instead. Otherwise, validation error will be thrown.

This field can be set only when the following conditions are met otherwise it will validation error 1.1 For DA campaign, it is allowed for objective = SALES or TRAFFIC 1.2 For non-DA campaign, it is allowed for SALES objective only. 2. website_tracking_tag is set.

When there are two configs then make sure following conditions apply

One of the config is for iOS and another for Android.
Both appStoreIds exist and are unique.
If MMP is selected, then MmpType is same for both configs.

For PATCH request, If you want to keep the value unchanged, then omit this field from patch request. If you want to remove the current appTrackingConfigs entirely then set this property to empty array. If you want to replace the existing config, then please provide entire array of appTrackingConfig.

Array of objects (DailySchedules) <= 6 items

An array of daily delivery schedules for the campaign. By default, it is empty. If empty, the campaign will run 24/7.

To run an overnight schedule, please create two schedules. For example, to run a campaign from 10 PM to 2 AM, create one schedule from 22:00 to 24:00 and another from 00:00 to 02:00.

Note: even if a daily schedule is provided, the campaign will only be delivered during the campaign's start_date_time and end_date_time.

The number of schedules must be between 1 and 6, if non-null. Windows must not overlap within the same campaign.

In a PATCH request, provide the entire array of daily schedules to replace the existing schedules. If you want to remove all schedules, provide an empty array. To leave unchanged, omit the field from the request body.

Responses

Request samples

Payload

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",
"conversion_attribution_window": "ONE_DAY",
"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": {"vendor_type": "MOAT",
"vendor_key": "string",
"verification_parameters": "{\"campaign_name\": \"{campaign_name}\"}",
"verification_script_url": "https://z.moatads.com/mydisplayads248228380663/moatad.js"
},
"click_destination_type": "WEB_VIEW",
"is_large_unit_ads": true,
"is_large_unit_square_ads": true,
"is_multi_order_attribution": false,
"is_skadnetwork_enabled": false,
"is_dynamic_ads": false,
"dynamic_ads_info": {"catalog_id": 0
},
"budget_auto_target_cpa_micro": 10000000000,
"app_promotion_info": {"promotion_type": "INSTALL",
"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
},
"app_tracking_configs": [{"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
}
],
"daily_schedules": [{"start_time": "09:00",
"end_time": "17:00"
}
]
}

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",
"conversion_attribution_window": "ONE_DAY",
"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": {"vendor_type": "MOAT",
"vendor_key": "string",
"verification_parameters": "{\"campaign_name\": \"{campaign_name}\"}",
"verification_script_url": "https://z.moatads.com/mydisplayads248228380663/moatad.js"
},
"click_destination_type": "WEB_VIEW",
"is_large_unit_ads": true,
"is_large_unit_square_ads": true,
"is_multi_order_attribution": false,
"is_skadnetwork_enabled": false,
"is_dynamic_ads": false,
"dynamic_ads_info": {"catalog_id": 0
},
"budget_auto_target_cpa_micro": 10000000000,
"app_promotion_info": {"promotion_type": "INSTALL",
"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
},
"app_tracking_configs": [{"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
}
],
"daily_schedules": [{"start_time": "09:00",
"end_time": "17:00"
}
],
"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": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"total_spending": "10000",
"minimal_spending_limit_micro": 10000000000,
"has_any_video_ads": true,
"is_migrated_from_v1": true,
"is_permanently_disabled": false
}

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",
"conversion_attribution_window": "ONE_DAY",
"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": {"vendor_type": "MOAT",
"vendor_key": "string",
"verification_parameters": "{\"campaign_name\": \"{campaign_name}\"}",
"verification_script_url": "https://z.moatads.com/mydisplayads248228380663/moatad.js"
},
"click_destination_type": "WEB_VIEW",
"is_large_unit_ads": true,
"is_large_unit_square_ads": true,
"is_multi_order_attribution": false,
"is_skadnetwork_enabled": false,
"is_dynamic_ads": false,
"dynamic_ads_info": {"catalog_id": 0
},
"budget_auto_target_cpa_micro": 10000000000,
"app_promotion_info": {"promotion_type": "INSTALL",
"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
},
"app_tracking_configs": [{"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
}
],
"daily_schedules": [{"start_time": "09:00",
"end_time": "17:00"
}
],
"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": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"total_spending": "10000",
"minimal_spending_limit_micro": 10000000000,
"has_any_video_ads": true,
"is_migrated_from_v1": true,
"is_permanently_disabled": false
}

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

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

Optimization Goal	Available optimization events
VIEWABLE_IMPRESSIONS	n/a
CLICK	n/a
OFFSITE_CONVERSIONS	PURCHASE, ADD_TO_CART, COMPLETE_REGISTRATION, VIEW_CONTENT, SUBSCRIBE, CONTACT, SIGN_UP, ADD_PAYMENT_INFO, ADD_TO_WISH_LIST, VISIT_CART, CUSTOMIZE_PRODUCT, SEARCH, BOOKING, DOWNLOAD, START_TRIAL, SHARE, LOGIN, DONATE, FIND_LOCATION, TIME_SPENT, INITIATE_CHECKOUT, SUBMIT_FORM
ROAS (Dynamic Ads only)	ADD_TO_CART, VIEW_CONTENT, PURCHASE, LEAD
INSTALL	INSTALL
INSTALL_WITH_IN_APP_EVENT	D1_RETENTION, PURCHASE, ADD_TO_CART, INITIATE_CHECKOUT, SUBMIT_FORM, SUBSCRIBE, COMPLETE_REGISTRATION, CONTACT, SIGN_UP, VIEW_CONTENT

Note:

This field is not updatable when ready_for_delivery is true.
LEAD event is only available for dynamic ads campaigns.
For dynamic ads campaigns, only the following optimization events are supported:

ADD_TO_CART
VIEW_CONTENT
PURCHASE
LEAD

conversion_attribution_window

string (ConversionAttributionWindow)

Enum: "ONE_DAY" "SEVEN_DAYS" "FOURTEEN_DAYS" "THIRTY_DAYS"

It specifies the time frame in which conversions are counted for the campaign.

The default value is THIRTY_DAYS if not specified.

Available values are dependent on the campaign objective:

SALES: All values are available.
others: Only THIRTY_DAYS is available.

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	Usable for US region ad accounts
TRAFFIC	HIGHEST_VOLUME	TRUE
TRAFFIC	MANUAL	TRUE
SALES	HIGHEST_VOLUME	TRUE
SALES	TARGET_COST	TRUE
AWARENESS	HIGHEST_VOLUME	FALSE
AWARENESS	MANUAL	FALSE
APP_PROMOTION	HIGHEST_VOLUME	FALSE
APP_PROMOTION	TARGET_COST	FALSE

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

string (BillingEvent)

Enum: "CLICK" "VIEWABLE_IMPRESSION"

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

Objective	Available billing events
TRAFFIC	VIEWABLE_IMPRESSION (non-DA campaign only), CLICK
SALES	VIEWABLE_IMPRESSION (non-DA campaign only), CLICK
AWARENESS	VIEWABLE_IMPRESSION
APP_PROMOTION	VIEWABLE_IMPRESSION, CLICK

This field is not updatable when ready_for_delivery is true.

VIEWABLE_IMPRESSION for non-awareness campaign is coming soon.

VIEWABLE_IMPRESSION is not supported for DA campaigns.

optimization_goal

string or null (OptimizationGoal)

Enum: "CLICKS" "OFFSITE_CONVERSIONS" "VIEWABLE_IMPRESSIONS" "INSTALL" "INSTALL_WITH_IN_APP_EVENT" "ROAS"

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, ROAS
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. ROAS is only allowed to Dynamic Ads campaign with SALES Objective.

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

STANDARD delivery type is not usable for US region ad accounts.

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:

click_destination_type = APP / APP_STORE for APP_PROMOTION objective
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

BROWSER is not usable for US region ad accounts.

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.

This feature is only available when objective is AWARENESS.

This field's value cannot be changed if the campaign already has 1 or more ads.

Note: This field is not settable for US region ad accounts.

is_large_unit_square_ads

boolean (IsLargeUnitSquareAds)

A boolean flag that indicates whether ads from this campaign are displayed in the app using the large unit square format.

This feature is only available when objective is AWARENESS.

This field's value cannot be changed if the campaign already has 1 or more ads.

Note: This field is not settable for US region ad accounts.

is_multi_order_attribution

boolean (IsMultiOrderAttribution)

If enabled, multiple Purchase event postbacks generated from the same click are recorded as separate Purchase events. Otherwise, only the first postback will be recorded.

The default value is false if not specified.

Note: only usable when campaign objective is SALES, optimization event is PURCHASE and bid strategy is not TARGET_COST.

is_skadnetwork_enabled

boolean (IsSKAdNetworkEnabled)

[Coming Soon] This feature is not yet available but will be supported soon.

A boolean flag that indicates whether the campaign is using SKAdNetwork to collect data.

The default value is false if not specified.

Note: only usable when campaign objective is APP_PROMOTION and targets an iOS app.

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.

Array of objects (AppTrackingConfigs) <= 2 items

This field is used to configure app tracking when conversions from both the app and the web need to be tracked.

If the campaign's objective = APP_PROMOTION, then please set campaign.app_promotion_info instead. Otherwise, validation error will be thrown.

This field can be set only when the following conditions are met otherwise it will validation error 1.1 For DA campaign, it is allowed for objective = SALES or TRAFFIC 1.2 For non-DA campaign, it is allowed for SALES objective only. 2. website_tracking_tag is set.

When there are two configs then make sure following conditions apply

One of the config is for iOS and another for Android.
Both appStoreIds exist and are unique.
If MMP is selected, then MmpType is same for both configs.

For PATCH request, If you want to keep the value unchanged, then omit this field from patch request. If you want to remove the current appTrackingConfigs entirely then set this property to empty array. If you want to replace the existing config, then please provide entire array of appTrackingConfig.

Array of objects (DailySchedules) <= 6 items

An array of daily delivery schedules for the campaign. By default, it is empty. If empty, the campaign will run 24/7.

To run an overnight schedule, please create two schedules. For example, to run a campaign from 10 PM to 2 AM, create one schedule from 22:00 to 24:00 and another from 00:00 to 02:00.

Note: even if a daily schedule is provided, the campaign will only be delivered during the campaign's start_date_time and end_date_time.

The number of schedules must be between 1 and 6, if non-null. Windows must not overlap within the same campaign.

In a PATCH request, provide the entire array of daily schedules to replace the existing schedules. If you want to remove all schedules, provide an empty array. To leave unchanged, omit the field from the request body.

Responses

Request samples

Payload

Content type

application/merge-patch+json

{"name": "string",
"configured_status": "ACTIVE",
"daily_budget_amount_micro": 10000000000,
"website_tracking_tag": "89d2b4523c7245ee9ec773a8",
"optimization_event": "PURCHASE",
"conversion_attribution_window": "ONE_DAY",
"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,
"billing_event": "CLICK",
"optimization_goal": "CLICKS",
"delivery_type": "STANDARD",
"spending_limit_micro": 10000000000,
"viewability_measurement": {"vendor_type": "MOAT",
"vendor_key": "string",
"verification_parameters": "{\"campaign_name\": \"{campaign_name}\"}",
"verification_script_url": "https://z.moatads.com/mydisplayads248228380663/moatad.js"
},
"click_destination_type": "WEB_VIEW",
"is_large_unit_ads": true,
"is_large_unit_square_ads": true,
"is_multi_order_attribution": false,
"is_skadnetwork_enabled": false,
"budget_auto_target_cpa_micro": 10000000000,
"app_promotion_info": {"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
},
"app_tracking_configs": [{"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
}
],
"daily_schedules": [{"start_time": "09:00",
"end_time": "17:00"
}
]
}

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",
"conversion_attribution_window": "ONE_DAY",
"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": {"vendor_type": "MOAT",
"vendor_key": "string",
"verification_parameters": "{\"campaign_name\": \"{campaign_name}\"}",
"verification_script_url": "https://z.moatads.com/mydisplayads248228380663/moatad.js"
},
"click_destination_type": "WEB_VIEW",
"is_large_unit_ads": true,
"is_large_unit_square_ads": true,
"is_multi_order_attribution": false,
"is_skadnetwork_enabled": false,
"is_dynamic_ads": false,
"dynamic_ads_info": {"catalog_id": 0
},
"budget_auto_target_cpa_micro": 10000000000,
"app_promotion_info": {"promotion_type": "INSTALL",
"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
},
"app_tracking_configs": [{"operating_system": "IOS",
"store_id": "string",
"mmp_type": "ADJUST",
"mmp_tracking_url": "string"
}
],
"daily_schedules": [{"start_time": "09:00",
"end_time": "17:00"
}
],
"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": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"total_spending": "10000",
"minimal_spending_limit_micro": 10000000000,
"has_any_video_ads": true,
"is_migrated_from_v1": true,
"is_permanently_disabled": false
}

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": {"type": "UNAUTHORIZED",
"message": "string",
"retriable": true
}
}

ad-group

List Ad Groups By Campaign (Paginated)

Get a paginated list of ad group objects under a specified campaign.

This endpoint returns ad groups with pagination support, including pagination metadata in the response.

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.
page_size	integer (PageSize) [ 1 .. 1000 ] Default: 1000 Example: page_size=100 The number of objects to return per page. The maximum page size is 1000 and the default is 1000.
page	integer (Page) >= 1 Default: 1 Example: page=2 The page of data to retrieve. The first page starts at 1, and each page will contain at most `page_size` items (the last page may contain less). To get the maximum available page number, refer to the `total_pages` field in the response's `pagination` object.

header Parameters

Accept-Language

string (AcceptLanguage)

Example: en-US

Controls the language of response text.

Responses

Response samples

Content type

application/json

{"data": [{"name": "string",
"audience": {"ages": ["AGE_UNDER_20"
],
"genders": ["MALE"
],
"locations": [0
],
"zip_codes": ["10001",
"10002"
],
"hyper_location_config": {"user_segment": "RESIDENT_ONLY",
"location_segments": [{"segment_area_type": "PIN_WITH_RADIUS",
"fixed_area_info": {"location_id": 0
},
"location_segment_id": 0,
"pin_with_radius_info": {"address": "string",
"label": "string",
"latitude": "string",
"longitude": "string",
"radius_in_meters": 0
}
},
{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70150
}
},
{"segment_area_type": "PIN_WITH_RADIUS",
"pin_with_radius_info": {"address": "福島県伊達郡川俣町山木屋キトウスズ山２",
"latitude": "37.59268044952155",
"longitude": "140.63639730916015",
"radius_in_meters": 3000,
"label": "My Label"
}
}
]
},
"operating_system": {"type": "IOS",
"since_version": "string"
},
"custom_audiences": {"include": [0
],
"exclude": [0
]
},
"connection_types": ["WIFI"
],
"carrier_types": ["DOCOMO"
],
"interests": [0
],
"media_types": ["SMART_VIEW"
],
"channel_alias_labels": ["CR_JA_TOP"
],
"article_categories": ["JA_JP_ANIMAL"
],
"automated_targeting": {"age_unbreakable": false,
"gender_unbreakable": false,
"location_unbreakable": false,
"custom_audience_unbreakable": false,
"carrier_unbreakable": false,
"connection_type_unbreakable": false,
"os_version_unbreakable": false
}
},
"frequency_control": {"interval": "LAST_1_DAY",
"threshold": 0
},
"configured_status": "ACTIVE",
"dynamic_ads_config": {"targeting_type": "RETARGETING",
"recency_days": "LAST_1_DAY",
"product_set_id": 0
},
"campaign_id": 0,
"ad_group_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"has_any_video_ads": true,
"is_migrated_from_v1": true
}
],
"pagination": {"page": 1,
"page_size": 100,
"total_pages": 10,
"total_objects": 987
}
}

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. Note: This field is not settable for US region ad accounts.
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

Payload

Content type

application/json

{"name": "string",
"audience": {"ages": ["AGE_UNDER_20"
],
"genders": ["MALE"
],
"locations": [0
],
"zip_codes": ["10001",
"10002"
],
"hyper_location_config": {"user_segment": "RESIDENT_AND_VISITOR",
"location_segments": [{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70196
}
},
{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70150
}
},
{"segment_area_type": "PIN_WITH_RADIUS",
"pin_with_radius_info": {"address": "福島県伊達郡川俣町山木屋キトウスズ山２",
"latitude": "37.59268044952155",
"longitude": "140.63639730916015",
"radius_in_meters": 3000,
"label": "My Label"
}
}
]
},
"operating_system": {"type": "IOS",
"since_version": "string"
},
"custom_audiences": {"include": [0
],
"exclude": [0
]
},
"connection_types": ["WIFI"
],
"carrier_types": ["DOCOMO"
],
"interests": [0
],
"media_types": ["SMART_VIEW"
],
"channel_alias_labels": ["CR_JA_TOP"
],
"article_categories": ["JA_JP_ANIMAL"
],
"automated_targeting": {"age_unbreakable": false,
"gender_unbreakable": false,
"location_unbreakable": false,
"custom_audience_unbreakable": false,
"carrier_unbreakable": false,
"connection_type_unbreakable": false,
"os_version_unbreakable": false
}
},
"frequency_control": {"interval": "LAST_1_DAY",
"threshold": 0
},
"configured_status": "ACTIVE",
"dynamic_ads_config": {"targeting_type": "RETARGETING",
"recency_days": "LAST_1_DAY",
"product_set_id": 0
}
}

Response samples

Content type

application/json

{"name": "string",
"audience": {"ages": ["AGE_UNDER_20"
],
"genders": ["MALE"
],
"locations": [0
],
"zip_codes": ["10001",
"10002"
],
"hyper_location_config": {"user_segment": "RESIDENT_ONLY",
"location_segments": [{"segment_area_type": "PIN_WITH_RADIUS",
"fixed_area_info": {"location_id": 0
},
"location_segment_id": 0,
"pin_with_radius_info": {"address": "string",
"label": "string",
"latitude": "string",
"longitude": "string",
"radius_in_meters": 0
}
},
{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70150
}
},
{"segment_area_type": "PIN_WITH_RADIUS",
"pin_with_radius_info": {"address": "福島県伊達郡川俣町山木屋キトウスズ山２",
"latitude": "37.59268044952155",
"longitude": "140.63639730916015",
"radius_in_meters": 3000,
"label": "My Label"
}
}
]
},
"operating_system": {"type": "IOS",
"since_version": "string"
},
"custom_audiences": {"include": [0
],
"exclude": [0
]
},
"connection_types": ["WIFI"
],
"carrier_types": ["DOCOMO"
],
"interests": [0
],
"media_types": ["SMART_VIEW"
],
"channel_alias_labels": ["CR_JA_TOP"
],
"article_categories": ["JA_JP_ANIMAL"
],
"automated_targeting": {"age_unbreakable": false,
"gender_unbreakable": false,
"location_unbreakable": false,
"custom_audience_unbreakable": false,
"carrier_unbreakable": false,
"connection_type_unbreakable": false,
"os_version_unbreakable": false
}
},
"frequency_control": {"interval": "LAST_1_DAY",
"threshold": 0
},
"configured_status": "ACTIVE",
"dynamic_ads_config": {"targeting_type": "RETARGETING",
"recency_days": "LAST_1_DAY",
"product_set_id": 0
},
"campaign_id": 0,
"ad_group_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"has_any_video_ads": true,
"is_migrated_from_v1": true
}

List Ad Groups By Ad Account (Paginated)

Get a paginated list of ad group objects by ad account.

This endpoint returns ad groups with pagination support, including pagination metadata in the response.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id

required

integer <int64>

query Parameters

include_deleted	boolean (IncludeDeleted) Default: false If `true`, deleted Ad Groups are included in the response.
ad_group_ids	Array of integers <int64> [ 1 .. 100 ] items [ items <int64 > ] Filter the response by a target list of ad_group_ids
page_size	integer (PageSize) [ 1 .. 1000 ] Default: 1000 Example: page_size=100 The number of objects to return per page. The maximum page size is 1000 and the default is 1000.
page	integer (Page) >= 1 Default: 1 Example: page=2 The page of data to retrieve. The first page starts at 1, and each page will contain at most `page_size` items (the last page may contain less). To get the maximum available page number, refer to the `total_pages` field in the response's `pagination` object.

header Parameters

Accept-Language

string (AcceptLanguage)

Example: en-US

Controls the language of response text.

Responses

Response samples

Content type

application/json

{"data": [{"name": "string",
"audience": {"ages": ["AGE_UNDER_20"
],
"genders": ["MALE"
],
"locations": [0
],
"zip_codes": ["10001",
"10002"
],
"hyper_location_config": {"user_segment": "RESIDENT_ONLY",
"location_segments": [{"segment_area_type": "PIN_WITH_RADIUS",
"fixed_area_info": {"location_id": 0
},
"location_segment_id": 0,
"pin_with_radius_info": {"address": "string",
"label": "string",
"latitude": "string",
"longitude": "string",
"radius_in_meters": 0
}
},
{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70150
}
},
{"segment_area_type": "PIN_WITH_RADIUS",
"pin_with_radius_info": {"address": "福島県伊達郡川俣町山木屋キトウスズ山２",
"latitude": "37.59268044952155",
"longitude": "140.63639730916015",
"radius_in_meters": 3000,
"label": "My Label"
}
}
]
},
"operating_system": {"type": "IOS",
"since_version": "string"
},
"custom_audiences": {"include": [0
],
"exclude": [0
]
},
"connection_types": ["WIFI"
],
"carrier_types": ["DOCOMO"
],
"interests": [0
],
"media_types": ["SMART_VIEW"
],
"channel_alias_labels": ["CR_JA_TOP"
],
"article_categories": ["JA_JP_ANIMAL"
],
"automated_targeting": {"age_unbreakable": false,
"gender_unbreakable": false,
"location_unbreakable": false,
"custom_audience_unbreakable": false,
"carrier_unbreakable": false,
"connection_type_unbreakable": false,
"os_version_unbreakable": false
}
},
"frequency_control": {"interval": "LAST_1_DAY",
"threshold": 0
},
"configured_status": "ACTIVE",
"dynamic_ads_config": {"targeting_type": "RETARGETING",
"recency_days": "LAST_1_DAY",
"product_set_id": 0
},
"campaign_id": 0,
"ad_group_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"has_any_video_ads": true,
"is_migrated_from_v1": true
}
],
"pagination": {"page": 1,
"page_size": 100,
"total_pages": 10,
"total_objects": 987
}
}

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": {"ages": ["AGE_UNDER_20"
],
"genders": ["MALE"
],
"locations": [0
],
"zip_codes": ["10001",
"10002"
],
"hyper_location_config": {"user_segment": "RESIDENT_ONLY",
"location_segments": [{"segment_area_type": "PIN_WITH_RADIUS",
"fixed_area_info": {"location_id": 0
},
"location_segment_id": 0,
"pin_with_radius_info": {"address": "string",
"label": "string",
"latitude": "string",
"longitude": "string",
"radius_in_meters": 0
}
},
{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70150
}
},
{"segment_area_type": "PIN_WITH_RADIUS",
"pin_with_radius_info": {"address": "福島県伊達郡川俣町山木屋キトウスズ山２",
"latitude": "37.59268044952155",
"longitude": "140.63639730916015",
"radius_in_meters": 3000,
"label": "My Label"
}
}
]
},
"operating_system": {"type": "IOS",
"since_version": "string"
},
"custom_audiences": {"include": [0
],
"exclude": [0
]
},
"connection_types": ["WIFI"
],
"carrier_types": ["DOCOMO"
],
"interests": [0
],
"media_types": ["SMART_VIEW"
],
"channel_alias_labels": ["CR_JA_TOP"
],
"article_categories": ["JA_JP_ANIMAL"
],
"automated_targeting": {"age_unbreakable": false,
"gender_unbreakable": false,
"location_unbreakable": false,
"custom_audience_unbreakable": false,
"carrier_unbreakable": false,
"connection_type_unbreakable": false,
"os_version_unbreakable": false
}
},
"frequency_control": {"interval": "LAST_1_DAY",
"threshold": 0
},
"configured_status": "ACTIVE",
"dynamic_ads_config": {"targeting_type": "RETARGETING",
"recency_days": "LAST_1_DAY",
"product_set_id": 0
},
"campaign_id": 0,
"ad_group_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"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. Note: This field is not settable for US region ad accounts.
	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 (DynamicAdsConfigPatchSchema) The Configuration of the dynamic ads for PATCH requests. If campaign is for dynamic ads, this object is required.

Responses

Request samples

Payload

Content type

application/merge-patch+json

{"name": "string",
"configured_status": "ACTIVE",
"frequency_control": {"interval": "LAST_1_DAY",
"threshold": 0
},
"audience": {"ages": ["AGE_UNDER_20"
],
"genders": ["MALE"
],
"locations": [0
],
"zip_codes": ["10001",
"10002"
],
"hyper_location_config": {"user_segment": "RESIDENT_AND_VISITOR",
"location_segments": [{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70196
}
},
{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70150
}
},
{"segment_area_type": "PIN_WITH_RADIUS",
"pin_with_radius_info": {"address": "福島県伊達郡川俣町山木屋キトウスズ山２",
"latitude": "37.59268044952155",
"longitude": "140.63639730916015",
"radius_in_meters": 3000,
"label": "My Label"
}
}
]
},
"operating_system": {"type": "IOS",
"since_version": "string"
},
"custom_audiences": {"include": [0
],
"exclude": [0
]
},
"connection_types": ["WIFI"
],
"carrier_types": ["DOCOMO"
],
"interests": [0
],
"media_types": ["SMART_VIEW"
],
"channel_alias_labels": ["CR_JA_TOP"
],
"article_categories": ["JA_JP_ANIMAL"
],
"automated_targeting": {"age_unbreakable": false,
"gender_unbreakable": false,
"location_unbreakable": false,
"custom_audience_unbreakable": false,
"carrier_unbreakable": false,
"connection_type_unbreakable": false,
"os_version_unbreakable": false
}
},
"dynamic_ads_config": {"targeting_type": "RETARGETING",
"recency_days": "LAST_1_DAY"
}
}

Response samples

Content type

application/json

{"name": "string",
"audience": {"ages": ["AGE_UNDER_20"
],
"genders": ["MALE"
],
"locations": [0
],
"zip_codes": ["10001",
"10002"
],
"hyper_location_config": {"user_segment": "RESIDENT_ONLY",
"location_segments": [{"segment_area_type": "PIN_WITH_RADIUS",
"fixed_area_info": {"location_id": 0
},
"location_segment_id": 0,
"pin_with_radius_info": {"address": "string",
"label": "string",
"latitude": "string",
"longitude": "string",
"radius_in_meters": 0
}
},
{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70150
}
},
{"segment_area_type": "PIN_WITH_RADIUS",
"pin_with_radius_info": {"address": "福島県伊達郡川俣町山木屋キトウスズ山２",
"latitude": "37.59268044952155",
"longitude": "140.63639730916015",
"radius_in_meters": 3000,
"label": "My Label"
}
}
]
},
"operating_system": {"type": "IOS",
"since_version": "string"
},
"custom_audiences": {"include": [0
],
"exclude": [0
]
},
"connection_types": ["WIFI"
],
"carrier_types": ["DOCOMO"
],
"interests": [0
],
"media_types": ["SMART_VIEW"
],
"channel_alias_labels": ["CR_JA_TOP"
],
"article_categories": ["JA_JP_ANIMAL"
],
"automated_targeting": {"age_unbreakable": false,
"gender_unbreakable": false,
"location_unbreakable": false,
"custom_audience_unbreakable": false,
"carrier_unbreakable": false,
"connection_type_unbreakable": false,
"os_version_unbreakable": false
}
},
"frequency_control": {"interval": "LAST_1_DAY",
"threshold": 0
},
"configured_status": "ACTIVE",
"dynamic_ads_config": {"targeting_type": "RETARGETING",
"recency_days": "LAST_1_DAY",
"product_set_id": 0
},
"campaign_id": 0,
"ad_group_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"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": {"type": "UNAUTHORIZED",
"message": "string",
"retriable": true
}
}

Get ad groups by custom audience.

Get an array of adgroups that use the specified custom audience for targeting.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id required	integer <int64>
custom_audience_id required	integer <int64> The ID of the custom audience to retrieve ad groups for.

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": [{"name": "string",
"audience": {"ages": ["AGE_UNDER_20"
],
"genders": ["MALE"
],
"locations": [0
],
"zip_codes": ["10001",
"10002"
],
"hyper_location_config": {"user_segment": "RESIDENT_ONLY",
"location_segments": [{"segment_area_type": "PIN_WITH_RADIUS",
"fixed_area_info": {"location_id": 0
},
"location_segment_id": 0,
"pin_with_radius_info": {"address": "string",
"label": "string",
"latitude": "string",
"longitude": "string",
"radius_in_meters": 0
}
},
{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70150
}
},
{"segment_area_type": "PIN_WITH_RADIUS",
"pin_with_radius_info": {"address": "福島県伊達郡川俣町山木屋キトウスズ山２",
"latitude": "37.59268044952155",
"longitude": "140.63639730916015",
"radius_in_meters": 3000,
"label": "My Label"
}
}
]
},
"operating_system": {"type": "IOS",
"since_version": "string"
},
"custom_audiences": {"include": [0
],
"exclude": [0
]
},
"connection_types": ["WIFI"
],
"carrier_types": ["DOCOMO"
],
"interests": [0
],
"media_types": ["SMART_VIEW"
],
"channel_alias_labels": ["CR_JA_TOP"
],
"article_categories": ["JA_JP_ANIMAL"
],
"automated_targeting": {"age_unbreakable": false,
"gender_unbreakable": false,
"location_unbreakable": false,
"custom_audience_unbreakable": false,
"carrier_unbreakable": false,
"connection_type_unbreakable": false,
"os_version_unbreakable": false
}
},
"frequency_control": {"interval": "LAST_1_DAY",
"threshold": 0
},
"configured_status": "ACTIVE",
"dynamic_ads_config": {"targeting_type": "RETARGETING",
"recency_days": "LAST_1_DAY",
"product_set_id": 0
},
"campaign_id": 0,
"ad_group_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"has_any_video_ads": true,
"is_migrated_from_v1": true
}
]
}

ad

List Ads By Ad Group (Paginated)

Get a paginated list of ad objects under a specified ad group.

This endpoint returns ads with pagination support, including pagination metadata in the response.

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.
page_size	integer (PageSize) [ 1 .. 1000 ] Default: 1000 Example: page_size=100 The number of objects to return per page. The maximum page size is 1000 and the default is 1000.
page	integer (Page) >= 1 Default: 1 Example: page=2 The page of data to retrieve. The first page starts at 1, and each page will contain at most `page_size` items (the last page may contain less). To get the maximum available page number, refer to the `total_pages` field in the response's `pagination` object.

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": [{"name": "string",
"landing_page_url": "string",
"cta_label": "BOOK_NOW",
"configured_status": "ACTIVE",
"impression_measurement": {"vendor_type": "DAR",
"measurement_url": "https://example.com"
},
"url_tracking_parameters": "utm_source=smartnews&utm_medium=display&cp_id={campaign_id}",
"is_price_label_enabled": null,
"ad_id": 0,
"click_destination_type": "WEB_VIEW",
"moderation_status": "NOT_REVIEWED",
"rejection_reasons": [{"policy": "医薬品、医薬部外品、医療機器",
"description": "[LP]医療関係者等の推薦にあたるためNG",
"url": "https://help-ads.smartnews.com/item-876/#2",
"element_type": {"object": "AD",
"field": "LANDING_PAGE_URL"
},
"element_id": 0
}
],
"submission_status": "BEFORE_SUBMISSION",
"creative": {"format": "IMAGE",
"creative_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"image_creative_info": {"headline": "stringstri",
"description": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"video_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"carousel_cards": [{"caption": "string",
"media_file": {"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": null,
"height": null,
"url": null,
"filesize": null,
"aspect_ratio_type": null,
"image_scale": null,
"created_at": null
},
"half": {"width": null,
"height": null,
"url": null,
"filesize": null,
"aspect_ratio_type": null,
"image_scale": null,
"created_at": null
},
"original": {"width": null,
"height": null,
"url": null,
"filesize": null,
"aspect_ratio_type": null,
"image_scale": null,
"created_at": null
}
},
"videos": {"high": {"width": null,
"height": null,
"url": null,
"length": null,
"filesize": null,
"aspect_ratio_type": null,
"video_quality": null,
"created_at": null
},
"middle": {"width": null,
"height": null,
"url": null,
"length": null,
"filesize": null,
"aspect_ratio_type": null,
"video_quality": null,
"created_at": null
},
"low": {"width": null,
"height": null,
"url": null,
"length": null,
"filesize": null,
"aspect_ratio_type": null,
"video_quality": null,
"created_at": null
},
"original": {"width": null,
"height": null,
"url": null,
"length": null,
"filesize": null,
"aspect_ratio_type": null,
"video_quality": null,
"created_at": null
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
}
]
},
"catalog_carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string"
},
"catalog_image_creative_info": {"sponsored_name": "string"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"is_migrated_from_v1": true
}
],
"pagination": {"page": 1,
"page_size": 100,
"total_pages": 10,
"total_objects": 987
}
}

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`. WEB_VIEW BROWSER The API will return a Validation Error if the field doesn't follow the below rules: URL format should follow the RFC 3986 spec All characters should be escaped accordingly, except macro parameters. Only http and https are allowed protocols. 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 Note: This field is not settable for US region ad accounts.
url_tracking_parameters	string or null (UrlTrackingParameters) [ 1 .. 256 ] characters The parameters added to the landing page URL. This field is only supported for Dynamic Ads. The API will return a Validation Error if the field doesn't follow the below rules: All characters should be escaped accordingly, except macro parameters. 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}`
is_price_label_enabled	boolean or null (PriceLabelEnabled) Default: null If `true`, show a price label on the ad. Otherwise, do not show. This field is required when the parent campaign has `is_dynamic_ads` set to `true` and ad's creative is of CATALOG_CAROUSEL format type. Otherwise, this field is not settable.
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

Payload

Content type

application/json

{"name": "string",
"landing_page_url": "string",
"cta_label": "BOOK_NOW",
"configured_status": "ACTIVE",
"impression_measurement": {"vendor_type": "DAR",
"measurement_url": "https://example.com"
},
"url_tracking_parameters": "utm_source=smartnews&utm_medium=display&cp_id={campaign_id}",
"is_price_label_enabled": null,
"creative": {"format": "IMAGE",
"image_creative_info": {"headline": "stringstri",
"description": "stringstri",
"sponsored_name": "string",
"media_file_ids": [0
]
},
"video_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"media_file_ids": [0
]
},
"carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"carousel_cards": [{"caption": "string",
"media_file_id": 0
},
{"caption": "string",
"media_file_id": 0
},
{"caption": "string",
"media_file_id": 0
}
]
},
"catalog_carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string"
},
"catalog_image_creative_info": {"sponsored_name": "string"
}
}
}

Response samples

Content type

application/json

{"name": "string",
"landing_page_url": "string",
"cta_label": "BOOK_NOW",
"configured_status": "ACTIVE",
"impression_measurement": {"vendor_type": "DAR",
"measurement_url": "https://example.com"
},
"url_tracking_parameters": "utm_source=smartnews&utm_medium=display&cp_id={campaign_id}",
"is_price_label_enabled": null,
"ad_id": 0,
"click_destination_type": "WEB_VIEW",
"moderation_status": "NOT_REVIEWED",
"rejection_reasons": [{"policy": "医薬品、医薬部外品、医療機器",
"description": "[LP]医療関係者等の推薦にあたるためNG",
"url": "https://help-ads.smartnews.com/item-876/#2",
"element_type": {"object": "AD",
"field": "LANDING_PAGE_URL"
},
"element_id": 0
}
],
"submission_status": "BEFORE_SUBMISSION",
"creative": {"format": "IMAGE",
"creative_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"image_creative_info": {"headline": "stringstri",
"description": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"video_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"carousel_cards": [{"caption": "string",
"media_file": {"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
}
]
},
"catalog_carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string"
},
"catalog_image_creative_info": {"sponsored_name": "string"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"is_migrated_from_v1": true
}

List Ads By Ad Account (Paginated)

Get a paginated list of ad objects by ad account.

This endpoint returns ads with pagination support, including pagination metadata in the response.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id

required

integer <int64>

query Parameters

include_deleted	boolean (IncludeDeleted) Default: false Boolean flag for including deleted ads in the response.
ad_ids	Array of integers <int64> [ 1 .. 100 ] items [ items <int64 > ] Filter the response by a target list of ad_id
page_size	integer (PageSize) [ 1 .. 1000 ] Default: 1000 Example: page_size=100 The number of objects to return per page. The maximum page size is 1000 and the default is 1000.
page	integer (Page) >= 1 Default: 1 Example: page=2 The page of data to retrieve. The first page starts at 1, and each page will contain at most `page_size` items (the last page may contain less). To get the maximum available page number, refer to the `total_pages` field in the response's `pagination` object.

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": [{"name": "string",
"landing_page_url": "string",
"cta_label": "BOOK_NOW",
"configured_status": "ACTIVE",
"impression_measurement": {"vendor_type": "DAR",
"measurement_url": "https://example.com"
},
"url_tracking_parameters": "utm_source=smartnews&utm_medium=display&cp_id={campaign_id}",
"is_price_label_enabled": null,
"ad_id": 0,
"click_destination_type": "WEB_VIEW",
"moderation_status": "NOT_REVIEWED",
"rejection_reasons": [{"policy": "医薬品、医薬部外品、医療機器",
"description": "[LP]医療関係者等の推薦にあたるためNG",
"url": "https://help-ads.smartnews.com/item-876/#2",
"element_type": {"object": "AD",
"field": "LANDING_PAGE_URL"
},
"element_id": 0
}
],
"submission_status": "BEFORE_SUBMISSION",
"creative": {"format": "IMAGE",
"creative_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"image_creative_info": {"headline": "stringstri",
"description": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"video_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"carousel_cards": [{"caption": "string",
"media_file": {"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": null,
"height": null,
"url": null,
"filesize": null,
"aspect_ratio_type": null,
"image_scale": null,
"created_at": null
},
"half": {"width": null,
"height": null,
"url": null,
"filesize": null,
"aspect_ratio_type": null,
"image_scale": null,
"created_at": null
},
"original": {"width": null,
"height": null,
"url": null,
"filesize": null,
"aspect_ratio_type": null,
"image_scale": null,
"created_at": null
}
},
"videos": {"high": {"width": null,
"height": null,
"url": null,
"length": null,
"filesize": null,
"aspect_ratio_type": null,
"video_quality": null,
"created_at": null
},
"middle": {"width": null,
"height": null,
"url": null,
"length": null,
"filesize": null,
"aspect_ratio_type": null,
"video_quality": null,
"created_at": null
},
"low": {"width": null,
"height": null,
"url": null,
"length": null,
"filesize": null,
"aspect_ratio_type": null,
"video_quality": null,
"created_at": null
},
"original": {"width": null,
"height": null,
"url": null,
"length": null,
"filesize": null,
"aspect_ratio_type": null,
"video_quality": null,
"created_at": null
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
}
]
},
"catalog_carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string"
},
"catalog_image_creative_info": {"sponsored_name": "string"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"is_migrated_from_v1": true
}
],
"pagination": {"page": 1,
"page_size": 100,
"total_pages": 10,
"total_objects": 987
}
}

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": {"vendor_type": "DAR",
"measurement_url": "https://example.com"
},
"url_tracking_parameters": "utm_source=smartnews&utm_medium=display&cp_id={campaign_id}",
"is_price_label_enabled": null,
"ad_id": 0,
"click_destination_type": "WEB_VIEW",
"moderation_status": "NOT_REVIEWED",
"rejection_reasons": [{"policy": "医薬品、医薬部外品、医療機器",
"description": "[LP]医療関係者等の推薦にあたるためNG",
"url": "https://help-ads.smartnews.com/item-876/#2",
"element_type": {"object": "AD",
"field": "LANDING_PAGE_URL"
},
"element_id": 0
}
],
"submission_status": "BEFORE_SUBMISSION",
"creative": {"format": "IMAGE",
"creative_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"image_creative_info": {"headline": "stringstri",
"description": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"video_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"carousel_cards": [{"caption": "string",
"media_file": {"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
}
]
},
"catalog_carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string"
},
"catalog_image_creative_info": {"sponsored_name": "string"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"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`. WEB_VIEW BROWSER The API will return a Validation Error if the field doesn't follow the below rules: URL format should follow the RFC 3986 spec All characters should be escaped accordingly, except macro parameters. Only http and https are allowed protocols. 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 Note: This field is not settable for US region ad accounts.
is_price_label_enabled	boolean or null (PriceLabelEnabled) Default: null If `true`, show a price label on the ad. Otherwise, do not show. This field is required when the parent campaign has `is_dynamic_ads` set to `true` and ad's creative is of CATALOG_CAROUSEL format type. Otherwise, this field is not settable.

Responses

Request samples

Payload

Content type

application/merge-patch+json

{"name": "string",
"configured_status": "ACTIVE",
"landing_page_url": "string",
"cta_label": "BOOK_NOW",
"submission_status": "BEFORE_SUBMISSION",
"creative": {"image_creative_info": {"headline": "stringstri",
"description": "stringstri",
"sponsored_name": "string",
"media_file_ids": [0
]
},
"video_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"media_file_ids": [0
]
},
"carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"carousel_cards": [{"caption": "string",
"media_file_id": 0
},
{"caption": "string",
"media_file_id": 0
},
{"caption": "string",
"media_file_id": 0
}
]
},
"catalog_carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string"
},
"catalog_image_creative_info": {"sponsored_name": "string"
}
},
"impression_measurement": {"vendor_type": "DAR",
"measurement_url": "https://example.com"
},
"is_price_label_enabled": null
}

Response samples

Content type

application/json

{"name": "string",
"landing_page_url": "string",
"cta_label": "BOOK_NOW",
"configured_status": "ACTIVE",
"impression_measurement": {"vendor_type": "DAR",
"measurement_url": "https://example.com"
},
"url_tracking_parameters": "utm_source=smartnews&utm_medium=display&cp_id={campaign_id}",
"is_price_label_enabled": null,
"ad_id": 0,
"click_destination_type": "WEB_VIEW",
"moderation_status": "NOT_REVIEWED",
"rejection_reasons": [{"policy": "医薬品、医薬部外品、医療機器",
"description": "[LP]医療関係者等の推薦にあたるためNG",
"url": "https://help-ads.smartnews.com/item-876/#2",
"element_type": {"object": "AD",
"field": "LANDING_PAGE_URL"
},
"element_id": 0
}
],
"submission_status": "BEFORE_SUBMISSION",
"creative": {"format": "IMAGE",
"creative_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"image_creative_info": {"headline": "stringstri",
"description": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"video_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"media_files": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
]
},
"carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string",
"carousel_cards": [{"caption": "string",
"media_file": {"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
}
]
},
"catalog_carousel_creative_info": {"headline": "stringstri",
"sponsored_name": "string"
},
"catalog_image_creative_info": {"sponsored_name": "string"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"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": {"type": "UNAUTHORIZED",
"message": "string",
"retriable": true
}
}

media-file

List Media Files

Get a paginated list of media files under the specified ad account.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id

required

integer <int64>

query Parameters

query	string [ 1 .. 256 ] characters Search query string. Filters media files whose `file_name` contains this value (case-insensitive).
media_type required	string (MediaType) Enum: "IMAGE" "VIDEO" Filter by media type.
min_width	integer >= 1 Minimum width in pixels. Only media files with `width >= min_width` will be returned.
min_height	integer >= 1 Minimum height in pixels. Only media files with `height >= min_height` will be returned.
aspect_ratio_type	string (AspectRatioType) Enum: "ASPECT_RATIO_1_1" "ASPECT_RATIO_6_5" "ASPECT_RATIO_16_9" "ASPECT_RATIO_191_100" Filter media files by the predefined aspect ratio. Applies to IMAGE media files. Only assets whose primary image has the specified `aspect_ratio_type` are returned.
sort	Array of strings = 1 items [^created_at:(asc\|desc)$] Default: "created_at:desc" Example: sort=created_at:desc Specify the sort order for the results. The format is `{field}:{order}` (e.g. `created_at:desc`). Only `created_at` is supported for now. Defaults to `created_at:desc`.
page_size	integer [ 1 .. 1000 ] Default: 100
page	integer (Page) >= 1 Default: 1 Example: page=2 The page of data to retrieve. The first page starts at 1, and each page will contain at most `page_size` items (the last page may contain less). To get the maximum available page number, refer to the `total_pages` field in the response's `pagination` object.

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": [{"media_file_id": 0,
"ad_account_id": 0,
"media_type": "IMAGE",
"file_name": "string",
"images": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"thumbnail_media_file_id": 0,
"created_at": "2019-08-24T14:15:22Z"
}
],
"pagination": {"page": 1,
"page_size": 100,
"total_pages": 10,
"total_objects": 987
}
}

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
GIF (animated GIF is not allowed)

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": {"full": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"half": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"image_scale": "FULL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"videos": {"high": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"middle": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"low": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
},
"original": {"width": 0,
"height": 0,
"url": "string",
"length": 0,
"filesize": 0,
"aspect_ratio_type": "ASPECT_RATIO_1_1",
"video_quality": "ORIGINAL",
"created_at": "2019-08-24T14:15:22Z"
}
},
"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

A sample of the JP Locations.

[{"location_id": 70149,
"ja": "北海道",
"en": "Hokkaido",
"children": [{"location_id": 70196,
"ja": "札幌市",
"en": "Sapporo"
},
{"location_id": 70197,
"ja": "函館市",
"en": "Hakodate"
}
]
}
]

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

[{"iab_interest_category_id": 100,
"iab_interest_category_name": "Food",
"display_name": {"en": "Food",
"ja": "食べ物"
},
"parent_iab_interest_category_id": 1
}
]

pixel

Get list of pixels which are linked to the ad_account_id.

Get list of pixels which are linked to the ad_account_id.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id

required

integer <int64> (AdAccountId)

Unique ID of the ad account.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"data": [{"user_id": 0,
"name": "string",
"pixel_tag_id": "71ccbe033ff6837c48e6c3c6",
"created_at": "2019-08-24T14:15:22Z",
"status": "EVENTS_RECEIVED",
"last_event_date_time": "2019-08-24T14:15:22Z"
}
]
}

Get the details of the pixel_tag_id linked to the ad_account_id.

It will return the details of the pixel_tag_id
The pixel_tag_id should be linked to ad_account_id, Otherwise returns 404

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id required	integer <int64> (AdAccountId) Unique ID of the ad account.
pixel_tag_id required	string (PixelTagId) Example: 71ccbe033ff6837c48e6c3c6 Unique ID of the pixel which is used in tracking scripts.

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"user_id": 0,
"name": "string",
"pixel_tag_id": "71ccbe033ff6837c48e6c3c6",
"created_at": "2019-08-24T14:15:22Z",
"status": "EVENTS_RECEIVED",
"last_event_date_time": "2019-08-24T14:15:22Z"
}

custom-audience

List custom audiences

Get a list of Custom Audiences for an ad account ID.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id

required

integer <int64> (AdAccountId)

Unique ID of the ad account.

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": [{"custom_audience_id": 0,
"web_activity_rules": [{"custom_audience_web_activity_rule_id": 0,
"pixel_tag_id": "71ccbe033ff6837c48e6c3c6",
"events": ["PURCHASE"
],
"urls": ["http://example.com"
],
"time_period": "LAST_7_DAYS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"ads_engagement_rules": [{"custom_audience_ads_engagement_rule_id": 0,
"ad_group_ids": [0
],
"action": "CLICK",
"time_period": "LAST_7_DAYS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"audience_id_list_rules": [{"custom_audience_audience_id_list_rule_id": 0,
"audience_id_list_file_id": 0,
"file_type": "ADID_SHA256",
"original_file_name": "my_list.csv",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"keyword_rules": [{"custom_audience_keyword_rule_id": 0,
"window": "LAST_3_DAYS",
"frequency": 1,
"keywords": ["string",
"string",
"string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"name": "My Custom Audience",
"type": "WEB_ACTIVITY",
"rules_combining_logic": "AND",
"result": {"availability_status": "IN_PROGRESS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"unique_audience_count": 0
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"configured_status": "ACTIVE"
}
]
}

Create a Custom Audience

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id

required

integer <int64> (AdAccountId)

Unique ID of the ad account.

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
required

name required	string (CustomAudienceSchemas_Name) [ 1 .. 255 ] characters The name of the custom audience. Please check this document for how the length is calculated.
type required	string (CustomAudienceRequestType) Enum: "WEB_ACTIVITY" "ADS_ENGAGEMENT" "AUDIENCE_ID_LIST_FILE" "KEYWORD" The type of the custom audience. Note: `KEYWORD` type is not available for US ad accounts.
rules_combining_logic required	string (RulesCombiningLogic) Enum: "AND" "OR" How the rules will be combined for this custom audience.
	Array of objects or null (WebActivityRuleCreationRequest) An array of web activity rules for this custom audience. It can only be specified when `type` is `WEB_ACTIVITY`.
	Array of objects or null (AdsEngagementRuleCreationRequest) An array of ads engagement rules for this custom audience. It can only be specified when `type` is `ADS_ENGAGEMENT`.
	Array of objects or null (AudienceIdListRuleCreationRequest) An array of id list rules for this custom audience. It can only be specified when `type` is `AUDIENCE_ID_LIST`.
	Array of objects or null (KeywordRuleCreationRequest) An array of keyword rules for this custom audience. It can only be specified when `type` is `KEYWORD`.
configured_status required	string (CustomAudienceConfiguredStatus) Enum: "ACTIVE" "PAUSED" "DELETED" `ACTIVE`: The audience will be updated periodically based on the latest data. `PAUSED`: The audience will not be updated until reactivated. `DELETED`: The audience is deleted and cannot be used in Ad Group targeting.

Responses

Request samples

Payload

Content type

application/json

{"name": "My Custom Audience",
"type": "WEB_ACTIVITY",
"rules_combining_logic": "AND",
"web_activity_rules": [{"pixel_tag_id": "71ccbe033ff6837c48e6c3c6",
"events": ["PURCHASE"
],
"urls": ["http://example.com"
],
"time_period": "LAST_7_DAYS"
}
],
"ads_engagement_rules": [{"ad_group_ids": [0
],
"action": "CLICK",
"time_period": "LAST_7_DAYS"
}
],
"audience_id_list_rules": [{"audience_id_list_file_id": 0
}
],
"keyword_rules": [{"window": "LAST_3_DAYS",
"frequency": 1,
"keywords": ["string",
"string",
"string"
]
}
],
"configured_status": "ACTIVE"
}

Response samples

Content type

application/json

{"custom_audience_id": 0,
"web_activity_rules": [{"custom_audience_web_activity_rule_id": 0,
"pixel_tag_id": "71ccbe033ff6837c48e6c3c6",
"events": ["PURCHASE"
],
"urls": ["http://example.com"
],
"time_period": "LAST_7_DAYS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"ads_engagement_rules": [{"custom_audience_ads_engagement_rule_id": 0,
"ad_group_ids": [0
],
"action": "CLICK",
"time_period": "LAST_7_DAYS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"audience_id_list_rules": [{"custom_audience_audience_id_list_rule_id": 0,
"audience_id_list_file_id": 0,
"file_type": "ADID_SHA256",
"original_file_name": "my_list.csv",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"keyword_rules": [{"custom_audience_keyword_rule_id": 0,
"window": "LAST_3_DAYS",
"frequency": 1,
"keywords": ["string",
"string",
"string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"name": "My Custom Audience",
"type": "WEB_ACTIVITY",
"rules_combining_logic": "AND",
"result": {"availability_status": "IN_PROGRESS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"unique_audience_count": 0
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"configured_status": "ACTIVE"
}

Get a Custom Audience

Get a single custom audience by ID.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id required	integer <int64> (AdAccountId) Unique ID of the ad account.
custom_audience_id required	integer <int64> Unique ID of the custom audience

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

{"custom_audience_id": 0,
"web_activity_rules": [{"custom_audience_web_activity_rule_id": 0,
"pixel_tag_id": "71ccbe033ff6837c48e6c3c6",
"events": ["PURCHASE"
],
"urls": ["http://example.com"
],
"time_period": "LAST_7_DAYS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"ads_engagement_rules": [{"custom_audience_ads_engagement_rule_id": 0,
"ad_group_ids": [0
],
"action": "CLICK",
"time_period": "LAST_7_DAYS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"audience_id_list_rules": [{"custom_audience_audience_id_list_rule_id": 0,
"audience_id_list_file_id": 0,
"file_type": "ADID_SHA256",
"original_file_name": "my_list.csv",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"keyword_rules": [{"custom_audience_keyword_rule_id": 0,
"window": "LAST_3_DAYS",
"frequency": 1,
"keywords": ["string",
"string",
"string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"name": "My Custom Audience",
"type": "WEB_ACTIVITY",
"rules_combining_logic": "AND",
"result": {"availability_status": "IN_PROGRESS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"unique_audience_count": 0
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"configured_status": "ACTIVE"
}

Update a Custom Audience

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id required	integer <int64> (AdAccountId) Unique ID of the ad account.
custom_audience_id required	integer <int64> Unique id of the custom audience

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
required

name	string (CustomAudienceSchemas_Name) [ 1 .. 255 ] characters The name of the custom audience. Please check this document for how the length is calculated.
rules_combining_logic	string (RulesCombiningLogic) Enum: "AND" "OR" How the rules will be combined for this custom audience.
	Array of objects or null (WebActivityRulePatchRequest) An array of web activity rules for this custom audience. It can only be specified when `type` is `WEB_ACTIVITY`. See the CustomAudiencePatchRequest description for how to update rules.
	Array of objects or null (AdsEngagementRulePatchRequest) An array of ads engagement rules for this custom audience. It can only be specified when `type` is `ADS_ENGAGEMENT`. See the CustomAudiencePatchRequest description for how to update rules.
	Array of objects or null (AudienceIdListRulePatchRequest) An array of id list rules for this custom audience. It can only be specified when `type` is `AUDIENCE_ID_LIST`. See the CustomAudiencePatchRequest description for how to update rules.
	Array of objects or null (KeywordRulePatchRequest) An array of keyword rules for this custom audience. It can only be specified when `type` is `KEYWORD`. See the CustomAudiencePatchRequest description for how to update rules.
configured_status	string (CustomAudienceConfiguredStatus) Enum: "ACTIVE" "PAUSED" "DELETED" `ACTIVE`: The audience will be updated periodically based on the latest data. `PAUSED`: The audience will not be updated until reactivated. `DELETED`: The audience is deleted and cannot be used in Ad Group targeting.

Responses

Request samples

Payload

Content type

application/json

{"name": "My Custom Audience",
"rules_combining_logic": "AND",
"web_activity_rules": [{"custom_audience_web_activity_rule_id": 0,
"pixel_tag_id": "71ccbe033ff6837c48e6c3c6",
"events": ["PURCHASE"
],
"urls": ["http://example.com"
],
"time_period": "LAST_7_DAYS"
}
],
"ads_engagement_rules": [{"custom_audience_ads_engagement_rule_id": 0,
"ad_group_ids": [0
],
"action": "CLICK",
"time_period": "LAST_7_DAYS"
}
],
"audience_id_list_rules": [{"custom_audience_audience_id_list_rule_id": 0,
"audience_id_list_file_id": 0
}
],
"keyword_rules": [{"custom_audience_keyword_rule_id": 0,
"window": "LAST_3_DAYS",
"frequency": 1,
"keywords": ["string",
"string",
"string"
]
}
],
"configured_status": "ACTIVE"
}

Response samples

Content type

application/json

{"custom_audience_id": 0,
"web_activity_rules": [{"custom_audience_web_activity_rule_id": 0,
"pixel_tag_id": "71ccbe033ff6837c48e6c3c6",
"events": ["PURCHASE"
],
"urls": ["http://example.com"
],
"time_period": "LAST_7_DAYS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"ads_engagement_rules": [{"custom_audience_ads_engagement_rule_id": 0,
"ad_group_ids": [0
],
"action": "CLICK",
"time_period": "LAST_7_DAYS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"audience_id_list_rules": [{"custom_audience_audience_id_list_rule_id": 0,
"audience_id_list_file_id": 0,
"file_type": "ADID_SHA256",
"original_file_name": "my_list.csv",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"keyword_rules": [{"custom_audience_keyword_rule_id": 0,
"window": "LAST_3_DAYS",
"frequency": 1,
"keywords": ["string",
"string",
"string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"name": "My Custom Audience",
"type": "WEB_ACTIVITY",
"rules_combining_logic": "AND",
"result": {"availability_status": "IN_PROGRESS",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"unique_audience_count": 0
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"configured_status": "ACTIVE"
}

Delete a Custom Audience

Delete a single custom audience by ID. NOTE: the custom audience must not be currently used in any Ad Group targeting.

Remove the custom audience from all Ad Group targeting before attempting to delete it.

Use the GET ad_accounts/{ad_account_id}/custom_audiences/{custom_audience_id}/ad_groups endpoint to determine which ad groups are currently using the custom audience.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id required	integer <int64> (AdAccountId) Unique ID of the ad account.
custom_audience_id required	integer <int64> Unique id of the custom audience

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": {"type": "UNAUTHORIZED",
"message": "string",
"retriable": true
}
}

Get ad groups by custom audience.

Get an array of adgroups that use the specified custom audience for targeting.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id required	integer <int64>
custom_audience_id required	integer <int64> The ID of the custom audience to retrieve ad groups for.

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": [{"name": "string",
"audience": {"ages": ["AGE_UNDER_20"
],
"genders": ["MALE"
],
"locations": [0
],
"zip_codes": ["10001",
"10002"
],
"hyper_location_config": {"user_segment": "RESIDENT_ONLY",
"location_segments": [{"segment_area_type": "PIN_WITH_RADIUS",
"fixed_area_info": {"location_id": 0
},
"location_segment_id": 0,
"pin_with_radius_info": {"address": "string",
"label": "string",
"latitude": "string",
"longitude": "string",
"radius_in_meters": 0
}
},
{"segment_area_type": "FIXED_AREA",
"fixed_area_info": {"location_id": 70150
}
},
{"segment_area_type": "PIN_WITH_RADIUS",
"pin_with_radius_info": {"address": "福島県伊達郡川俣町山木屋キトウスズ山２",
"latitude": "37.59268044952155",
"longitude": "140.63639730916015",
"radius_in_meters": 3000,
"label": "My Label"
}
}
]
},
"operating_system": {"type": "IOS",
"since_version": "string"
},
"custom_audiences": {"include": [0
],
"exclude": [0
]
},
"connection_types": ["WIFI"
],
"carrier_types": ["DOCOMO"
],
"interests": [0
],
"media_types": ["SMART_VIEW"
],
"channel_alias_labels": ["CR_JA_TOP"
],
"article_categories": ["JA_JP_ANIMAL"
],
"automated_targeting": {"age_unbreakable": false,
"gender_unbreakable": false,
"location_unbreakable": false,
"custom_audience_unbreakable": false,
"carrier_unbreakable": false,
"connection_type_unbreakable": false,
"os_version_unbreakable": false
}
},
"frequency_control": {"interval": "LAST_1_DAY",
"threshold": 0
},
"configured_status": "ACTIVE",
"dynamic_ads_config": {"targeting_type": "RETARGETING",
"recency_days": "LAST_1_DAY",
"product_set_id": 0
},
"campaign_id": 0,
"ad_group_id": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"parent": {"id": 0,
"type": "CAMPAIGN",
"name": "string",
"objective": "TRAFFIC",
"optimization_event": "PURCHASE",
"ready_for_delivery": true,
"parent": { }
},
"delivery_status": {"status": "DELETED",
"reason": "CAMPAIGN_DELETED",
"description": "string"
},
"has_any_video_ads": true,
"is_migrated_from_v1": true
}
]
}

Create a audience ID list file.

Authorizations:

ApiKeyAuth

path Parameters

ad_account_id

required

integer <int64>

header Parameters

Accept-Language

string

Request Body schema: multipart/form-data

original_file_name required	string (OriginalFileName) [ 1 .. 255 ] characters Filename of the audience ID list file.
file_type required	string (FileType) Value: "ADID_SHA256" The type of the audience ID list file.
audience_id_list_file required	string <binary> The file that contains the audience ID list. The file should be in CSV/TXT format. The filesize must be ≥ 5KB and ≤ 100MB. Please visit this help page for more details about the file contents.

Responses

Response samples

Content type

application/json

{"audience_id_list_file_id": 0,
"ad_account_id": 0,
"original_file_name": "my_list.csv",
"file_type": "ADID_SHA256",
"created_at": "2019-08-24T14:15:22Z"
}

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": [{"ad_account_id": 0,
"ad_account_name": "string",
"owner_business_id": 0,
"owner_business_name": "string",
"roles": ["ADS_ADVERTISER_OPERATOR"
]
}
]
}

Media Type	Required Fields
IMAGE	`images`
VIDEO	`images`, `videos`

SmartNews Marketing API (3.0.0)

Previous Versions

About This Document

Contact Information

Change Log

How to Upgrade From Marketing API v2 to v3

Base URL

Rate Limit

Authentication / Authorization

About Currency Units

Simultaneous Update Operation Limitation

oauth

Generate an access token

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Response samples

Revoke all active access tokens for the developer application

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Response samples

insights

Insights

Authorizations:

path Parameters

query Parameters

Layer Specific Metadata fields

Campaign

Ad Group

Ad

header Parameters

Responses

Response samples

Aggregated Insights

Authorizations:

path Parameters

query Parameters

header Parameters

Responses

Response samples

campaign

List Campaigns (Paginated)

Authorizations:

path Parameters

query Parameters

header Parameters

Responses

Response samples

Create a Campaign

Authorizations:

path Parameters

query Parameters

header Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Get a Campaign

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Update a Campaign

Authorizations:

path Parameters

header Parameters

Request Body schema: application/merge-patch+json

Responses

Request samples

Response samples

Delete a Campaign

Authorizations:

path Parameters

header Parameters

Responses

Response samples

ad-group

List Ad Groups By Campaign (Paginated)

Authorizations:

path Parameters

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/x-www-form-urlencoded
required