{ "openapi": "3.0.3", "info": { "version": "3.0.1", "title": "SmartNews Marketing API", "description": "# Previous Versions\n- SmartNews Marketing API (2.0.0): https://ads.smartnews.com/developers/deprecated/v2/index.html\n - **API v2 has been fully disabled.** All requests to `api/ma/v2/*` endpoints now return a `410 Gone` error. Please ensure that your system has been updated to use API v3. See [How to Upgrade From Marketing API v2 to v3](#section/How-to-Upgrade-From-Marketing-API-v2-to-v3).\n\n# About This Document\nThis 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.\n\nTo use the SmartNews Ads API, you must agree to the SmartNews Ads API Terms of Service.\n\n- **English Version:** https://ads.smartnews.com/developers/tos-en.html\n- **Japanese Reference Translation:** https://ads.smartnews.com/developers/tos-ja.html\n# Contact Information\n\nAPI Help Page:\n- (Ja) https://help-ads.smartnews.com/item-4207/\n- (En) https://help-ads.smartnews.com/linkonly/item-4442/\n\n**For inquiries:**\n\nFor the Japan region\n\nPlease contact us through the following link:\nhttps://smartnews-ads.zendesk.com/hc/ja/requests/new?ticket_form_id=&u=1723081408\n\n- **カテゴリ:** Select \"Standard Adsに関するお問い合わせ\"\n- **該当の項目:** Select \"APIの仕様・不具合について\"\n- **対象のAPI:** Select \"Marketing API\"\n\nFor the US region\n\nPlease contact us through the following link:\nhttps://business.smartnews.com/get-started-ads\n\n# Change Log\n\nJanuary 2026\n- Released Marketing API v3 version which requires pagination parameters for insights and list campaign/adgroup/ad endpoints.\n - See [How to Upgrade From Marketing API v2 to v3](#section/How-to-Upgrade-From-Marketing-API-v2-to-v3)\n - To access the old docs, visit https://ads.smartnews.com/developers/deprecated/v2/index.html\n - API v2 will be sunset on June 30, 2026 (JST). Please ensure that your system is updated to use API v3 by that date.\n- CSV format is now supported for insights v3.\n\nApril 2026\n- (catalog) Added new APIs for catalogs and productSets which are available for certain allowlisted developer app only.\n - In order to access the API, one developer app should be created with access to the adAccount for campaign management.\n - Please contact Customer Support with the developer app and business details to request access to the Catalog APIs.\n\nMay 2026\n- Added rate limit for OAuth token issuance endpoint (`generateAccessToken`): 5 requests per minute per developer app. Access tokens are valid for 24 hours and should be reused within that period.\n- Added new `channel_alias_labels` endpoint to retrieve channel alias label options for ad group targeting.\n- Increased the maximum `spending_limit_micro` for JP ad accounts from 1,000,000,000,000,000 to 10,000,000,000,000,000.\n\nJuly 2026\n- **API v2 has been fully disabled.** All requests to `api/ma/v2/*` endpoints now return a `410 Gone` error. If you have not yet migrated, please update your system to use API v3. See [How to Upgrade From Marketing API v2 to v3](#section/How-to-Upgrade-From-Marketing-API-v2-to-v3).\n\n# How to Upgrade From Marketing API v2 to v3\n- **Note: API v2 is now fully disabled. Any request to an `api/ma/v2/*` endpoint will return a `410 Gone` error. You must migrate to the equivalent `api/ma/v3/*` endpoint.**\n- The main change is pagination; affected endpoints are as follows:\n - `/api/ma/v3/ad_accounts/{ad_account_id}/insights/{layer}`\n - `/api/ma/v3/ad_accounts/{ad_account_id}/campaigns`\n - `/api/ma/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id}/ad_groups`\n - `/api/ma/v3/ad_accounts/{ad_account_id}/ad_groups`\n - `/api/ma/v3/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/ads`\n - `/api/ma/v3/ad_accounts/{ad_account_id}/ads`\n- For the above endpoints, `page_size` and `page` query parameters are added with default values.\n- 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).\n- 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.\n- For CSV, we recommend setting `remove_csv_header=true` for pages greater than 1. This allows you to easily join all pages to create the full CSV file.\n - CSV does not include the pagination summary. Please keep calling the endpoint until there are no rows returned in the response.\n\n# Base URL\nThe base URL for all API requests is `https://ads.smartnews.com/`.\n\nFor 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/`\n\n# Rate Limit\nRequests are limited per developer app ID. Making too many requests in a short time will result in a 429 error.\n\nIn this case, please wait a short time and retry the request again.\n\nCurrently the limits are as follows:\n\n- 10 GET requests per second\n- 10 POST/PATCH/DELETE requests per second\n- 5 OAuth token requests per minute (generateAccessToken endpoint)\n - Access tokens are valid for 24 hours. Please reuse the same token for multiple API requests within its validity period, rather than generating a new token for each request.\n\nNote: we do not guarantee these limits and they are subject to change, so we strongly recommend not relying on these limits but instead implementing retry logic\nbased on 429 error response.\n\n# Authentication / Authorization\nTo set the JWT token in the HTTP header based on the provided OpenAPI definition, please include the Authorization header with the following format:\n```\nAuthorization: Bearer \n```\nAccess tokens are generated using the OAuth API. Please refer to the [OAuth API](#tag/oauth) for more information.\n\n# About Currency Units\n\nThe SmartNews Ads Marketing API uses the `_micro` notation for monetary amounts, representing currency values as integers.\nExamples include `daily_budget_amount_micro` and `bid_amount_micro` in campaign level.\n\nThis integer representation multiplies the actual currency amount by 1,000,000.\n\nExamples:\n\n| Currency | API notation (micro) | Actual amount |\n-----------|----------------------|---------------|\n| USD | 1,500,000 | $1.50 USD |\n| USD | 2,500,000 | $2.50 USD |\n| JPY | 5,000,000 | ¥5 JPY |\n| JPY | 120,000,000 | ¥120 JPY |\n\nIn practice, when specifying monetary amounts via the API, you should use an integer value equal to 1,000,000 times the intended actual amount.\n\nAvailable currencies are set at the advertising account level.\n\n# Simultaneous Update Operation Limitation\n\nThe following applies to Campaign, AdGroup, Ad `POST`, `PATCH` and `DELETE` endpoints:\n\nThere are limitations on doing simultaneous operations on related objects (\"simultaneous\" means starting a second request before receiving a response from the first request).\n\nThe following cases are not allowed and will result in a `409 Conflict` error:\n\n- __Creating, updating or deleting multiple children of the same parent simultaneously.__\n - Example 1: Updating two Ads which both belong to the same Campaign at the same time.\n - Example 2: Creating an Ad and deleting another Ad which both belong to the same Campaign.\n - Example 3: Creating two AdGroups which both belong to the same Campaign.\n - Example 4: Creating an AdGroup and an Ad which both belong to the same Campaign.\n- __Creating, updating or deleting objects at the same time as its parent object.__\n - Example 1: Updating a Campaign and its child AdGroup at the same time.\n - Example 2: Updating an AdGroup and deleting one of its Ads at the same time.\n", "contact": { "name": "SmartNews Ads Support" } }, "servers": [ { "url": "https://ads.smartnews.com", "description": "Production" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "GenerateAccessTokenRequest": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "description": "The grant type of the request. It should be 'client_credentials'.", "example": "client_credentials" }, "client_id": { "type": "integer", "format": "int64", "description": "The client id(developer app id) of the developer app." }, "client_secret": { "type": "string", "description": "The client secret of the developer app. Client secret is a credential generated when the developer app is created." } } }, "GenerateAccessTokenResponse": { "type": "object", "required": [ "access_token", "expires_in", "token_type", "scope" ], "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64" }, "token_type": { "type": "string" }, "scope": { "type": "string" } }, "example": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", "expires_in": 86400, "token_type": "Bearer", "scope": "ads-manager" } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "retriable" ], "properties": { "message": { "type": "string" }, "retriable": { "type": "boolean" } } } } }, "RevokeAccessTokenRequest": { "type": "object", "required": [ "client_id", "client_secret" ], "properties": { "client_id": { "type": "integer", "format": "int64", "description": "The client id(developer app id) of the developer app." }, "client_secret": { "type": "string", "description": "The client secret of the developer app. Client secret is a credential generated when the developer app is created." } } }, "AcceptLanguage": { "type": "string", "description": "The language to use for system generated text within API responses.\n\nThe currently supported languages are English (`en`, `en-*`) and Japanese (`ja`, `ja-JP`)\n", "example": "en-US" }, "Layer": { "type": "string", "enum": [ "campaigns", "ad_groups", "ads" ], "x-enum-varnames": [ "CAMPAIGNS", "AD_GROUPS", "ADS" ] }, "FieldV3": { "type": "string", "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", "metrics_count_store_visit", "metrics_cvr_store_visit", "metrics_cpa_store_visit" ], "x-enum-varnames": [ "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", "METRICS_COUNT_STORE_VISIT", "METRICS_CVR_STORE_VISIT", "METRICS_CPA_STORE_VISIT" ] }, "BreakdownType": { "type": "string", "example": "age", "enum": [ "age", "gender", "age_and_gender", "prefecture", "city", "connection_type", "os", "device_type", "carrier_type", "state", "county", "hyper_location_segment" ], "x-enum-varnames": [ "AGE", "GENDER", "AGE_AND_GENDER", "PREFECTURE", "CITY", "CONNECTION_TYPE", "OS", "DEVICE_TYPE", "CARRIER_TYPE", "STATE", "COUNTY", "HYPER_LOCATION_SEGMENT" ] }, "BreakdownPeriod": { "type": "string", "example": "hour", "enum": [ "hour", "day" ], "x-enum-varnames": [ "HOUR", "DAY" ] }, "IncludeDeleted": { "type": "boolean", "default": false }, "MobileAppAttributionMode": { "type": "string", "enum": [ "all", "mmp_only" ], "x-enum-varnames": [ "ALL", "MMP_ONLY" ] }, "ClickAttributionWindow": { "type": "string", "enum": [ "days_30", "days_14", "days_7", "day_1" ], "x-enum-varnames": [ "DAYS_30", "DAYS_14", "DAYS_7", "DAY_1" ] }, "VimpAttributionWindow": { "type": "string", "enum": [ "day_1", "none" ], "x-enum-varnames": [ "DAY_1", "NONE" ] }, "Page": { "type": "integer", "minimum": 1, "default": 1, "example": 2, "description": "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).\n\nTo get the maximum available page number, refer to the `total_pages` field in the response's `pagination` object.\n" }, "SortParameter": { "type": "string", "description": "A sort parameter in the format `{field}:{order}`, where `field` is a value from `SortableField`\nand `order` is a value from `SortOrder`.\n", "pattern": "^[a-zA-Z_]+:(asc|desc)$", "example": "metrics_click:desc" }, "ObjectType": { "type": "string", "enum": [ "CAMPAIGN", "AD_GROUP", "AD" ], "description": "The type of object." }, "ConfiguredStatus": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED" ], "description": "The status of the object configured by an ad operator." }, "DeliveryStatus": { "type": "string", "enum": [ "DELETED", "PAUSED", "NOT_ELIGIBLE", "PENDING", "ENDED", "ELIGIBLE", "UNKNOWN", "DISABLED" ], "description": "The delivery status of the object determined by the system.\n\n| Delivery status | What it means |\n|-----------------|---------------|\n| DELETED | The object is deleted by an ad operator |\n| PAUSED | The object is paused by an ad operator |\n| NOT_ELIGIBLE | The object is configured to be active but is not delivered due to some conditions. Please check the `reason` or `description` field for more details |\n| PENDING | The object is configured to be active and will be delivered when certain conditions are met. Please check Please check the `reason` or `description` field for more details |\n| ENDED | The object is configured to be active but the campaign has ended |\n| ELIGIBLE | The object is configured to be active and is delivering ads |\n| UNKNOWN | The object is configured to be active but its delivery status is unknown |\n| DISABLED | The object is disabled because the business, account, or brand is disabled|\n" }, "DeliveryStatusReason": { "type": "string", "enum": [ "CAMPAIGN_DELETED", "CAMPAIGN_PAUSED", "NO_AD_GROUPS", "ALL_AD_GROUPS_PAUSED_OR_DELETED", "NO_ADS", "NO_SUBMITTED_ADS", "ALL_ADS_PAUSED_DELETED_OR_REJECTED", "NO_APPROVED_ADS", "CAMPAIGN_STARTS_IN_FUTURE", "CAMPAIGN_ENDED", "CAMPAIGN_OUTSIDE_DAILY_SCHEDULE", "NO_ACTIVE_APPROVED_ADS", "CAMPAIGN_ELIGIBLE", "AD_GROUP_DELETED", "AD_GROUP_PAUSED", "AD_GROUP_ELIGIBLE", "AD_DELETED", "AD_NOT_SUBMITTED", "AD_NOT_REVIEWED", "AD_REJECTED", "AD_PAUSED", "AD_ELIGIBLE", "CAMPAIGN_EXCEEDED_LIFETIME_SPENDING_LIMIT", "UNCONFIRMED", "BUSINESS_DISABLED", "AD_ACCOUNT_OR_BRAND_DISABLED", "BUSINESS_AND_AD_ACCOUNT_UNDER_REVIEW", "BUSINESS_NOT_APPROVED", "AD_ACCOUNT_NOT_APPROVED", "PAYMENT_METHOD_NOT_VERIFIED", "PAYMENT_METHOD_ISSUE", "PRODUCT_SET_NOT_READY", "STORE_SET_NOT_READY" ], "description": "An enum field for the reason the delivery status was determined.\n| Reason | Layers |\n|-------------------------------------------|-----------|\n| CAMPAIGN_DELETED | Campaign |\n| CAMPAIGN_PAUSED | Campaign, Ad group, Ad |\n| NO_AD_GROUPS | Campaign |\n| ALL_AD_GROUPS_PAUSED_OR_DELETED | Campaign |\n| NO_ADS | Campaign, Ad group |\n| NO_SUBMITTED_ADS | Campaign, Ad group |\n| ALL_ADS_PAUSED_DELETED_OR_REJECTED | Campaign, Ad group |\n| NO_APPROVED_ADS | Campaign, Ad group |\n| CAMPAIGN_STARTS_IN_FUTURE | Campaign, Ad group, Ad |\n| CAMPAIGN_ENDED | Campaign, Ad group, Ad |\n| CAMPAIGN_OUTSIDE_DAILY_SCHEDULE | Campaign |\n| NO_ACTIVE_APPROVED_ADS | Campaign, Ad group |\n| CAMPAIGN_ELIGIBLE | Campaign |\n| AD_GROUP_DELETED | Ad group |\n| AD_GROUP_PAUSED | Ad group, Ad |\n| AD_GROUP_ELIGIBLE | Ad group |\n| AD_DELETED | Ad |\n| AD_NOT_SUBMITTED | Ad |\n| AD_NOT_REVIEWED | Ad |\n| AD_REJECTED | Ad |\n| AD_PAUSED | Ad |\n| AD_ELIGIBLE | Ad |\n| CAMPAIGN_EXCEEDED_LIFETIME_SPENDING_LIMIT | Campaign, Ad group, Ad|\n| UNCONFIRMED | Campaign, Ad group, Ad|\n| BUSINESS_DISABLED | Campaign, Ad group, Ad |\n| AD_ACCOUNT_OR_BRAND_DISABLED | Campaign, Ad group, Ad |\n| BUSINESS_AND_AD_ACCOUNT_UNDER_REVIEW | Campaign, Ad group, Ad |\n| BUSINESS_NOT_APPROVED | Campaign, Ad group, Ad |\n| AD_ACCOUNT_NOT_APPROVED | Campaign, Ad group, Ad |\n| PAYMENT_METHOD_NOT_VERIFIED | Campaign, Ad group, Ad |\n| PAYMENT_METHOD_ISSUE | Campaign, Ad group, Ad |\n| PRODUCT_SET_NOT_READY | Campaign, Ad group, Ad |\n| STORE_SET_NOT_READY | Campaign, Ad group, Ad |\n" }, "DeliveryStatusObject": { "type": "object", "required": [ "status", "reason", "description" ], "properties": { "status": { "$ref": "#/components/schemas/DeliveryStatus" }, "reason": { "$ref": "#/components/schemas/DeliveryStatusReason" }, "description": { "type": "string", "description": "A localized human readable description of the reason. The language is controlled by the Accept-Language header in the request." } }, "description": "An Object that provides information about the delivery status of the campaign." }, "CommonMetadata": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the object." }, "created_at": { "type": "string", "format": "date-time", "description": "The date-time at which the object was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date-time at which the object was updated." }, "configured_status": { "$ref": "#/components/schemas/ConfiguredStatus" }, "delivery_status": { "$ref": "#/components/schemas/DeliveryStatusObject" }, "ad_account_name": { "type": "string" }, "ad_account_id": { "type": "integer", "format": "int64" } } }, "CampaignObjective": { "type": "string", "enum": [ "TRAFFIC", "SALES", "AWARENESS", "APP_PROMOTION" ], "description": "The objective of the campaign. It defines the business goal that customers pursue during a campaign.\\\n\nNote: Only `TRAFFIC` and `SALES` objectives are usable for US region ad account.\n" }, "OptimizationEvent": { "type": "string", "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" ], "nullable": true, "description": "Optimization event defines which conversion event the campaign is optimized for.\n\n| Optimization Goal | Available optimization events |\n|---------------------------|-------------------------------|\n| VIEWABLE_IMPRESSIONS | n/a |\n| CLICK | n/a |\n| 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 |\n| ROAS (Dynamic Ads only) | ADD_TO_CART, VIEW_CONTENT, PURCHASE, LEAD |\n| INSTALL | INSTALL |\n| INSTALL_WITH_IN_APP_EVENT | D1_RETENTION, PURCHASE, ADD_TO_CART, INITIATE_CHECKOUT, SUBMIT_FORM, SUBSCRIBE, COMPLETE_REGISTRATION, CONTACT, SIGN_UP, VIEW_CONTENT |\n\nNote:\n1. This field is not updatable when `ready_for_delivery` is `true`.\n2. `LEAD` event is only available for dynamic ads campaigns.\n3. For dynamic ads campaigns, only the following optimization events are supported:\n - `ADD_TO_CART`\n - `VIEW_CONTENT`\n - `PURCHASE`\n - `LEAD`\n" }, "OptimizationGoal": { "type": "string", "enum": [ "CLICKS", "OFFSITE_CONVERSIONS", "VIEWABLE_IMPRESSIONS", "INSTALL", "INSTALL_WITH_IN_APP_EVENT", "ROAS" ], "nullable": true, "description": "Optimization goal defines how the campaign is optimized.\n\nThis is required and configurable unless bidding strategy is `MANUAL`.\n\n| Objective | Bid Strategy | Available Optimization Goal |\n|---------------|----------------|-------------------------------------|\n| TRAFFIC | HIGHEST_VOLUME | CLICKS |\n| TRAFFIC | MANUAL | null |\n| SALES | HIGHEST_VOLUME | OFFSITE_CONVERSIONS, ROAS |\n| SALES | TARGET_COST | OFFSITE_CONVERSIONS |\n| AWARENESS | HIGHEST_VOLUME | VIEWABLE_IMPRESSIONS |\n| AWARENESS | MANUAL | null |\n| APP_PROMOTION | HIGHEST_VOLUME | INSTALL, INSTALL_WITH_IN_APP_EVENT |\n| APP_PROMOTION | TARGET_COST | INSTALL, INSTALL_WITH_IN_APP_EVENT |\n\nThis field is not updatable when `ready_for_delivery` is `true`.\nROAS is only allowed to Dynamic Ads campaign with SALES Objective.\n" }, "StartDateTime": { "type": "string", "format": "date-time", "example": "2046-01-07T16:02:00Z", "description": "The date-time at which the campaign is scheduled to start.\n\nMinimum value: ≥ today (ad account based timezone)\\\nMaximum value: `2099-12-31T23:58:00` (ad account based timezone)\n\nThe API rejects the value if seconds / milliseconds are specified except 0.\n\nThis field is not updatable when `ready_for_delivery` is `true`.\n" }, "EndDateTime": { "type": "string", "format": "date-time", "example": "2046-02-07T16:02:00Z", "nullable": true, "description": "The date-time at which the campaign is scheduled to end.\n\nMinimum value: max(`current_date_time`, `start_date_time`)\\\nMaximum value: `2099-12-31T23:59:00` (ad account based timezone)\n\nThe API rejects the value if seconds / milliseconds are specified except 0.\n\nThis field is nullable. When it is set to `null`, it means the campaign runs indefinitely.\n" }, "ReadyForDelivery": { "type": "boolean", "description": "A boolean flag that indicates whether a ready for delivery. The flag is immutable once it turned to `true`.\nWhen the flag is true, the following fields are not updatable anymore.\n1. `start_date_time`\n2. `billing_event`\n3. `optimization_goal`\n4. `optimization_event`\n5. `website_tracking_tag`\n6. `viewability_measurement`\n7. `app_promotion_info` (PatchAppPromotionInfo)\n" }, "HasAnyVideoAds": { "type": "boolean", "description": "Whether the ad object has any video ads, including those that have been deleted." }, "IsMigratedFromV1": { "type": "boolean", "description": "A boolean flag that indicates whether the object is migrated from v1." }, "IsLargeUnitAds": { "type": "boolean", "description": "A boolean flag that indicates whether ads from this campaign are displayed in the app using the large unit format.\n\nThis feature is only available when objective is `AWARENESS`.\n\nFor eligible ad accounts, this feature is also available when objective is `TRAFFIC` or `SALES`.\n\nThis field's value cannot be changed if the campaign already has 1 or more ads.\n\nNote: This field is not settable for US region ad accounts.\n" }, "CampaignMetadataV3": { "allOf": [ { "$ref": "#/components/schemas/CommonMetadata" }, { "type": "object", "properties": { "objective": { "$ref": "#/components/schemas/CampaignObjective" }, "optimization_event": { "$ref": "#/components/schemas/OptimizationEvent" }, "optimization_goal": { "$ref": "#/components/schemas/OptimizationGoal" }, "start_date_time": { "$ref": "#/components/schemas/StartDateTime" }, "end_date_time": { "$ref": "#/components/schemas/EndDateTime" }, "daily_budget_amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "123.4", "description": "The campaign's daily budget, represented in the ad account's currency.\n" }, "ready_for_delivery": { "$ref": "#/components/schemas/ReadyForDelivery" }, "has_any_video_ads": { "$ref": "#/components/schemas/HasAnyVideoAds" }, "is_migrated_from_v1": { "$ref": "#/components/schemas/IsMigratedFromV1" }, "is_large_unit_ads": { "$ref": "#/components/schemas/IsLargeUnitAds" }, "spending_limit": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "123.4", "description": "The campaign's spending limit, represented in the ad account's currency.\n" } } } ] }, "AdGroupMetadata": { "allOf": [ { "$ref": "#/components/schemas/CommonMetadata" }, { "type": "object", "properties": { "campaign_id": { "type": "integer", "format": "int64" }, "campaign_name": { "type": "string" }, "has_any_video_ads": { "$ref": "#/components/schemas/HasAnyVideoAds" }, "is_migrated_from_v1": { "$ref": "#/components/schemas/IsMigratedFromV1" } } } ] }, "AspectRatioType": { "type": "string", "enum": [ "ASPECT_RATIO_1_1", "ASPECT_RATIO_6_5", "ASPECT_RATIO_16_9", "ASPECT_RATIO_191_100" ], "description": "The predefined enums for the aspect ratio of images and videos." }, "Url": { "type": "string", "description": "The storage full url path of the image file." }, "AdThumbnail": { "type": "object", "required": [ "aspect_ratio_type", "url" ], "properties": { "aspect_ratio_type": { "$ref": "#/components/schemas/AspectRatioType" }, "url": { "$ref": "#/components/schemas/Url" } } }, "VideoSchemas_Url": { "type": "string", "description": "The full url path of the video file." }, "AdVideo": { "type": "object", "description": "Object containing the info of the `high` quality video generated by the uploaded video of an Video Ad. Null if the Ad is not a video ad.", "required": [ "aspect_ratio_type", "url" ], "properties": { "aspect_ratio_type": { "$ref": "#/components/schemas/AspectRatioType" }, "url": { "$ref": "#/components/schemas/VideoSchemas_Url" } } }, "ModerationStatus": { "type": "string", "enum": [ "NOT_REVIEWED", "APPROVED", "REJECTED" ], "description": "This is the moderation result of current Ad.\n" }, "SubmissionStatus": { "type": "string", "enum": [ "BEFORE_SUBMISSION", "SUBMITTED" ], "description": "This is the status of the ad to know whether our customers submit the ad to moderation or not.\n" }, "Format": { "type": "string", "enum": [ "IMAGE", "VIDEO", "CAROUSEL", "CATALOG_CAROUSEL", "CATALOG_IMAGE" ], "description": "The format of the Creative that defines the view attribution of an Ad.\n\nNote: `CAROUSEL`, `CATALOG_CAROUSEL`, and `CATALOG_IMAGE` are not settable for US region ad accounts.\n" }, "AdMetadata": { "allOf": [ { "$ref": "#/components/schemas/CommonMetadata" }, { "type": "object", "properties": { "thumbnails": { "description": "Image Ad: An array of objects containing the URL & Aspect Ratio Type of the `full` image scale only for each MediaFile contained in the Ad's creative.\\\nVideo Ad: An array of a single object containing the URL of the thumbnail of the video Ad's creative. The `aspect_ratio_type` is always `ASPECT_RATIO_16_9`.\n", "type": "array", "items": { "$ref": "#/components/schemas/AdThumbnail" } }, "video": { "$ref": "#/components/schemas/AdVideo" }, "moderation_status": { "$ref": "#/components/schemas/ModerationStatus" }, "submission_status": { "$ref": "#/components/schemas/SubmissionStatus" }, "campaign_id": { "type": "integer", "format": "int64" }, "campaign_name": { "type": "string" }, "ad_group_id": { "type": "integer", "format": "int64" }, "ad_group_name": { "type": "string" }, "is_migrated_from_v1": { "$ref": "#/components/schemas/IsMigratedFromV1" }, "ad_headline": { "type": "string" }, "ad_description": { "type": "string" }, "ad_creative_format": { "$ref": "#/components/schemas/Format" }, "ad_landing_page_url": { "type": "string" }, "ad_creative_media_file_aspect_ratio": { "type": "string", "description": "The aspect ratio of all the media file used in the ad creative.\nIf there are multiple media files, the aspect ratio is combined with comma e.g. `1.91:1, 1:1`.\n" } } } ] }, "MetadataV3": { "description": "Each field starting with `metadata_` specified in the fields parameter will be included as a field in this object.\n", "oneOf": [ { "$ref": "#/components/schemas/CampaignMetadataV3" }, { "$ref": "#/components/schemas/AdGroupMetadata" }, { "$ref": "#/components/schemas/AdMetadata" } ] }, "MetricsV3": { "description": "Each field starting with `metrics_` specified in the `fields` parameter will be included as a field in this object.\n\nNote: fields starting with `count_`, `cvr_`, `cpa_` are the metrics for events received via pixel postbacks.\n\nThe value following the prefix is the name of the event. For example, `count_purchase` is the number of Purchase events received.\n\n- `count_*`: The total number of events received.\n- `cvr_*`: The conversion rate for this event (number of events divided by number of clicks)\n- `cpa_*`: The average cost per event (budget spent divided by the number of events)\n", "type": "object", "properties": { "viewable_impression": { "type": "integer", "format": "int64", "description": "The number of times an ad was viewed by a user." }, "click": { "type": "integer", "format": "int64", "description": "The number of times an ad was clicked on by a user." }, "ctr": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "0.03", "description": "The click through rate (clicks divided by viewable impressions)." }, "cpc": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "1.2", "description": "The cost per click." }, "cpm": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34", "description": "The cost per 1,000 viewable impressions." }, "count_purchase": { "type": "integer", "format": "int64" }, "cvr_purchase": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_purchase": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_add_to_cart": { "type": "integer", "format": "int64" }, "cvr_add_to_cart": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_add_to_cart": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_initiate_checkout": { "type": "integer", "format": "int64" }, "cvr_initiate_checkout": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_initiate_checkout": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_submit_form": { "type": "integer", "format": "int64" }, "cvr_submit_form": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_submit_form": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_subscribe": { "type": "integer", "format": "int64" }, "cvr_subscribe": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_subscribe": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_complete_registration": { "type": "integer", "format": "int64" }, "cvr_complete_registration": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_complete_registration": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_contact": { "type": "integer", "format": "int64" }, "cvr_contact": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_contact": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_sign_up": { "type": "integer", "format": "int64" }, "cvr_sign_up": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_sign_up": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_view_content": { "type": "integer", "format": "int64" }, "cvr_view_content": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_view_content": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_add_payment_info": { "type": "integer", "format": "int64" }, "cvr_add_payment_info": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_add_payment_info": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_add_to_wish_list": { "type": "integer", "format": "int64" }, "cvr_add_to_wish_list": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_add_to_wish_list": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_visit_cart": { "type": "integer", "format": "int64" }, "cvr_visit_cart": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_visit_cart": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_customize_product": { "type": "integer", "format": "int64" }, "cvr_customize_product": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_customize_product": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_search": { "type": "integer", "format": "int64" }, "cvr_search": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_search": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_booking": { "type": "integer", "format": "int64" }, "cvr_booking": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_booking": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_download": { "type": "integer", "format": "int64" }, "cvr_download": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_download": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_start_trial": { "type": "integer", "format": "int64" }, "cvr_start_trial": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_start_trial": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_share": { "type": "integer", "format": "int64" }, "cvr_share": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_share": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_login": { "type": "integer", "format": "int64" }, "cvr_login": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_login": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_donate": { "type": "integer", "format": "int64" }, "cvr_donate": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_donate": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_find_location": { "type": "integer", "format": "int64" }, "cvr_find_location": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_find_location": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_time_spent": { "type": "integer", "format": "int64" }, "cvr_time_spent": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_time_spent": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_install": { "type": "integer", "format": "int64" }, "cvr_install": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_install": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_d1_retention": { "type": "integer", "format": "int64" }, "cvr_d1_retention": { "type": "string", "description": "For D1 retention rate, which is a special event for mobile only, it is calculated as (count of D1 retention event) / (count of installs)", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_d1_retention": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "budget_spent": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "123.4", "description": "The estimated total spending of your campaign, ad group, or ad." }, "lifetime_spent": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "123.4", "description": "The total budget spent for this object since creation regardless of any date/time filters." }, "spent_before_this_month": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "123.4", "description": "The total budget spent for this object through the end of last month." }, "video_views": { "type": "integer", "format": "int64", "description": "For video format ads, the number of times the video was viewed." }, "video_views_p25": { "type": "integer", "format": "int64", "description": "For video format ads, the number of times the video was viewed (at least 25% completed)." }, "video_views_p50": { "type": "integer", "format": "int64", "description": "For video format ads, the number of times the video was viewed (at least 50% completed)." }, "video_views_p75": { "type": "integer", "format": "int64", "description": "For video format ads, the number of times the video was viewed (at least 75% completed)." }, "video_views_p95": { "type": "integer", "format": "int64", "description": "For video format ads, the number of times the video was viewed (at least 95% completed)." }, "video_views_completed": { "type": "integer", "format": "int64", "description": "For video format ads, the number of times the video was viewed (fully completed)." }, "reach": { "description": "The number of unique users who saw your ads, defined as number of distinct devices that viewable impressions were delivered.", "type": "integer", "format": "int64" }, "frequency": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "0.2", "description": "The average number of times each user saw your ad. Number of unique users are defined as number of distinct devices that viewable impressions were delivered." }, "count_skan_install": { "type": "integer", "format": "int64", "description": "[Coming Soon] This feature is not yet available but will be supported soon.\n\nThe number of installs tracked by SKAdNetwork.\n" }, "cvr_skan_install": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "0.2", "description": "[Coming Soon] This feature is not yet available but will be supported soon.\n\nThe conversion rate for SKAdNetwork installs.\n" }, "cpa_skan_install": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "0.2", "description": "[Coming Soon] This feature is not yet available but will be supported soon.\n\nThe average cost per SKAdNetwork install.\n" }, "count_lead": { "type": "integer", "format": "int64" }, "cvr_lead": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_lead": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "count_store_visit": { "type": "integer", "format": "int64" }, "cvr_store_visit": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" }, "cpa_store_visit": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "2.34" } } }, "MetricsBreakdownV3": { "allOf": [ { "type": "object", "properties": { "segment_name": { "type": "string", "example": "21-24 & MALE", "description": "A breakdown type can encompass numerous segment labels. For instance, the age breakdown type might include\nsegment names such as \"under 20\" and \"21-24\", etc. with each being a string that gets translated according\nto the `Accept-Language`` header in the request.\n\nAPI will return metrics of certain segments based on the ad objects settings.\n 1. API will return metrics of only targeted segment names that were selected during creation of ad object\n 2. If no targeted segments were selected then API will return metrics of all segment names of that breakdown type.\n\nSince audience targeting is supported at ad_group layer, the set of segment names for each layer will be as follows.\n1. For a campaign (C) with ad_groups AG1 and AG2 with following targeted audiences\n AG1: (gender: female, age: under 20)\n AG2: (gender: female, age: 21-24)\n and\n when breakdown_type = gender\n then set of segment names will be (female)\n when breakdown_type = age\n then set of th segment names will be (under 20, 21-24)\n when breakdown_type = age_and_gender\n then set of segment names will be (female & under 20, female & 21-24)\n Basically, we do union of segment names of ad_group.\n2. For a ad_group, the segement names will be same as that of ad_group\n3. For a ad, the segement names will be same as its parent ad_group.\n" }, "period": { "type": "string", "example": "2023-11-28, 2023-11-28 12:00", "description": "It is a string to represent daily or hourly metrics for a requested time range.\nTime is already in Advertiser's timezone.\n" } } }, { "$ref": "#/components/schemas/MetricsV3" } ] }, "StoreSetId": { "type": "integer", "format": "int64", "description": "Identifier of the store set associated with this campaign for Store Visit measurement.\nStore sets are managed under Business Management.\n" }, "Parent": { "type": "object", "required": [ "id", "type", "name" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "The ID of the parent object." }, "type": { "type": "string", "enum": [ "CAMPAIGN", "AD_GROUP" ] }, "name": { "type": "string", "description": "The name of the object." }, "objective": { "$ref": "#/components/schemas/CampaignObjective" }, "optimization_event": { "$ref": "#/components/schemas/OptimizationEvent" }, "ready_for_delivery": { "$ref": "#/components/schemas/ReadyForDelivery" }, "store_set_id": { "$ref": "#/components/schemas/StoreSetId" }, "parent": { "type": "object", "description": "The parent of the parent. The properties are the same as parent (`id`, `name`, `type`, `objective`,\n`optimization_event` ,`ready_for_delivery` ,`store_set_id` ,`parent`)\n" } } }, "StandardInsightsItemV3": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/ObjectType" }, "id": { "description": "The ID of a object.", "type": "integer", "format": "int64" }, "metadata": { "$ref": "#/components/schemas/MetadataV3" }, "metrics": { "$ref": "#/components/schemas/MetricsV3" }, "metrics_breakdown": { "description": "This field is included when `breakdown_type` or `breakdown_period` parameter(s) are specified.\n", "type": "array", "items": { "$ref": "#/components/schemas/MetricsBreakdownV3" } }, "parent": { "$ref": "#/components/schemas/Parent" } } }, "PaginationInfoResponse": { "description": "An object describing pagination parameters for this response.\n", "type": "object", "required": [ "page", "page_size", "total_pages", "total_objects" ], "properties": { "page": { "type": "integer", "description": "The current page, where the first page starts at 1, and the last page corresponds to `total_pages`.", "example": 1 }, "page_size": { "type": "integer", "description": "The page size as specified in the request (note: the actual number of items in the response may be less if this is the last page of data.)", "example": 100 }, "total_pages": { "type": "integer", "description": "The total number of pages for this query.", "example": 10 }, "total_objects": { "type": "integer", "description": "The total number of objects that exist across all pages.", "example": 987 } } }, "InsightsResponseV3": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "description": "An array of objects containing fields for each ad object.", "type": "array", "items": { "$ref": "#/components/schemas/StandardInsightsItemV3" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoResponse" } } }, "BadRequestErrorExtension": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "BAD_REQUEST" ] } } }, "ErrorBase": { "type": "object", "required": [ "message", "retriable" ], "properties": { "message": { "type": "string" }, "retriable": { "type": "boolean" } } }, "BadRequestError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BadRequestErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "BadRequestErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/BadRequestError" } } }, "UnauthorizedErrorExtension": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "UNAUTHORIZED" ] } } }, "UnauthorizedError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/UnauthorizedErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "UnauthorizedErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/UnauthorizedError" } } }, "ForbiddenErrorExtension": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "TERMS_OF_SERVICE_NOT_ACCEPTED", "ACCESS_DENIED" ] }, "terms_of_service_path": { "type": "string", "example": "/terms/agreement", "description": "The path that the user must open in a browser to accept the terms of service. The hostname matches the API hostname." } } }, "ForbiddenError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ForbiddenErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "ForbiddenErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ForbiddenError" } } }, "ResourceNotFoundErrorExtension": { "type": "object", "required": [ "type", "resource_type" ], "properties": { "type": { "type": "string", "enum": [ "NOT_FOUND", "DELETED" ] }, "resource_type": { "type": "string", "enum": [ "CAMPAIGN", "AD_GROUP", "AD", "MEDIA_FILE", "AD_ACCOUNT", "PIXEL", "CUSTOM_AUDIENCE", "PIXEL_URL_CONFIGURATION", "AM_CONFIGURATION", "CATALOG", "STORE_SET", "RULE" ] } } }, "ResourceNotFoundError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ResourceNotFoundErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "ResourceNotFoundErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ResourceNotFoundError" } } }, "NotAcceptableErrorExtension": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "NOT_ACCEPTABLE" ] } } }, "NotAcceptableError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/NotAcceptableErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "NotAcceptableErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/NotAcceptableError" } } }, "RateLimitedError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ErrorBase" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "TOO_MANY_REQUESTS" ] } } } ] }, "RateLimitedErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/RateLimitedError" } } }, "UnexpectedErrorExtension": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "UNEXPECTED_ERROR" ] } } }, "UnexpectedError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/UnexpectedErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "UnexpectedErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/UnexpectedError" } } }, "ServiceUnavailableErrorExtension": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "UNDER_MAINTENANCE" ] } } }, "ServiceUnavailableError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ServiceUnavailableErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "ServiceUnavailableErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ServiceUnavailableError" } } }, "AggregatedInsightsBreakdownType": { "type": "string", "example": "age", "enum": [ "age", "gender", "prefecture" ], "x-enum-varnames": [ "AGE", "GENDER", "PREFECTURE" ] }, "AggregatedInsightsResponseV3": { "type": "object", "required": [ "data", "total_objects" ], "properties": { "total_objects": { "type": "integer", "format": "int32", "description": "The total number of objects that match this query" }, "data": { "type": "object", "description": "Aggregated data of a specific object.", "properties": { "metadata": { "$ref": "#/components/schemas/MetadataV3" }, "metrics": { "$ref": "#/components/schemas/MetricsV3" }, "metrics_breakdown": { "description": "This field is included when `breakdown_period` or `breakdown_type` parameter is specified.\n", "type": "array", "items": { "$ref": "#/components/schemas/MetricsBreakdownV3" } } } } } }, "PageSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000, "example": 100, "description": "The number of objects to return per page.\n\nThe maximum page size is 1000 and the default is 1000.\n" }, "Name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The name of the campaign.\n\nNote: The maximum length is calculated by our standard length calculation rules: [See details](https://help-ads.smartnews.com/item-3888/)\n" }, "WebsiteTrackingTag": { "type": "string", "example": "89d2b4523c7245ee9ec773a8", "nullable": true, "description": "The pixel tag id that is used to report web events generated through a campaign. \\\nRequired if Objective is `SALES` and Click Destination Type is `WEB_VIEW`\n\nThis field is not updatable when `ready_for_delivery` is `true`.\n" }, "DailyBudgetAmountMicro": { "type": "integer", "format": "int64", "example": 10000000000, "description": "The average budget per day in [micros](#section/About-Currency-Units) of the ad account currency base unit.\n\n| Ad Account's currency | Minimum value | Maximum Value | Minimum unit |\n|-----------------------|-----------------|---------------------------|------------------|\n| JPY | 100,000,000 | 100,000,000,000,000 | 1,000,000 |\n| USD | 1,000,000 | 1,000,000,000,000 | 10,000 |\n\nThe API will return an error if the provided value is not divisible by the minimum unit.\n" }, "BidStrategy": { "type": "string", "enum": [ "MANUAL", "HIGHEST_VOLUME", "TARGET_COST" ], "description": "The strategy that defines how the amount of bid is decided.\n\n| Objective | Available bid strategies | Usable for US region ad accounts |\n|---------------|--------------------------|----------------------------------|\n| TRAFFIC | HIGHEST_VOLUME | TRUE |\n| TRAFFIC | MANUAL | TRUE |\n| SALES | HIGHEST_VOLUME | TRUE |\n| SALES | TARGET_COST | TRUE |\n| AWARENESS | HIGHEST_VOLUME | FALSE |\n| AWARENESS | MANUAL | FALSE |\n| APP_PROMOTION | HIGHEST_VOLUME | FALSE |\n| APP_PROMOTION | TARGET_COST | FALSE |\n" }, "TargetCostMicro": { "type": "integer", "format": "int64", "nullable": true, "description": "The cost per acquisition in [micros](#section/About-Currency-Units) of the ad account currency base unit.\n\nThis is only required and configurable if and only if the bidding strategy is `TARGET_COST`.\n\n| Ad Account's currency | Minimum value | Maximum Value | Minimum unit |\n|-----------------------|-----------------|---------------------------|------------------|\n| JPY | 50,000,000 | 1,000,000,000,000 | 1,000,000 |\n| USD | 500,000 | 10,000,000,000 | 10,000 |\n\nThe API will return an error if the provided value is not divisible by the minimum unit.\n" }, "BidAmountMicro": { "type": "integer", "format": "int64", "nullable": true, "description": "The bidding amount for `MANUAL` bidding strategy in [micros](#section/About-Currency-Units) of the ad account currency base unit.\n\nThis field is configurable and required if and only if the bid_strategy is `MANUAL`.\n\n| Ad Account's currency | Minimum value | Maximum Value | Minimum unit |\n|-----------------------|-----------------|---------------------------|------------------|\n| JPY | 1,000,000 | 1,000,000,000,000 | 1,000,000 |\n| USD | 10,000 | 10,000,000,000 | 10,000 |\n\nThe API will return an error if the provided value is not divisible by the minimum unit.\n\nIf the billing event is IMPRESSION, then the bidding amount is the price the campaign bids for 1000 VIMPs.\n" }, "BillingEvent": { "type": "string", "enum": [ "CLICK", "VIEWABLE_IMPRESSION" ], "description": "The type of event that the ad account wants to pay for the campaign.\n\n| Objective | Available billing events |\n|---------------|----------------------------------|\n| TRAFFIC | VIEWABLE_IMPRESSION (non-DA campaign only), CLICK |\n| SALES | VIEWABLE_IMPRESSION (non-DA campaign only), CLICK |\n| AWARENESS | VIEWABLE_IMPRESSION |\n| APP_PROMOTION | VIEWABLE_IMPRESSION, CLICK |\n\nThis field is not updatable when `ready_for_delivery` is `true`. \n\n`VIEWABLE_IMPRESSION` is not supported for DA campaigns.\n" }, "DeliveryType": { "type": "string", "enum": [ "STANDARD", "ACCELERATED" ], "nullable": true, "description": "Delivery type adjusts the speed of budget spending throughout the day.\n\nA delivery type must be configured for `MANUAL` or `TARGET_COST` bid strategy, while it must be `null` for `HIGHEST_VOLUME`\n\nIf `null` is provided during the creation of a campaign, a default value is assigned by the system as following:\n\n| Objective | Bid Strategy | Default Delivery Type |\n|---------------|----------------|-----------------------|\n| TRAFFIC | HIGHEST_VOLUME | null |\n| TRAFFIC | MANUAL | ACCELERATED |\n| SALES | HIGHEST_VOLUME | null |\n| SALES | TARGET_COST | ACCELERATED |\n| AWARENESS | HIGHEST_VOLUME | null |\n| AWARENESS | MANUAL | STANDARD |\n| APP_PROMOTION | TARGET_COST | ACCELERATED |\n| APP_PROMOTION | HIGHEST_VOLUME | null |\n\n`STANDARD` delivery type is not usable for US region ad accounts.\n" }, "ConversionAttributionWindow": { "type": "string", "enum": [ "ONE_DAY", "SEVEN_DAYS", "FOURTEEN_DAYS", "THIRTY_DAYS" ], "description": "It specifies the time frame in which conversions are counted for the campaign.\n\nThe default value is `THIRTY_DAYS` if not specified.\n\nAvailable values are dependent on the campaign objective:\n - `SALES`: All values are available.\n - others: Only `THIRTY_DAYS` is available.\n" }, "SpendingLimitMicro": { "type": "integer", "format": "int64", "example": 10000000000, "description": "The life-time spending limit in [micros](#section/About-Currency-Units) of the ad account currency base unit. Null means there is no limit.\n\n| Ad Account's currency | Minimum value (creation only) | Maximum Value | Minimum unit |\n|-----------------------|--------------------------------|---------------------------|------------------|\n| JPY | 100,000,000 | 10,000,000,000,000,000 | 1,000,000 |\n| USD | 1,000,000 | 10,000,000,000,000 | 10,000 |\n\nThe API will return an error if the provided value is not divisible by the minimum unit.\nAfter the creation, please refer to the `minimal_spending_limit_micro` field for the minimum value.\n" }, "ViewabilityMeasurement": { "type": "object", "required": [ "vendor_type", "vendor_key", "verification_parameters", "verification_script_url" ], "description": "Configuration for 3rd party viewability measurement provider. It is not editable when the campaign is ready for delivery.\nCurrently, only MOAT is supported.\n", "properties": { "vendor_type": { "type": "string", "enum": [ "MOAT" ], "description": "The vendor to use for viewability measurement." }, "vendor_key": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "The unique key provided by the vendor." }, "verification_parameters": { "type": "string", "minLength": 1, "maxLength": 1024, "example": "{\"campaign_name\": \"{campaign_name}\"}", "description": "A string containing the viewability parameters to be sent along with impressions.\n\n- For MOAT, it is an escaped JSON string.\n - Example: `{\\\"campaign_name\\\": \\\"{campaign_name}\\\", \\\"ad_group_name\\\": \\\"{ad_group_name}\\\"}`\n- For DoubleVerify, it uses URL query string syntax.\n - Example: `campaign_name={campaign_name}&ad_group_name={ad_group_name}`\n\nBoth vendors accept the following macros:\n - {ad_account_name}\n - {campaign_name}\n - {ad_group_name}\n - {ad_name}\n\nDoubleVerify also accepts the following macros:\n - {ad_account_id}\n - {campaign_id}\n - {ad_group_id}\n - {ad_id}\n" }, "verification_script_url": { "type": "string", "example": "https://z.moatads.com/mydisplayads248228380663/moatad.js", "minLength": 1, "maxLength": 1024, "description": "The script URL provided by the vendor.\n- URL format must follow the [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) spec\n- The protocol must be `https`\n" } } }, "ClickDestinationType": { "type": "string", "enum": [ "WEB_VIEW", "BROWSER", "APP", "APP_STORE" ], "nullable": true, "description": "This defines which components SmartNews opens after an ad is clicked.\n\nIf click_destination_type = null when creating campaign then default value is set as below:\n 1. click_destination_type = APP / APP_STORE for APP_PROMOTION objective\n 2. click_destination_type = WEB_VIEW for remaining available objectives\n\n| Objective | Available click destination types |\n|---------------|-----------------------------------|\n| TRAFFIC | WEB_VIEW, BROWSER |\n| SALES | WEB_VIEW, BROWSER |\n| AWARENESS | WEB_VIEW, BROWSER |\n| APP_PROMOTION | APP, APP_STORE |\n\n`BROWSER` is not usable for US region ad accounts.\n" }, "IsLargeUnitSquareAds": { "type": "boolean", "description": "A boolean flag that indicates whether ads from this campaign are displayed in the app using the large unit square format.\n\nThis feature is only available when objective is `AWARENESS`.\n\nFor eligible ad accounts, this feature is also available when objective is `TRAFFIC` or `SALES`.\n\nThis field's value cannot be changed if the campaign already has 1 or more ads.\n\nNote: This field is not settable for US region ad accounts.\n" }, "IsStickyPlacementsEnabled": { "type": "boolean", "description": "A boolean flag that indicates whether fixed on-scroll sticky placements are included for this campaign.\n\nThe default value is `false` if not specified.\n\nNote: This field can be `true` only when both `is_large_unit_ads` and `is_large_unit_square_ads` are `false`.\n" }, "IsMultiOrderAttribution": { "type": "boolean", "example": false, "description": "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.\n\nThe default value is `false` if not specified.\n\nNote: only usable when campaign objective is `SALES`, optimization event is `PURCHASE` and bid strategy is not `TARGET_COST`.\n" }, "IsSKAdNetworkEnabled": { "type": "boolean", "example": false, "description": "[Coming Soon] This feature is not yet available but will be supported soon.\n\nA boolean flag that indicates whether the campaign is using SKAdNetwork to collect data.\n\nThe default value is `false` if not specified.\n\nNote: only usable when campaign objective is `APP_PROMOTION` and targets an iOS app.\n" }, "IsDynamicAds": { "type": "boolean", "default": false, "description": "A boolean flag that indicates whether the campaign is dynamic ads or standard ads.\\\n\nNote: The US region ad accounts are not allowed to create dynamic ads campaigns.\n\nCurrently supported objectives for dynamic ads campaigns:\n- `TRAFFIC`\n- `SALES`\n" }, "CatalogId": { "type": "integer", "description": "The catalog ID to use for this dynamic ads campaign.\n" }, "DynamicAdsInfo": { "type": "object", "required": [ "catalog_id" ], "properties": { "catalog_id": { "$ref": "#/components/schemas/CatalogId" } }, "description": "Configuration specific to dynamic ads campaigns.\n\nIf `is_dynamic_ads` is true, this field is required.\n" }, "BudgetAutoTargetCpaMicro": { "type": "integer", "format": "int64", "nullable": true, "default": null, "example": 10000000000, "description": "Budget Auto-adjustment Expected CPA in [micros](#section/About-Currency-Units) of the ad account currency base unit.\n\nThis value is only able to be set when campaign objective is `SALES` and bidding strategy is `HIGHEST_VOLUME`.\nOtherwise it must be `null`.\n" }, "AppPromotionType": { "type": "string", "enum": [ "INSTALL", "ENGAGEMENT" ], "description": "The type of app promotion campaign.\n\n| Promotion type | Description |\n|-------------------|-------------------------------------------|\n| INSTALL | To promote app installations by new users |\n| ENGAGEMENT | To promote app activities on installed app|\n\nIt is not editable when `ready_for_delivery` is `true`.\n" }, "AppOperatingSystem": { "type": "string", "enum": [ "IOS", "ANDROID" ], "description": "The platform of promoted app" }, "AppStoreId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The promoted app's App store ID. Each platform has a different format for the ID.\n\nFor `IOS`, it is string containing digits only. Example: `\"579581125\"`\nFor `ANDROID`,it is a string. Example: `\"jp.gocro.smartnews.android\"`\n" }, "AppMmpType": { "type": "string", "enum": [ "ADJUST", "APPS_FLYER", "SINGULAR" ], "description": "The third-party service provider that helps advertisers track, measure, and attribute the performance of\ntheir mobile ad campaigns.\n\nIt is not editable when `ready_for_delivery` is `true`.\n" }, "AppMmpTrackingUrl": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "A URL used to track and attribute mobile app marketing campaign performance.\n\nFor detailed validation rules, see the [help page](https://help-ads.smartnews.com/item-3673/)\n" }, "AppPromotionInfo": { "type": "object", "description": "Configuration specific to App Promotion objective campaigns. It is required when `objective` is `APP_PROMOTION`", "required": [ "promotion_type", "operating_system", "store_id", "mmp_type", "mmp_tracking_url" ], "properties": { "promotion_type": { "$ref": "#/components/schemas/AppPromotionType" }, "operating_system": { "$ref": "#/components/schemas/AppOperatingSystem" }, "store_id": { "$ref": "#/components/schemas/AppStoreId" }, "mmp_type": { "$ref": "#/components/schemas/AppMmpType" }, "mmp_tracking_url": { "$ref": "#/components/schemas/AppMmpTrackingUrl" } } }, "AppTrackingConfig": { "type": "object", "required": [ "operating_system", "store_id" ], "properties": { "operating_system": { "$ref": "#/components/schemas/AppOperatingSystem" }, "store_id": { "$ref": "#/components/schemas/AppStoreId" }, "mmp_type": { "$ref": "#/components/schemas/AppMmpType" }, "mmp_tracking_url": { "$ref": "#/components/schemas/AppMmpTrackingUrl" } } }, "AppTrackingConfigs": { "type": "array", "items": { "$ref": "#/components/schemas/AppTrackingConfig" }, "maxItems": 2, "description": "This field is used to configure app tracking when conversions from both the app and the web need to be tracked.\n\nIf the campaign's objective = APP_PROMOTION, then please set campaign.app_promotion_info instead. Otherwise, \n validation error will be thrown.\n\nThis field can be set only when the following conditions are met otherwise it will validation error\n 1.1 For DA campaign, it is allowed for objective = SALES or TRAFFIC\n 1.2 For non-DA campaign, it is allowed for SALES objective only.\n 2. website_tracking_tag is set. \n\nWhen there are two configs then make sure following conditions apply\n - One of the config is for iOS and another for Android.\n - Both appStoreIds exist and are unique.\n - If MMP is selected, then MmpType is same for both configs.\n\nFor PATCH request,\n If you want to keep the value unchanged, then omit this field from patch request.\n If you want to remove the current appTrackingConfigs entirely then set this property to empty array.\n If you want to replace the existing config, then please provide entire array of appTrackingConfig.\n" }, "CampaignDailySchedule": { "type": "object", "required": [ "start_time", "end_time" ], "properties": { "start_time": { "type": "string", "pattern": "^(?:([0-1]?[0-9]|2[0-3]):([0-5][0-9]))$", "example": "09:00", "description": "The start time (inclusive) in 24 hour time, using the ad account's timezone.\n\nMust be between 00:00 and 23:00, and less than end_time. Minutes must be set to `00`.\n\n00:00 represents midnight at the start of the day.\n" }, "end_time": { "type": "string", "pattern": "^(?:([0-1]?[1-9]|2[0-3]):([0-5][0-9])|24:00)$", "example": "17:00", "description": "The end time (exclusive) in 24 hour time, using the ad account's timezone.\n\nMust be between `01:00` and `24:00`, and greater than start_time. Minutes must be set to `00`.\n\n`24:00` represents midnight at the end of the day.\n" } } }, "DailySchedules": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignDailySchedule" }, "maxItems": 6, "description": "An array of daily delivery schedules for the campaign. By default, it is empty. If empty, the campaign will run 24/7.\n\nTo 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`.\n\nNote: even if a daily schedule is provided, the campaign will only be delivered during the campaign's `start_date_time` and `end_date_time`.\n\nThe number of schedules must be between 1 and 6, if non-null. Windows must not overlap within the same campaign.\n\nIn 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.\n" }, "ChannelViewPlacement": { "type": "string", "enum": [ "IN_FEED", "PRIMARY_SLOT" ], "description": "The placement of the campaign's ads within the channel view.\n\n- `IN_FEED`: Shown in between articles in the feed\n- `PRIMARY_SLOT`: Shown in the first ad slot of the feed, typically before any articles\n\n`PRIMARY_SLOT` can only be specified when `is_large_unit_ads` or `is_large_unit_square_ads` is `true`.\n\nThe default is `IN_FEED`.\n" }, "CampaignRequest": { "type": "object", "required": [ "name", "objective", "daily_budget_amount_micro", "bid_strategy", "billing_event", "start_date_time", "configured_status" ], "properties": { "name": { "$ref": "#/components/schemas/Name" }, "objective": { "$ref": "#/components/schemas/CampaignObjective" }, "website_tracking_tag": { "$ref": "#/components/schemas/WebsiteTrackingTag" }, "daily_budget_amount_micro": { "$ref": "#/components/schemas/DailyBudgetAmountMicro" }, "bid_strategy": { "$ref": "#/components/schemas/BidStrategy" }, "target_cost_micro": { "$ref": "#/components/schemas/TargetCostMicro" }, "bid_amount_micro": { "$ref": "#/components/schemas/BidAmountMicro" }, "billing_event": { "$ref": "#/components/schemas/BillingEvent" }, "optimization_goal": { "$ref": "#/components/schemas/OptimizationGoal" }, "delivery_type": { "$ref": "#/components/schemas/DeliveryType" }, "optimization_event": { "$ref": "#/components/schemas/OptimizationEvent" }, "conversion_attribution_window": { "$ref": "#/components/schemas/ConversionAttributionWindow" }, "start_date_time": { "$ref": "#/components/schemas/StartDateTime" }, "end_date_time": { "$ref": "#/components/schemas/EndDateTime" }, "configured_status": { "$ref": "#/components/schemas/ConfiguredStatus" }, "spending_limit_micro": { "$ref": "#/components/schemas/SpendingLimitMicro" }, "viewability_measurement": { "$ref": "#/components/schemas/ViewabilityMeasurement" }, "click_destination_type": { "$ref": "#/components/schemas/ClickDestinationType" }, "is_large_unit_ads": { "$ref": "#/components/schemas/IsLargeUnitAds" }, "is_large_unit_square_ads": { "$ref": "#/components/schemas/IsLargeUnitSquareAds" }, "is_sticky_placements_enabled": { "$ref": "#/components/schemas/IsStickyPlacementsEnabled" }, "is_multi_order_attribution": { "$ref": "#/components/schemas/IsMultiOrderAttribution" }, "is_skadnetwork_enabled": { "$ref": "#/components/schemas/IsSKAdNetworkEnabled" }, "is_dynamic_ads": { "$ref": "#/components/schemas/IsDynamicAds" }, "dynamic_ads_info": { "$ref": "#/components/schemas/DynamicAdsInfo" }, "budget_auto_target_cpa_micro": { "$ref": "#/components/schemas/BudgetAutoTargetCpaMicro" }, "app_promotion_info": { "$ref": "#/components/schemas/AppPromotionInfo" }, "app_tracking_configs": { "$ref": "#/components/schemas/AppTrackingConfigs" }, "daily_schedules": { "$ref": "#/components/schemas/DailySchedules" }, "store_set_id": { "$ref": "#/components/schemas/StoreSetId" }, "channel_view_placement": { "$ref": "#/components/schemas/ChannelViewPlacement" } } }, "CampaignID": { "type": "integer", "format": "int64", "description": "The ID of the campaign." }, "CreatedAt": { "type": "string", "format": "date-time", "description": "The date-time at which the campaign was created." }, "UpdatedAt": { "type": "string", "format": "date-time", "description": "The date-time at which the campaign was last updated." }, "TotalSpending": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "10000", "description": "The current total spending of the campaign.\nThis value is expressed in the base unit of the ad account's currency and it represents the exact monetary amount spent over the campaign's lifetime.\nNull if our system is not able to determine the value currently.\n" }, "MinimalSpendingLimitMicro": { "type": "integer", "format": "int64", "example": 10000000000, "description": "The current minimum required value when you attempt to update the `spending_limit_micro`.\nThis value considers the factors like the `total_spending` of the campaign and may change by the time our system receives a update request.\nNull if updating `spending_limit_micro` is not available at the moment.\n" }, "CampaignResponse": { "allOf": [ { "$ref": "#/components/schemas/CampaignRequest" }, { "type": "object", "required": [ "campaign_id", "ad_account_id", "buying_type", "click_destination_type", "conversion_attribution_window", "created_at", "updated_at", "ready_for_delivery", "delivery_status", "has_any_video_ads", "is_migrated_from_v1", "is_dynamic_ads", "is_multi_order_attribution", "is_skadnetwork_enabled", "is_permanently_disabled", "daily_schedules", "is_large_unit_ads", "is_large_unit_square_ads", "channel_view_placement", "is_sticky_placements_enabled" ], "properties": { "campaign_id": { "$ref": "#/components/schemas/CampaignID" }, "ad_account_id": { "type": "integer", "format": "int64", "description": "The ID of the ad account that owns the campaign." }, "buying_type": { "type": "string", "enum": [ "AUCTION" ], "description": "Buying type defines how an ad account buy ads. Currently, the only available type is AUCTION." }, "click_destination_type": { "$ref": "#/components/schemas/ClickDestinationType" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" }, "ready_for_delivery": { "$ref": "#/components/schemas/ReadyForDelivery" }, "delivery_status": { "$ref": "#/components/schemas/DeliveryStatusObject" }, "total_spending": { "$ref": "#/components/schemas/TotalSpending" }, "minimal_spending_limit_micro": { "$ref": "#/components/schemas/MinimalSpendingLimitMicro" }, "has_any_video_ads": { "$ref": "#/components/schemas/HasAnyVideoAds" }, "is_migrated_from_v1": { "$ref": "#/components/schemas/IsMigratedFromV1" }, "is_dynamic_ads": { "$ref": "#/components/schemas/IsDynamicAds" }, "is_sticky_placements_enabled": { "$ref": "#/components/schemas/IsStickyPlacementsEnabled" }, "dynamic_ads_info": { "$ref": "#/components/schemas/DynamicAdsInfo" }, "budget_auto_target_cpa_micro": { "$ref": "#/components/schemas/BudgetAutoTargetCpaMicro" }, "is_permanently_disabled": { "type": "boolean", "example": false, "description": "Indicates that the campaign cannot be switched back to `ACTIVE` configured status. This state occurs when a campaign's SKAdNetwork source identifier is reused for another campaign." } } } ] }, "CampaignPaginatedResponse": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignResponse" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoResponse" } } }, "BusinessErrorExtension": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "BUSINESS_ERROR" ] } } }, "BusinessError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BusinessErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "BusinessErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/BusinessError" } } }, "ValidationErrorExtension": { "required": [ "type", "error_fields" ], "properties": { "type": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "error_fields": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string", "description": "The field name that doesn't pass the validation.\\\nFor nested fields, the field name will be in the format of JSON path with dot notation.\\\nHere are some examples:\\\n - `landing_page_url`(a root level field)\\\n - `ad.creative.headline`(a nested object field)\\\n - `creative.image_creative_info.media_file_ids`(an array in a nested object)\\\n - `creative.carousel_creative_info.carousel_cards[0].caption`(a field of an object in an array)\\\n" }, "reason": { "type": "string" } } } } } }, "ValidationError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ValidationErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "ValidationErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ValidationError" } } }, "PatchAppPromotionInfo": { "type": "object", "description": "It contains the fields of AppPromotionInfo which are updatable.", "properties": { "mmp_type": { "$ref": "#/components/schemas/AppMmpType" }, "mmp_tracking_url": { "$ref": "#/components/schemas/AppMmpTrackingUrl" } } }, "CampaignPatchRequest": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "configured_status": { "$ref": "#/components/schemas/ConfiguredStatus" }, "daily_budget_amount_micro": { "$ref": "#/components/schemas/DailyBudgetAmountMicro" }, "website_tracking_tag": { "$ref": "#/components/schemas/WebsiteTrackingTag" }, "optimization_event": { "$ref": "#/components/schemas/OptimizationEvent" }, "conversion_attribution_window": { "$ref": "#/components/schemas/ConversionAttributionWindow" }, "start_date_time": { "$ref": "#/components/schemas/StartDateTime" }, "end_date_time": { "$ref": "#/components/schemas/EndDateTime" }, "bid_strategy": { "$ref": "#/components/schemas/BidStrategy" }, "target_cost_micro": { "$ref": "#/components/schemas/TargetCostMicro" }, "bid_amount_micro": { "$ref": "#/components/schemas/BidAmountMicro" }, "billing_event": { "$ref": "#/components/schemas/BillingEvent" }, "optimization_goal": { "$ref": "#/components/schemas/OptimizationGoal" }, "delivery_type": { "$ref": "#/components/schemas/DeliveryType" }, "spending_limit_micro": { "$ref": "#/components/schemas/SpendingLimitMicro" }, "viewability_measurement": { "$ref": "#/components/schemas/ViewabilityMeasurement" }, "click_destination_type": { "$ref": "#/components/schemas/ClickDestinationType" }, "is_large_unit_ads": { "$ref": "#/components/schemas/IsLargeUnitAds" }, "is_large_unit_square_ads": { "$ref": "#/components/schemas/IsLargeUnitSquareAds" }, "is_sticky_placements_enabled": { "$ref": "#/components/schemas/IsStickyPlacementsEnabled" }, "is_multi_order_attribution": { "$ref": "#/components/schemas/IsMultiOrderAttribution" }, "is_skadnetwork_enabled": { "$ref": "#/components/schemas/IsSKAdNetworkEnabled" }, "store_set_id": { "$ref": "#/components/schemas/StoreSetId" }, "budget_auto_target_cpa_micro": { "$ref": "#/components/schemas/BudgetAutoTargetCpaMicro" }, "app_promotion_info": { "$ref": "#/components/schemas/PatchAppPromotionInfo" }, "app_tracking_configs": { "$ref": "#/components/schemas/AppTrackingConfigs" }, "daily_schedules": { "$ref": "#/components/schemas/DailySchedules" }, "channel_view_placement": { "$ref": "#/components/schemas/ChannelViewPlacement" } } }, "AdGroupSchemas_Name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The name of the ad group.\n\nNote: The maximum length is calculated by our standard length calculation rules: [See details](https://help-ads.smartnews.com/item-3888/)\n" }, "Age": { "type": "string", "enum": [ "AGE_UNDER_20", "AGE_21_24", "AGE_25_29", "AGE_30_34", "AGE_35_39", "AGE_40_44", "AGE_45_49", "AGE_50_54", "AGE_55_59", "AGE_60_64", "AGE_65_69", "AGE_OVER_70" ] }, "Ages": { "description": "An array of age buckets to target.\n\nNote:\n- This field is not settable for US region ad accounts.\n- `AGE_UNDER_20` option is deprecated and can no longer be used for new ad groups and when updating an existing ad group.\n", "type": "array", "items": { "$ref": "#/components/schemas/Age" } }, "Gender": { "type": "string", "description": "Selected genders of users for the ads to be delivered.", "enum": [ "MALE", "FEMALE", "UNKNOWN" ] }, "Genders": { "description": "An array of genders to target.\n\nNote: This field is not settable for US region ad accounts.\n", "type": "array", "items": { "$ref": "#/components/schemas/Gender" } }, "LocationId": { "type": "integer", "format": "int32" }, "AdGroupLocations": { "description": "An array of location IDs to target.\n\nA list of location IDs can be obtained via the [locations](#tag/locations) endpoint.\n\nNote: Only available for US accounts. For JP accounts, please use `hyper_location_config`.\n\nWhen both `locations` and `zip_codes` are provided, the delivery condition is satisfied if the user matches any of the given states/counties or any of the ZIP codes.\n", "type": "array", "items": { "$ref": "#/components/schemas/LocationId" } }, "ZipCode": { "type": "string", "pattern": "^\\d{5}$", "description": "A ZIP code used for ad group location targeting in the United States.\n\n- Accepts exactly five numeric digits. Leading zeroes must be included where applicable.\n- Only available for ad accounts in the US region.\n- Only valid ZIP codes are accepted.\n", "example": "10001" }, "ZipCodes": { "description": "An array of ZIP codes to target.\n\nThe values are combined with `locations` (states and counties) using OR logic during delivery.\n\nThe response returns ZIP codes in ascending numeric order while keeping their 5-digit string form.\n\n- Submit an empty array `[]` or `null` in a PATCH request to remove all ZIP codes.\n- Duplicate values in the request payload are ignored; the response returns a unique set of ZIP codes.\n- Supports up to 40,000 ZIP codes per request.\n\n* e.g. This targets Washington state, Pierce County, and ZIP codes `12345` / `67890`:\n ```\n {\n ...\n \"audience\": {\n \"locations\": [2, 3],\n \"zip_codes\": [\"12345\", \"67890\"]\n }\n }\n ```\n", "type": "array", "items": { "$ref": "#/components/schemas/ZipCode" }, "maxItems": 1000, "example": [ "10001", "10002" ] }, "UserSegment": { "type": "string", "description": "The type of users to target.\n", "enum": [ "RESIDENT_ONLY", "RESIDENT_AND_VISITOR" ] }, "LocationSegmentId": { "type": "integer", "description": "The unique identifier of the location segment.\n\nIf this property is set, the specified location segment will be updated (PATCH request only).\n\nIf this property is not set, a new location segment will be created.\n\nThis property is not allowed in POST requests.\n", "format": "int64" }, "SegmentAreaType": { "type": "string", "description": "The area type of the segment.\n", "enum": [ "PIN_WITH_RADIUS", "FIXED_AREA" ] }, "LocationSegmentPinWithRadiusInfo": { "type": "object", "description": "The configuration for the Pin with Radius location segment. Required and only settable when `segment_area_type` is `PIN_WITH_RADIUS`.\n", "required": [ "address", "latitude", "longitude", "radius_in_meters" ], "properties": { "address": { "type": "string", "description": "The address of the location.\n" }, "label": { "type": "string", "description": "The label of the location.\n" }, "latitude": { "type": "string", "description": "The latitude of the location.\n" }, "longitude": { "type": "string", "description": "The longitude of the location.\n" }, "radius_in_meters": { "type": "integer", "format": "int32", "description": "The radius in meters from the central point of the location.\n" } } }, "HyperLocationSchemas_LocationId": { "type": "integer", "description": "The unique identifier of the location.\n\nA list of location IDs can be obtained via the [locations](#tag/locations) endpoint.\n", "format": "int32" }, "LocationSegmentFixedAreaInfo": { "type": "object", "description": "The configuration for the Fixed Area location segment. Required and only settable when `segment_area_type` is `FIXED_AREA`.\n", "required": [ "location_id" ], "properties": { "location_id": { "$ref": "#/components/schemas/HyperLocationSchemas_LocationId" } } }, "LocationSegmentRequest": { "type": "object", "required": [ "segment_area_type" ], "properties": { "location_segment_id": { "$ref": "#/components/schemas/LocationSegmentId" }, "segment_area_type": { "$ref": "#/components/schemas/SegmentAreaType" }, "pin_with_radius_info": { "$ref": "#/components/schemas/LocationSegmentPinWithRadiusInfo" }, "fixed_area_info": { "$ref": "#/components/schemas/LocationSegmentFixedAreaInfo" } } }, "HyperLocationConfigRequest": { "type": "object", "nullable": true, "description": "An object containing hyper location targeting configuration.\n\nNote: This field is not settable for US region ad accounts.\n", "required": [ "user_segment", "location_segments" ], "properties": { "user_segment": { "$ref": "#/components/schemas/UserSegment" }, "location_segments": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LocationSegmentRequest" }, "description": "The list of location segments to target.\n\nThe list must contain all the segments to target. If a segment is not included in the list, it will be removed from the targeting configuration in a PATCH request.\n\nExactly one of `pin_with_radius_info` or `fixed_area_info` must be set based on the `segment_area_type` value.\n" } }, "example": { "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" } } ] } }, "OperatingSystem": { "type": "object", "nullable": true, "description": "Target OS and optionally a specific OS version. If it is not specified, all OS and OS versions are targeted.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The OS to target.\n", "enum": [ "IOS", "ANDROID" ] }, "since_version": { "type": "string", "description": "Selected OS version of users for the ads to be delivered.\nEx: `13.0.0` means iOS 13.0.0 or later. Empty mean all version.\n" } } }, "CustomAudiences": { "type": "object", "description": "Custom audiences to include or exclude for ad delivery.\n\nIt contains the custom audience IDs to include or exclude for ad delivery.\n\nIf it's empty, it will be delivered to all users.\n\n* e.g. This will target all users\n ```\n {\n ...\n \"custom_audiences\": {\n \"include\": [],\n \"exclude\": []\n }\n }\n ```\n* e.g. This will target users who are in custom audience `123`\n ```\n {\n \"custom_audiences\": {\n \"include\": [123],\n \"exclude\": []\n }\n }\n ```\n", "properties": { "include": { "type": "array", "description": "An array of `custom_audience_id` to include for delivery.", "items": { "type": "integer", "format": "int64" } }, "exclude": { "type": "array", "description": "An array of `custom_audience_id` to exclude for delivery.", "items": { "type": "integer", "format": "int64" } } } }, "ConnectionType": { "type": "string", "nullable": true, "enum": [ "WIFI", "CELLULAR_5G", "CELLULAR_4G", "CELLULAR_3G" ] }, "ConnectionTypes": { "description": "An array of connection types to target.", "type": "array", "items": { "$ref": "#/components/schemas/ConnectionType" } }, "CarrierType": { "type": "string", "enum": [ "DOCOMO", "AU", "SOFTBANK", "ATNT", "VERIZON", "TMOBILE", "BOOST", "SPRINT", "USCELLULAR", "XFINITY", "RAKUTEN", "OTHERS", "UNKNOWN" ] }, "CarrierTypes": { "description": "An array of mobile network carriers to target.\n\nNote: This field is not settable for US region ad accounts.\n", "type": "array", "items": { "$ref": "#/components/schemas/CarrierType" } }, "IABInterestId": { "type": "integer", "format": "int32" }, "Interests": { "description": "An array of IAB Interest IDs to target.\n\nA list of IAB Interest IDs can be obtained via the [iab_interest_categories](#tag/interests) endpoint.\n\nNote: This field is not settable for US region ad accounts.\n", "type": "array", "items": { "$ref": "#/components/schemas/IABInterestId" } }, "PlacementMediaType": { "type": "string", "enum": [ "SMART_VIEW", "CHANNEL_VIEW" ] }, "MediaTypes": { "description": "An array of media types defining where the ads will be displayed in the SmartNews app.\n\nNote: This field is not settable for US region ad accounts.\n", "type": "array", "items": { "$ref": "#/components/schemas/PlacementMediaType" } }, "ChannelAliasLabel": { "type": "string", "enum": [ "CR_JA_TOP", "CR_JA_LOCAL", "CR_JA_ENTERTAINMENT", "CR_JA_SPORTS", "CR_JA_NATIONAL", "CR_JA_POLITICS", "CR_JA_HUMOR", "CR_JA_ECONOMY", "CR_JA_INTERNATIONAL", "CR_JA_EXTRA_ANIMAL", "CR_JA_COLUMN_CAREER", "CR_JA_COLUMN_LOVE", "CR_JA_FOOD", "CR_JA_COLUMN2", "CR_JA_INFECTION", "CR_JA_TECHNOLOGY", "CR_JA_ECONOMY_CAR", "CR_JA_COLUMN_FAMILY", "CR_JA_VIDEO", "CR_JA_SPORTS_SOCCER", "CR_JA_ENTERTAINMENT_MOVIE", "CR_JA_SPORTS_BASEBALL", "CR_JA_COLUMN_BEAUTY", "CR_JA_EXTRA_ANIMAL_DOG", "CR_JA_EXTRA_ANIMAL_CAT", "CR_JA_COLUMN_LIVING", "CR_JA_COLUMN_FASHION", "CR_JA_ENTERTAINMENT_GAME", "CR_JA_EXTRA_MENSSTYLE", "CR_JA_SPORTS_TENNIS", "CR_JA_SPORTS_GOLF", "CR_JA_ECONOMY_MONEY", "CR_JA_ECONOMY_MARKET", "CR_JA_TECHNOLOGY_INNOVATION", "CR_JA_COUPON", "CR_JA_FOOD_RECIPE", "CR_JA_EXTRA_BEER", "CR_JA_EXTRA_RAMEN", "CR_JA_FOOD_BACKORDER", "CR_JA_FOOD_FASTFOOD", "CR_JA_FOOD_CAFE", "CR_JA_FOOD_GOURMET_KOREANFOOD", "CR_JA_FOOD_SPICY", "CR_JA_FOOD_SWEETS", "CR_JA_FOOD_BREAD", "CR_JA_EXTRA_RANKING", "CR_JA_FOOD_FINGERFOOD", "CR_JA_EXTRA_COFFEE", "CR_JA_EXTRA_CHOCOLATE", "CR_JA_EXTRA_WINE", "CR_JA_EXTRA_ICECREAM", "CR_JA_EXTRA_CURRY", "CR_JA_FOOD_GOURMET_JAPANESEFOOD", "CR_JA_FOOD_MEAT", "CR_JA_FOOD_TAKEOUT", "CR_JA_FOOD_GOURMET_CHINESE", "CR_JA_FOOD_TEA", "CR_JA_FOOD_GOURMET_FRENCH", "CR_JA_EXTRA_POINT", "CR_JA_COLUMN_SALE", "CR_JA_COLUMN_100YEN", "CR_JA_EXTRA_SAVING", "CR_JA_EXTRA_CONVENIENTSTORE", "CR_JA_BOUSAI", "CR_JA_LIFE_CONSUMERELECTRONICS", "CR_JA_COLUMN_INTERIOR", "CR_JA_SPECIAL_STAYHOME", "CR_JA_EXTRA_RESIDENCE", "CR_JA_EXTRA_CLEANING", "CR_JA_EXTRA_EDUCATION", "CR_JA_COLUMN_CHILDCARE", "CR_JA_EXTRA_GIFT", "CR_JA_COLUMN_PRIZEGIVING", "CR_JA_COLUMN_TRAVEL", "CR_JA_EXTRA_GOTO", "CR_JA_EXTRA_HOTSPRING", "CR_JA_EXTRA_MUSEUM", "CR_JA_SPORTS_SOCCER_OVERSEA", "CR_JA_SPORTS_BASKETBALL", "CR_JA_SPORTS_RUGBY", "CR_JA_SPORTS_VOLLEYBALL", "CR_JA_SPORTS_ATHLETICSPORTS", "CR_JA_SPORTS_TABLETENNIS", "CR_JA_SPORTS_JUDO", "CR_JA_SPORTS_BOATRACE", "CR_JA_SPORTS_HORSERACING", "CR_JA_SPORTS_SHOHEIOHTANI", "CR_JA_SPORTS_BASEBALL_HIGHSCHOOL", "CR_JA_SPORTS_MARTIALARTS", "CR_JA_SPORTS_SUMO", "CR_JA_SPORTS_BOXING", "CR_JA_SPORTS_PROWRESTLING", "CR_JA_SPORTS_FIGURESKATE", "CR_JA_SPORTS_CURLING", "CR_JA_SPORTS_XSPORTS", "CR_JA_SPORTS_PARASPORTS", "CR_JA_SPORTS_WRESTLING", "CR_JA_SPORTS_BICYCLERACING", "CR_JA_COLUMN_FISHING", "CR_JA_EXTRA_ESPORTS", "CR_JA_EXTRA_RUNNING", "CR_JA_EXTRA_MOUNTAINCLIMBING", "CR_JA_EXTRA_FITNESS", "CR_JA_SPORTS_MOTORSPORTS", "CR_JA_ECONOMY_INVESTMENT", "CR_JA_EXTRA_ECONOMY_INVESTMENT_NISA", "CR_JA_ECONOMY_INVESTMENT_BEGINNER", "CR_JA_SPECIAL_TRUMP_ADMINISTRATION", "CR_JA_INTERNATIONAL_USA", "CR_JA_ECONOMY_CROWDFUNDING", "CR_JA_ECONOMY_MOBILECARRIERS", "CR_JA_ECONOMY_BANK", "CR_JA_EXTRA_AGRICULTURE", "CR_JA_LIFE_NURSING", "CR_JA_ECONOMY_FOODSERVICE", "CR_JA_EXTRA_SDGS", "CR_JA_EXTRA_SCIENCE", "CR_JA_APPS_ANDROID_ALL", "CR_JA_TECHNOLOGY_ARTIFICIAL_INTELLIGENCE", "CR_JA_TECHNOLOGY_PROGRAMMING", "CR_JA_EXTRA_MARKETING", "CR_JA_COLUMN_SIDEBUSINESS", "CR_JA_EXTRA_JOBHUNTING", "CR_JA_EXTRA_LEARNING_ENGLISH", "CR_JA_EXTRA_OUTDOOR", "CR_JA_EXTRA_GARDENING", "CR_JA_EXTRA_NORIMONO", "CR_JA_ECONOMY_BIKE", "CR_JA_EXTRA_BOOK", "CR_JA_ENTERTAINMENT_ART", "CR_JA_COLUMN_FASHION_SNEAKERS", "CR_JA_ENTERTAINMENT_HOBBY", "CR_JA_LIFE_STATIONERY", "CR_JA_EXTRA_HANDMADE", "CR_JA_NATIONAL_TRAIN", "CR_JA_NATIONAL_SHOGI", "CR_JA_EXTRA_ASTRONOMY", "CR_JA_EXTRA_HISTORY", "CR_JA_TECHNOLOGY_VR", "CR_JA_EXTRA_GADGET", "CR_JA_TECHNOLOGY_CAMERA", "CR_JA_TECHNOLOGY_AUDIOVISUAL", "CR_JA_EXTRA_DIY", "CR_JA_LIFE_TRIVIA_MAIN", "CR_JA_EXTRA_ART_MUSEUM", "CR_JA_EXTRA_RETRO", "CR_JA_EXTRA_CERAMICART", "CR_JA_EXTRA_LIFE_KIMONO", "CR_JA_ENTERTAINMENT_IDOL", "CR_JA_EXTRA_OWARAI", "CR_JA_ENTERTAINMENT_GRAVIA", "CR_JA_ENTERTAINMENT_MUSIC", "CR_JA_ENTERTAINMENT_KPOP", "CR_JA_ENTERTAINMENT_FOREIGNMUSIC", "CR_JA_ENTERTAINMENT_KOREANDORAMA", "CR_JA_ENTERTAINMENT_KOREA", "CR_JA_ENTERTAINMENT_STAGE", "CR_JA_ENTERTAINMENT_TV", "CR_JA_ENTERTAINMENT_RADIO", "CR_JA_EXTRA_MANGA", "CR_JA_ENTERTAINMENT_ANIME_VOICEACTOR", "CR_JA_ENTERTAINMENT_HYPNOSISMIC", "CR_JA_COLUMN_FORTUNETELLING", "CR_JA_COLUMN_COSME", "CR_JA_EXTRA_SKINCARE", "CR_JA_EXTRA_COLUMN_BODYCARE", "CR_JA_EXTRA_COLUMN_SHAPEUP", "CR_JA_EXTRA_COLUMN_HAIRCARE", "CR_JA_COSME_KCOSME", "CR_JA_EXTRA_YOGA", "CR_JA_EXTRA_WALKING", "CR_JA_EXTRA_STRETCH", "CR_JA_COLUMN_MENSBEAUTY", "CR_JA_COLUMN_MUSCLETRAINING", "CR_JA_EXTRA_SELFCARE", "CR_JA_EXTRA_HOKKAIDO_INFO", "CR_JA_EXTRA_OSAKA_INFO", "CR_JA_EXTRA_KANAGAWA_INFO", "CR_JA_EXTRA_FUKUOKA2_INFO", "CR_JA_EXTRA_AICHI_INFO", "CR_JA_EXTRA_SAITAMA_INFO", "CR_JA_EXTRA_HIROSHIMA_INFO", "CR_JA_EXTRA_IBARAKI_INFO", "CR_JA_EXTRA_CHIBA_INFO", "CR_JA_EXTRA_NAGANO_INFO", "CR_JA_EXTRA_HYOGO_INFO", "CR_JA_EXTRA_MIYAGI_INFO", "CR_JA_EXTRA_NIIGATA_INFO", "CR_JA_EXTRA_FUKUSHIMA_INFO", "CR_JA_EXTRA_SHIZUOKA_INFO", "CR_JA_EXTRA_GUNMA_INFO", "CR_JA_EXTRA_AOMORI_INFO", "CR_JA_EXTRA_EHIME_INFO", "CR_JA_EXTRA_OKAYAMA_INFO", "CR_JA_EXTRA_TOKYO_INFO", "CR_JA_EXTRA_YAMAGATA_INFO", "CR_JA_EXTRA_IWATE_INFO", "CR_JA_EXTRA_OKINAWA2_INFO", "CR_JA_EXTRA_GIFU_INFO", "CR_JA_EXTRA_KUMAMOTO_INFO", "CR_JA_EXTRA_KAGOSHIMA_INFO", "CR_JA_EXTRA_ISHIKAWA_INFO", "CR_JA_EXTRA_KYOTO_INFO", "CR_JA_EXTRA_SHIGA_INFO", "CR_JA_EXTRA_AKITA_INFO", "CR_JA_EXTRA_TOCHIGI_INFO", "CR_JA_EXTRA_NARA_INFO", "CR_JA_EXTRA_OITA_INFO", "CR_JA_EXTRA_TOYAMA_INFO", "CR_JA_EXTRA_SHIMANE_INFO", "CR_JA_EXTRA_FUKUI_INFO", "CR_JA_EXTRA_NAGASAKI_INFO", "CR_JA_EXTRA_WAKAYAMA_INFO", "CR_JA_EXTRA_KAGAWA_INFO", "CR_JA_EXTRA_YAMAGUCHI_INFO", "CR_JA_EXTRA_TOTTORI_INFO", "CR_JA_EXTRA_MIE_INFO", "CR_JA_EXTRA_TOKUSHIMA_INFO", "CR_JA_EXTRA_YAMANASHI_INFO", "CR_JA_EXTRA_KOUCHI_INFO", "CR_JA_EXTRA_SAGA_INFO", "CR_JA_EXTRA_MIYAZAKI_INFO", "CR_JA_REGION_HOKKAIDO_SAPPORO_INFO", "CR_JA_REGION_MIYAGI_SENDAI_INFO", "CR_JA_REGION_CHIBA_KASHIWA_INFO", "CR_JA_REGION_SAITAMA_SAITAMA_INFO", "CR_JA_REGION_KANAGAWA_YOKOHAMA_INFO", "CR_JA_REGION_AICHI_NAGOYA_INFO", "CR_JA_REGION_HYOGO_KOBE_INFO", "CR_JA_REGION_KYOTO_KYOTO_INFO", "CR_JA_REGION_OSAKA_OSAKA_INFO", "CR_JA_REGION_MIE_ISE_INFO", "CR_JA_REGION_HIROSHIMA_HIROSHIMA_INFO", "CR_JA_REGION_FUKUOKA_FUKUOKA_INFO", "CR_JA_REGION_OITA_OITA_INFO", "CR_JA_REGION_TOKYO_SETAGAYA_INFO", "CR_JA_REGION_TOKYO_NERIMA_INFO", "CR_JA_REGION_TOKYO_SUGINAMI_INFO", "CR_JA_REGION_TOKYO_ITABASHI_INFO", "CR_JA_REGION_TOKYO_OOTA_INFO", "CR_JA_REGION_TOKYO_KOUTOU_INFO", "CR_JA_REGION_TOKYO_KATSUSHIKA_INFO", "CR_JA_REGION_TOKYO_SHINAGAWA_INFO", "CR_JA_REGION_TOKYO_EDOGAWA_INFO", "CR_JA_REGION_TOKYO_SUMIDA_INFO", "CR_JA_REGION_TOKYO_SHINJYUKU_INFO", "CR_JA_REGION_SHIBUYA_INFO", "CR_JA_REGION_TOKYO_NAKANO_INFO", "CR_JA_REGION_TOKYO_ARAKAWA_INFO", "CR_JA_REGION_TOKYO_CHUO_INFO", "CR_JA_REGION_TOKYO_KITA_INFO", "CR_JA_REGION_TOKYO_MINATO_INFO", "CR_JA_REGION_TOKYO_TOSHIMA_INFO", "CR_JA_REGION_TOKYO_TAITO_INFO", "CR_JA_REGION_TOKYO_BUNKYO_INFO", "CR_JA_REGION_TOKYO_CHIYODA_INFO", "CR_JA_REGION_TOKYO_MEGURO_INFO", "CR_JA_REGION_TOKYO_ADACHI_INFO", "OTHERS" ] }, "ChannelAliasLabels": { "description": "An array of target channels to display the ads in the SmartNews app. If it is `null` or `[]`, all channels will be targeted.\n\nThis value can only be set when `media_type` contains `CHANNEL_VIEW`.\n\nNote: This field is not settable for US region ad accounts.\n\nIn PATCH request, if you set this field to `null` or `[]`, it will change the setting to target all channels. If you omit this field, it will retain the current setting.\n\nTo get the list of available channel identifiers and their names, use the `GET /api/cm/v1/channel_alias_labels` endpoint.\n", "type": "array", "items": { "$ref": "#/components/schemas/ChannelAliasLabel" } }, "SmartViewArticleCategoryId": { "type": "integer", "format": "int32" }, "SmartViewArticleCategoryTargeting": { "type": "object", "nullable": true, "required": [ "include", "exclude" ], "description": "SmartView article category targeting settings for ad delivery.\n\nIt contains article category IDs to include or exclude for delivery.\n\nThis field is only configurable when `media_types` includes `SMART_VIEW`.\n\ninclude `[]` means all article categories are included\n\nexclude `[]` means no article categories are excluded\n\nA category ID cannot appear in both the include and exclude lists.\n\nSome example settings:\n| **Case** | **Include** | **Exclude** | **Behavior** |\n|----------|--------------------|-------------|-------------------------------------------------------------------|\n| 1 | `[]` (include All) | `[]` | Deliver to all article categories (Also the default value for UI) |\n| 2 | `[]` (include All) | `[1, 3, 5]` | Deliver to all categories except `1, 3, 5` |\n| 3 | `[1, 2, 3]` | `[]` | Deliver to only categories `1, 2, 3` |\n| 4 | `[1, 2]` | `[3, 5]` | Deliver only to categories `1, 2` excluding `3, 5` |\n| 5 | `[1, 2, 3]` | `[1, 5]` | ❌ Validation error - category `1` appears in both lists |\n\nA list of article category IDs can be obtained via the [article categories](#tag/article-category) endpoint.\n", "properties": { "include": { "description": "An array of article category IDs to include for delivery.", "type": "array", "nullable": false, "items": { "$ref": "#/components/schemas/SmartViewArticleCategoryId" } }, "exclude": { "description": "An array of article category IDs to exclude for delivery.", "type": "array", "nullable": false, "items": { "$ref": "#/components/schemas/SmartViewArticleCategoryId" } } } }, "SmartViewArticleKeywordTargeting": { "type": "object", "nullable": true, "required": [ "include", "exclude" ], "description": "SmartView article keyword targeting settings for ad delivery.\n\nAds will be delivered to SmartView ad placements of articles which include and/or exclude these keywords or a similar topic.\n\nThis field is only configurable when `media_types` includes `SMART_VIEW`.\n\ninclude `[]` means deliver to articles containing any keyword\n\nexclude `[]` means no articles are excluded by keyword\n\nA keyword cannot appear in both the include and exclude lists.\n\nOnly system available keywords are allowed. To get the list of available keywords, use the `POST /api/ma/v3/article_keywords/search` endpoint.\n\nDuplicate values in the request payload are ignored; the response returns a unique set of keywords.\n\nSome example settings:\n| **Case** | **Include** | **Exclude** | **Behavior** |\n|----------|--------------------------------------|----------------------------|-----------------------------------------------------------------------------------------------------|\n| 1 | `[]` (include All) | `[]` | Deliver to articles containing any keyword (Also the default value for UI) |\n| 2 | `[]` (include All) | `[\"soccer\", \"baseball\"]` | Deliver to all articles except those containing `\"soccer\"` or `\"baseball\"` |\n| 3 | `[\"restaurant\", \"tokyo\", \"travel\"]` | `[]` | Deliver only to articles containing `\"restaurant\"`, `\"tokyo\"`, or `\"travel\"` |\n| 4 | `[\"restaurant\", \"tokyo\"]` | `[\"soccer\", \"baseball\"]` | Deliver to articles containing `\"restaurant\"` or `\"tokyo\"`, excluding those containing `\"soccer\"` or `\"baseball\"` |\n| 5 | `[\"restaurant\", \"tokyo\", \"soccer\"]` | `[\"soccer\", \"baseball\"]` | ❌ Validation error - keyword `\"soccer\"` appears in both lists |\n", "properties": { "include": { "description": "An array of keywords. Ads will be delivered to articles containing these keywords.", "type": "array", "nullable": false, "items": { "type": "string" } }, "exclude": { "description": "An array of keywords. Articles containing these keywords will be excluded from delivery.", "type": "array", "nullable": false, "items": { "type": "string" } } } }, "AutomatedTargeting": { "type": "object", "nullable": true, "description": "Automated targeting settings for the ads to be delivered with SN optimized strategy.\n\nIf this field is non-null, automated targeting is enabled (even if the object is empty). Otherwise, it is disabled.\n\nNote: This field is not settable for US region ad accounts.\n", "properties": { "age_unbreakable": { "type": "boolean", "default": false, "description": "If this field is `true`, then age targeting will be strictly followed" }, "gender_unbreakable": { "type": "boolean", "default": false, "description": "If this field is `true`, then gender targeting will be strictly followed" }, "location_unbreakable": { "type": "boolean", "default": false, "description": "If this field is `true`, then location targeting will be strictly followed" }, "custom_audience_unbreakable": { "type": "boolean", "default": false, "description": "If this field is `true`, then custom audience will be strictly followed" }, "carrier_unbreakable": { "type": "boolean", "default": false, "description": "If this field is `true`, then carrier targeting will be strictly followed" }, "connection_type_unbreakable": { "type": "boolean", "default": false, "description": "If this field is `true`, then connection type targeting will be strictly followed" }, "os_version_unbreakable": { "type": "boolean", "default": false, "description": "If this field is `true`, then advertiser's os version targeting will be strictly followed" } } }, "AudienceRequest": { "type": "object", "description": "In Patch Request, if you omit the property, the data will remain unchanged.\n\nIf you want to remove the current settings, set individual fields to either `null` or an empty array.\n\ne.g. This will remove the current settings of ages and genders, while keeping the locations and other audience fields unchanged:\n```\n{\n ages: [],\n genders: null,\n}\n```\n", "properties": { "ages": { "$ref": "#/components/schemas/Ages" }, "genders": { "$ref": "#/components/schemas/Genders" }, "locations": { "$ref": "#/components/schemas/AdGroupLocations" }, "zip_codes": { "$ref": "#/components/schemas/ZipCodes" }, "hyper_location_config": { "$ref": "#/components/schemas/HyperLocationConfigRequest" }, "operating_system": { "$ref": "#/components/schemas/OperatingSystem" }, "custom_audiences": { "$ref": "#/components/schemas/CustomAudiences" }, "connection_types": { "$ref": "#/components/schemas/ConnectionTypes" }, "carrier_types": { "$ref": "#/components/schemas/CarrierTypes" }, "interests": { "$ref": "#/components/schemas/Interests" }, "media_types": { "$ref": "#/components/schemas/MediaTypes" }, "channel_alias_labels": { "$ref": "#/components/schemas/ChannelAliasLabels" }, "smart_view_article_category_targeting": { "$ref": "#/components/schemas/SmartViewArticleCategoryTargeting" }, "smart_view_article_keyword_targeting": { "$ref": "#/components/schemas/SmartViewArticleKeywordTargeting" }, "automated_targeting": { "$ref": "#/components/schemas/AutomatedTargeting" } } }, "Interval": { "type": "string", "description": "The time interval which frequency will be calculated.", "enum": [ "LAST_1_DAY", "LAST_7_DAYS" ] }, "FrequencyControl": { "type": "object", "nullable": true, "description": "Frequency control settings for the ads to be delivered. Only available for Awareness campaign.\n\nNote: This field is not settable for US region ad accounts.\n", "required": [ "interval", "threshold" ], "properties": { "interval": { "$ref": "#/components/schemas/Interval" }, "threshold": { "type": "integer", "description": "The maximum number of times the ad can be shown to a user within a given time period. Min 1, Max 15." } } }, "TargetingType": { "type": "string", "description": "The type of DA targeting. \n\nRetargeting is for finding existing user; \nProspecting is for finding new user based on existing user log.\n\nThis value is NOT updatable once the campaign is ready for delivery.\n", "enum": [ "RETARGETING", "PROSPECTING" ] }, "RecencyDays": { "type": "string", "nullable": true, "enum": [ "LAST_1_DAY", "LAST_3_DAYS", "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "LAST_60_DAYS", "LAST_90_DAYS" ], "description": "The lookback window (in days) for user logs can be used for retargeting.\n\n- Required when targeting_type is `RETARGETING`\n- Set to null when targeting_type is `PROSPECTING`\n\nThis value is updatable when the campaign is ready for delivery.\n" }, "ProductSetID": { "type": "integer", "format": "int64", "description": "The ID of the product set." }, "DynamicAdsConfigSchema": { "type": "object", "required": [ "targeting_type" ], "description": "The Configuration of the dynamic ads.\nIf campaign is for dynamic ads, this object is required.\n", "properties": { "targeting_type": { "$ref": "#/components/schemas/TargetingType" }, "recency_days": { "$ref": "#/components/schemas/RecencyDays" }, "product_set_id": { "$ref": "#/components/schemas/ProductSetID" } } }, "AdGroupRequest": { "type": "object", "required": [ "name", "configured_status" ], "properties": { "name": { "$ref": "#/components/schemas/AdGroupSchemas_Name" }, "audience": { "$ref": "#/components/schemas/AudienceRequest" }, "frequency_control": { "$ref": "#/components/schemas/FrequencyControl" }, "configured_status": { "$ref": "#/components/schemas/ConfiguredStatus" }, "dynamic_ads_config": { "$ref": "#/components/schemas/DynamicAdsConfigSchema" } } }, "AdGroupID": { "type": "integer", "format": "int64", "description": "The ID of the ad group." }, "AdGroupSchemas_CreatedAt": { "type": "string", "format": "date-time", "description": "The date-time at which the ad group was created." }, "AdGroupSchemas_UpdatedAt": { "type": "string", "format": "date-time", "description": "The date-time at which the ad group was last updated." }, "LocationSegmentResponse": { "type": "object", "description": "The response of the hyper location segment resource.\n\nOnly one of `location_segment_pin_with_radius_info` or `location_segment_fixed_area_info` will be returned based on the segment_area_type value.\n", "required": [ "location_segment_id", "segment_area_type" ], "properties": { "location_segment_id": { "$ref": "#/components/schemas/LocationSegmentId" }, "segment_area_type": { "$ref": "#/components/schemas/SegmentAreaType" }, "pin_with_radius_info": { "$ref": "#/components/schemas/LocationSegmentPinWithRadiusInfo" }, "fixed_area_info": { "$ref": "#/components/schemas/LocationSegmentFixedAreaInfo" } } }, "HyperLocationConfigResponse": { "type": "object", "nullable": true, "description": "An object containing hyper location targeting configuration.\n", "required": [ "user_segment", "location_segments" ], "properties": { "user_segment": { "$ref": "#/components/schemas/UserSegment" }, "location_segments": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LocationSegmentResponse" }, "description": "The list of location segments being targeted.\n" } } }, "AudienceResponse": { "type": "object", "required": [ "ages", "genders", "custom_audiences", "locations" ], "properties": { "ages": { "$ref": "#/components/schemas/Ages" }, "genders": { "$ref": "#/components/schemas/Genders" }, "locations": { "$ref": "#/components/schemas/AdGroupLocations" }, "zip_codes": { "$ref": "#/components/schemas/ZipCodes" }, "hyper_location_config": { "$ref": "#/components/schemas/HyperLocationConfigResponse" }, "custom_audiences": { "$ref": "#/components/schemas/CustomAudiences" }, "operating_system": { "$ref": "#/components/schemas/OperatingSystem" }, "connection_types": { "$ref": "#/components/schemas/ConnectionTypes" }, "carrier_types": { "$ref": "#/components/schemas/CarrierTypes" }, "interests": { "$ref": "#/components/schemas/Interests" }, "media_types": { "$ref": "#/components/schemas/MediaTypes" }, "channel_alias_labels": { "$ref": "#/components/schemas/ChannelAliasLabels" }, "smart_view_article_category_targeting": { "$ref": "#/components/schemas/SmartViewArticleCategoryTargeting" }, "smart_view_article_keyword_targeting": { "$ref": "#/components/schemas/SmartViewArticleKeywordTargeting" }, "automated_targeting": { "$ref": "#/components/schemas/AutomatedTargeting" } } }, "AdGroupResponse": { "allOf": [ { "$ref": "#/components/schemas/AdGroupRequest" }, { "type": "object", "required": [ "ad_group_id", "campaign_id", "created_at", "updated_at", "parent", "audience", "delivery_status", "has_any_video_ads", "is_migrated_from_v1" ], "properties": { "campaign_id": { "$ref": "#/components/schemas/CampaignID" }, "ad_group_id": { "$ref": "#/components/schemas/AdGroupID" }, "created_at": { "$ref": "#/components/schemas/AdGroupSchemas_CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/AdGroupSchemas_UpdatedAt" }, "parent": { "$ref": "#/components/schemas/Parent" }, "audience": { "$ref": "#/components/schemas/AudienceResponse" }, "frequency_control": { "$ref": "#/components/schemas/FrequencyControl" }, "delivery_status": { "$ref": "#/components/schemas/DeliveryStatusObject" }, "has_any_video_ads": { "$ref": "#/components/schemas/HasAnyVideoAds" }, "is_migrated_from_v1": { "$ref": "#/components/schemas/IsMigratedFromV1" }, "dynamic_ads_config": { "$ref": "#/components/schemas/DynamicAdsConfigSchema" } } } ] }, "AdGroupPaginatedResponse": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdGroupResponse" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoResponse" } } }, "DynamicAdsConfigPatchSchema": { "type": "object", "description": "The Configuration of the dynamic ads for PATCH requests.\nIf campaign is for dynamic ads, this object is required.\n", "properties": { "targeting_type": { "$ref": "#/components/schemas/TargetingType" }, "recency_days": { "$ref": "#/components/schemas/RecencyDays" } } }, "AdGroupPatchRequest": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/AdGroupSchemas_Name" }, "configured_status": { "$ref": "#/components/schemas/ConfiguredStatus" }, "frequency_control": { "$ref": "#/components/schemas/FrequencyControl" }, "audience": { "$ref": "#/components/schemas/AudienceRequest" }, "dynamic_ads_config": { "$ref": "#/components/schemas/DynamicAdsConfigPatchSchema" } } }, "AdSchemas_Name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of an Ad. It is only used by customers to distinguish their Ads on Ads Manager.\n\nNote: Our standard length calculation rules apply to length validation: [See details](https://help-ads.smartnews.com/item-3888/)\n" }, "LandingPageUrl": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "URL of the Website which is opened when an Ad is clicked.\\\nIt 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`.\n 1. WEB_VIEW\n 2. BROWSER\nThe API will return a Validation Error if the field doesn't follow the below rules:\n1. URL format should follow the [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) spec\n2. All characters should be escaped accordingly, except macro parameters.\n3. Only http and https are allowed protocols.\n4. The following macro parameters are supported. The curly brackets characters `{` or `}` can only be used as part of the macro parameters.\n- `{ad_account_id}`\n- `{campaign_id}`\n- `{ad_group_id}`\n- `{ad_id}`\n- `{click_id}`\n" }, "CtaLabel": { "type": "string", "description": "If specified, a call to action button with the specified option is displayed on the ad (may not be displayed in all placements).", "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" ], "nullable": true }, "VendorType": { "type": "string", "enum": [ "DAR", "DCM" ], "description": "The vendor to use for impression measurement" }, "AdImpressionMeasurement": { "type": "object", "description": "Configuration for 3rd party ad impression measurement\n\nNote: This field is not settable for US region ad accounts.\n", "nullable": true, "required": [ "vendor_type", "measurement_url" ], "properties": { "vendor_type": { "$ref": "#/components/schemas/VendorType" }, "measurement_url": { "type": "string", "example": "https://example.com", "description": "The URL to use for impression measurement\n" } } }, "UrlTrackingParameters": { "type": "string", "minLength": 1, "maxLength": 256, "nullable": true, "example": "utm_source=smartnews&utm_medium=display&cp_id={campaign_id}", "description": "The parameters added to the landing page URL. This field is only supported for Dynamic Ads.\n\nThe API will return a Validation Error if the field doesn't follow the below rules:\n1. All characters should be escaped accordingly, except macro parameters.\n2. The following macro parameters are supported. The curly brackets characters `{` or `}` can only be used as part of the macro parameters.\n- `{ad_account_id}`\n- `{campaign_id}`\n- `{ad_group_id}`\n- `{ad_id}`\n- `{click_id}`\n" }, "PriceLabelEnabled": { "type": "boolean", "nullable": true, "description": "If `true`, show a price label on the ad. Otherwise, do not show.\n\nThis field is required when the parent campaign has `is_dynamic_ads` set to `true` and ad's creative is of \nCATALOG_CAROUSEL format type. \nOtherwise, this field is not settable.\n", "default": null }, "AdCreationParams": { "type": "object", "required": [ "name", "configured_status" ], "properties": { "name": { "$ref": "#/components/schemas/AdSchemas_Name" }, "landing_page_url": { "$ref": "#/components/schemas/LandingPageUrl" }, "cta_label": { "$ref": "#/components/schemas/CtaLabel" }, "configured_status": { "$ref": "#/components/schemas/ConfiguredStatus", "description": "Used for Call to Action Button. In the creative, corresponding translated UI text will be displayed in Creative.\n\nNo difference for the available Call To Action labels for each region.\n\nThis field is set automatically and not configurable if the `click_destination_type` of the Campaign is `APP_STORE` or `APP`.\n" }, "impression_measurement": { "$ref": "#/components/schemas/AdImpressionMeasurement" }, "url_tracking_parameters": { "$ref": "#/components/schemas/UrlTrackingParameters" }, "is_price_label_enabled": { "$ref": "#/components/schemas/PriceLabelEnabled" } } }, "ModerationElementType": { "type": "object", "required": [ "object", "field" ], "properties": { "object": { "type": "string", "enum": [ "AD", "CREATIVE" ], "description": "This specifies which object violates the policy\n" }, "field": { "type": "string", "nullable": true, "enum": [ "LANDING_PAGE_URL", "HEADLINE", "DESCRIPTION", "MEDIA_FILES", "SPONSORED_NAME", "CAROUSEL_CARDS" ], "description": "This specifies the field of the object that violates the policy. This can be null if the object itself violates the policy.\n" } } }, "RejectionReason": { "type": "object", "required": [ "policy", "description", "element_type", "element_id" ], "properties": { "policy": { "type": "string", "description": "The policy that the ad violated in the specified language\n", "example": "医薬品、医薬部外品、医療機器" }, "description": { "type": "string", "description": "The description of the policy that the ad violated in the specified language\n", "example": "[LP]医療関係者等の推薦にあたるためNG" }, "url": { "type": "string", "description": "URL to a help page for more details about the policy violation\n", "example": "https://help-ads.smartnews.com/item-876/#2" }, "element_type": { "$ref": "#/components/schemas/ModerationElementType" }, "element_id": { "type": "integer", "format": "int64", "description": "id that uniquely identifies the element that was rejected.\nCurrently, `CREATIVE_IMAGE` is the only element type that you cannot uniquely identify the element without `element_id`.\nHowever, for consistency, `element_id` is also set for other element types.\nThe `element_id` is one of the following:\n| Element Type ([object].[field]) | value |\n|------------------------------------------------------------------|--------------------------------|\n| AD,AD.LANDING_PAGE_URL | ad_id |\n| CREATIVE.MEDIA_FILES | media_file_id |\n| CREATIVE.HEADLINE, CREATIVE.DESCRIPTION, CREATIVE.SPONSORED_NAME | creative_id |\n| CREATIVE.CAROUSEL_CARDS | index position in cards from 0 |\n" } } }, "Headline": { "type": "string", "minLength": 10, "maxLength": 70, "description": "Headline text of a Creative.\n\nNote: The validated length is calculated by our standard length calculation rules: [See details](https://help-ads.smartnews.com/item-3888/)\n\nMaximum length of the headline changes depending on the creative format.\n| Creative Format | Max Length |\n| --------------- | ---------- |\n| IMAGE,CAROUSEL | 70 |\n| VIDEO | 56 |\n\nA Validation Error will also be returned if the field contains illegal characters or illegal character sequences.\n\n**Dynamic Tags (controlled by feature flag `AMV2-1031`):**\n\nWhen the feature flag is enabled, the headline supports dynamic tags that are replaced with user location data during ad delivery.\n\nSupported tags (case-insensitive):\n- For US region ad accounts: `{state}`, `{city}`\n- For JP region ad accounts: `{prefecture}`, `{city}`\n\nTag validation rules:\n- Only the supported tags listed above are allowed\n- Tags must use the exact format with curly brackets: `{tag_name}`\n- When the feature flag is disabled, any `{` or `}` characters in the text will be rejected\n- Dynamic Ads (campaigns with `is_dynamic_ads` = `true`) do not support dynamic tags\n\nTag replacement during delivery:\n- Tags are replaced with the user's location based on the ad group's targeting configuration\n- If no user location is available, fallback text is used:\n - US: `{state}` → \"Your area\", `{city}` → \"Your area\"\n - JP: `{prefecture}` → \"この地域\", `{city}` → \"この地域\"\n\nPreview mock values:\n- US: `{state}` → \"California\", `{city}` → \"Los Angeles\"\n- JP: `{prefecture}` → \"東京都\", `{city}` → \"新宿区\"\n" }, "Description": { "type": "string", "minLength": 10, "maxLength": 180, "description": "Description text of a Creative. This is used when an Ad is displayed in SmartView.\n- Required if the creative format is `IMAGE`.\n- Must be null for other formats.\n\nNote: The validated length is calculated by our standard length calculation rules: [See details](https://help-ads.smartnews.com/item-3888/)\n\nA Validation Error will also be returned if the field contains illegal characters or illegal character sequences.\n\n**Dynamic Tags (controlled by feature flag `AMV2-1031`):**\n\nWhen the feature flag is enabled, the description supports dynamic tags that are replaced with user location data during ad delivery.\n\nSupported tags (case-insensitive):\n- For US region ad accounts: `{state}`, `{city}`\n- For JP region ad accounts: `{prefecture}`, `{city}`\n\nTag validation rules:\n- Only the supported tags listed above are allowed\n- Tags must use the exact format with curly brackets: `{tag_name}`\n- When the feature flag is disabled, any `{` or `}` characters in the text will be rejected\n- Dynamic Ads (campaigns with `is_dynamic_ads` = `true`) do not support dynamic tags\n\nTag replacement during delivery:\n- Tags are replaced with the user's location based on the ad group's targeting configuration\n- If no user location is available, fallback text is used:\n - US: `{state}` → \"Your area\", `{city}` → \"Your area\"\n - JP: `{prefecture}` → \"この地域\", `{city}` → \"この地域\"\n\nPreview mock values:\n- US: `{state}` → \"California\", `{city}` → \"Los Angeles\"\n- JP: `{prefecture}` → \"東京都\", `{city}` → \"新宿区\"\n" }, "SponsoredName": { "type": "string", "minLength": 1, "maxLength": 22, "description": "Name of advertiser/service name/brand name/product name etc which is displayed to users to show the sponsorship of Ad.\n\nNote: The validated length is calculated by our standard length calculation rules: [See details](https://help-ads.smartnews.com/item-3888/)\n" }, "MediaType": { "type": "string", "description": "The type of the media file.", "enum": [ "IMAGE", "VIDEO" ] }, "ImageResponse": { "type": "object", "required": [ "width", "height", "url", "filesize", "aspect_ratio_type", "image_scale", "created_at" ], "properties": { "width": { "type": "integer", "description": "The width of the ad image in pixels." }, "height": { "type": "integer", "description": "The height of the ad image in pixels." }, "url": { "$ref": "#/components/schemas/Url" }, "filesize": { "type": "integer", "description": "The file size of image file." }, "aspect_ratio_type": { "$ref": "#/components/schemas/AspectRatioType" }, "image_scale": { "type": "string", "enum": [ "FULL", "HALF", "ORIGINAL" ], "description": "The scale of the image according to the delivery spec." }, "created_at": { "type": "string", "format": "date-time", "description": "The date-time at which this record was created." } } }, "VideoResponse": { "type": "object", "required": [ "width", "height", "url", "length", "filesize", "aspect_ratio_type", "video_quality", "created_at" ], "properties": { "width": { "type": "integer", "description": "The width of the ad video in pixels." }, "height": { "type": "integer", "description": "The height of the ad video in pixels." }, "url": { "$ref": "#/components/schemas/VideoSchemas_Url" }, "length": { "type": "integer", "description": "The length of the video in ms." }, "filesize": { "type": "integer", "description": "The file size of video file." }, "aspect_ratio_type": { "$ref": "#/components/schemas/AspectRatioType" }, "video_quality": { "type": "string", "enum": [ "ORIGINAL", "HIGH", "MIDDLE", "LOW" ], "description": "The quality of the video according to the delivery spec." }, "created_at": { "type": "string", "format": "date-time", "description": "The date-time at which this record was created" } } }, "MediaFileStatus": { "type": "string", "description": "The status of the media file.\n- `ACTIVE`: The media file is visible in the Media Library.\n- `INACTIVE`: The media file has been soft-deleted and is no longer visible in the Media Library.\n\nNote: Even if a media file is set to `INACTIVE`, it will still be visible in the creatives where it is used.\n", "enum": [ "ACTIVE", "INACTIVE" ] }, "MediaFileResponse": { "type": "object", "required": [ "media_file_id", "ad_account_id", "media_type", "file_name", "images", "created_at", "status" ], "properties": { "media_file_id": { "type": "integer", "format": "int64", "description": "ID of the media file." }, "ad_account_id": { "type": "integer", "format": "int64", "description": "ID of the Ad Account that the media file belongs to." }, "media_type": { "$ref": "#/components/schemas/MediaType" }, "file_name": { "type": "string", "description": "Name of the media file when the file is uploaded." }, "images": { "type": "object", "required": [ "full", "half", "original" ], "properties": { "full": { "$ref": "#/components/schemas/ImageResponse" }, "half": { "$ref": "#/components/schemas/ImageResponse" }, "original": { "$ref": "#/components/schemas/ImageResponse" } }, "description": "The definitions of this field are different depending on the Media Type:\n| Media Type | Definition |\n|------------|------------------------------------------------------|\n| IMAGE | The image files (Full/Half/Original). |\n| VIDEO | The auto-generated thumbnails of the uploaded video. |\n" }, "videos": { "type": "object", "required": [ "high", "middle", "low", "original" ], "properties": { "high": { "$ref": "#/components/schemas/VideoResponse" }, "middle": { "$ref": "#/components/schemas/VideoResponse" }, "low": { "$ref": "#/components/schemas/VideoResponse" }, "original": { "$ref": "#/components/schemas/VideoResponse" } }, "description": "The video files (High/Middle/Low/Original)." }, "thumbnail_media_file_id": { "type": "integer", "format": "int64", "description": "The media_file_id of the auto-generated thumbnail. Only Available for `VIDEO` media file." }, "created_at": { "type": "string", "format": "date-time", "description": "The date-time at which the media file was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date-time at which the media file was last updated." }, "status": { "$ref": "#/components/schemas/MediaFileStatus" } } }, "ImageCreativeInfoResponse": { "type": "object", "required": [ "headline", "description", "sponsored_name", "media_files" ], "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "description": { "$ref": "#/components/schemas/Description" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" }, "media_files": { "type": "array", "items": { "$ref": "#/components/schemas/MediaFileResponse" }, "description": "Only image media files are returned.\n" } } }, "VideoCreativeInfoResponse": { "type": "object", "required": [ "headline", "sponsored_name", "format", "media_files" ], "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" }, "media_files": { "type": "array", "items": { "$ref": "#/components/schemas/MediaFileResponse" } } } }, "CarouselCardResponse": { "type": "object", "description": "Caption and Media file combination for carousel format.\n", "required": [ "caption", "media_file" ], "properties": { "caption": { "type": "string", "minLength": 5, "maxLength": 50 }, "media_file": { "description": "The image for the carousel needs to be 1:1 aspect ratio.", "$ref": "#/components/schemas/MediaFileResponse" } } }, "CarouselCreativeInfoResponse": { "type": "object", "required": [ "headline", "sponsored_name", "carousel_cards" ], "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" }, "carousel_cards": { "type": "array", "items": { "$ref": "#/components/schemas/CarouselCardResponse" } } } }, "CatalogCarouselCreativeInfoResponse": { "type": "object", "required": [ "headline", "sponsored_name" ], "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" } } }, "CatalogImageCreativeInfoRequestResponse": { "type": "object", "description": "Required when `format` is `CATALOG_IMAGE`.\n\nNote: This field is not settable for US region ad accounts.\n", "required": [ "sponsored_name" ], "properties": { "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" } } }, "CreativeResponse": { "type": "object", "required": [ "format", "creative_id", "created_at", "updated_at" ], "properties": { "format": { "$ref": "#/components/schemas/Format" }, "creative_id": { "type": "integer", "format": "int64", "description": "The ID of the creative." }, "created_at": { "type": "string", "format": "date-time", "description": "The date-time at which the adgroup was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date-time at which the adgroup was last updated." }, "image_creative_info": { "$ref": "#/components/schemas/ImageCreativeInfoResponse" }, "video_creative_info": { "$ref": "#/components/schemas/VideoCreativeInfoResponse" }, "carousel_creative_info": { "$ref": "#/components/schemas/CarouselCreativeInfoResponse" }, "catalog_carousel_creative_info": { "$ref": "#/components/schemas/CatalogCarouselCreativeInfoResponse" }, "catalog_image_creative_info": { "$ref": "#/components/schemas/CatalogImageCreativeInfoRequestResponse" } }, "description": "The response of the creative resource.\n\nOnly one of `image_creative_info`, `video_creative_info`, `carousel_creative_info`, `catalog_carousel_creative_info`, or `catalog_image_creative_info` will be returned based on the format of the creative.\n" }, "AdResponse": { "allOf": [ { "$ref": "#/components/schemas/AdCreationParams" }, { "type": "object", "required": [ "ad_id", "ad_account_id", "click_destination_type", "moderation_status", "submission_status", "creative", "created_at", "updated_at", "parent", "delivery_status", "is_migrated_from_v1" ], "properties": { "ad_id": { "type": "integer", "format": "int64", "description": "The ID of the ad object." }, "click_destination_type": { "$ref": "#/components/schemas/ClickDestinationType" }, "moderation_status": { "$ref": "#/components/schemas/ModerationStatus" }, "rejection_reasons": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/RejectionReason" }, "description": "The reasons why the ad was rejected.\nThis field is only returned when the `moderation_status` is `REJECTED`.\n" }, "submission_status": { "$ref": "#/components/schemas/SubmissionStatus" }, "creative": { "$ref": "#/components/schemas/CreativeResponse" }, "created_at": { "type": "string", "format": "date-time", "description": "The date-time at which the ad was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The date-time at which the ad was last updated." }, "parent": { "$ref": "#/components/schemas/Parent" }, "delivery_status": { "$ref": "#/components/schemas/DeliveryStatusObject" }, "impression_measurement": { "$ref": "#/components/schemas/AdImpressionMeasurement" }, "is_migrated_from_v1": { "type": "boolean", "description": "A boolean flag that, when `true`, indicates that the ad is migrated from v1." }, "is_price_label_enabled": { "$ref": "#/components/schemas/PriceLabelEnabled" } } } ] }, "AdPaginatedResponse": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdResponse" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoResponse" } } }, "MediaFileIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "List of Media File IDs which will be used for a Creative.\n\nMedia Files can be created via the `POST media_files` endpoint.\n\nThe specified Media Files must belong to the same ad account which the ad belongs to, otherwise the API returns a Resource Not Found Error.\n\nOnly 1 image per aspect ratio type can be added per request.\n- When `format` of the creative = `IMAGE`, one of the following combinations of images is accepted:\n 1. Required: `ASPECT_RATIO_1_1`, `ASPECT_RATIO_191_100`. Optional: `ASPECT_RATIO_6_5`, `ASPECT_RATIO_16_9`\n 2. Required: `ASPECT_RATIO_1_1`, `ASPECT_RATIO_6_5`, `ASPECT_RATIO_16_9`, Optional: `ASPECT_RATIO_191_100`\n 3. [When parent campaign's `is_large_unit_square_ads` field is set to `true`] Required: `ASPECT_RATIO_1_1` with at least 600 x 600 resolution\n- When `format` of the creative = `VIDEO`, it requires exactly a pair of `VIDEO` and `IMAGE` `media_file_id`s\n - VIDEO: (Please check the spec in `POST /api/v1/ad_accounts/{ad_account_id}/media_files`)\\\n - IMAGE: Must be an `ASPECT_RATIO_16_9` image\n" }, "ImageCreativeInfoRequest": { "type": "object", "description": "Required when `format` is `IMAGE`.", "required": [ "headline", "description", "sponsored_name", "media_file_ids" ], "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "description": { "$ref": "#/components/schemas/Description" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" }, "media_file_ids": { "$ref": "#/components/schemas/MediaFileIds" } } }, "VideoCreativeInfoRequest": { "type": "object", "description": "Required when `format` is `VIDEO`.", "required": [ "headline", "sponsored_name", "media_file_ids" ], "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" }, "media_file_ids": { "$ref": "#/components/schemas/MediaFileIds" } } }, "CarouselCardMediaFileId": { "type": "integer", "format": "int64", "description": "The Id of the media file. Only image is supported.\nThe image for the carousel needs to be 1:1 aspect ratio.\n" }, "CarouselCardRequest": { "type": "object", "description": "Combination of image and caption text for carousel format.\n", "required": [ "caption", "media_file_id" ], "properties": { "caption": { "type": "string", "minLength": 5, "maxLength": 50 }, "media_file_id": { "$ref": "#/components/schemas/CarouselCardMediaFileId" } } }, "CarouselCreativeInfoRequest": { "type": "object", "description": "Required when `format` is `CAROUSEL`.\n\nNote: This field is not settable for US region ad accounts.\n", "required": [ "headline", "sponsored_name", "carousel_cards" ], "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" }, "carousel_cards": { "type": "array", "items": { "$ref": "#/components/schemas/CarouselCardRequest" }, "minItems": 3, "maxItems": 10, "description": "The order in the array represents the order of the cards.\n" } } }, "CatalogCarouselCreativeInfoRequest": { "type": "object", "description": "Required when `format` is `CATALOG_CAROUSEL`.\n\nNote: This field is not settable for US region ad accounts.\n", "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" } }, "required": [ "headline", "sponsored_name" ] }, "CreativeRequest": { "type": "object", "required": [ "format" ], "properties": { "format": { "$ref": "#/components/schemas/Format" }, "image_creative_info": { "$ref": "#/components/schemas/ImageCreativeInfoRequest" }, "video_creative_info": { "$ref": "#/components/schemas/VideoCreativeInfoRequest" }, "carousel_creative_info": { "$ref": "#/components/schemas/CarouselCreativeInfoRequest" }, "catalog_carousel_creative_info": { "$ref": "#/components/schemas/CatalogCarouselCreativeInfoRequest" }, "catalog_image_creative_info": { "$ref": "#/components/schemas/CatalogImageCreativeInfoRequestResponse" } } }, "AdRequest": { "allOf": [ { "$ref": "#/components/schemas/AdCreationParams" }, { "type": "object", "properties": { "creative": { "allOf": [ { "$ref": "#/components/schemas/CreativeRequest" } ], "description": "The `creative` to configure for the ad.\n\nDepending on the format, the corresponding `*_info` object is required.\n\nFor example, if `format` is `IMAGE`, `image_creative_info` is required. If `format` is `VIDEO`, `video_creative_info` is required, and so on.\n" } }, "required": [ "creative" ] } ] }, "ImageCreativeInfoPatchRequest": { "type": "object", "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "description": { "$ref": "#/components/schemas/Description" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" }, "media_file_ids": { "$ref": "#/components/schemas/MediaFileIds" } } }, "VideoCreativeInfoPatchRequest": { "type": "object", "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" }, "media_file_ids": { "$ref": "#/components/schemas/MediaFileIds" } } }, "CarouselCreativeInfoPatchRequest": { "type": "object", "properties": { "headline": { "$ref": "#/components/schemas/Headline" }, "sponsored_name": { "$ref": "#/components/schemas/SponsoredName" }, "carousel_cards": { "type": "array", "items": { "$ref": "#/components/schemas/CarouselCardRequest" }, "minItems": 3, "maxItems": 10, "description": "The order in the array represents the order of the cards.\n" } } }, "CreativePatchRequest": { "type": "object", "properties": { "image_creative_info": { "$ref": "#/components/schemas/ImageCreativeInfoPatchRequest" }, "video_creative_info": { "$ref": "#/components/schemas/VideoCreativeInfoPatchRequest" }, "carousel_creative_info": { "$ref": "#/components/schemas/CarouselCreativeInfoPatchRequest" }, "catalog_carousel_creative_info": { "$ref": "#/components/schemas/CatalogCarouselCreativeInfoRequest" }, "catalog_image_creative_info": { "$ref": "#/components/schemas/CatalogImageCreativeInfoRequestResponse" } } }, "AdPatchRequest": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/AdSchemas_Name" }, "configured_status": { "$ref": "#/components/schemas/ConfiguredStatus" }, "landing_page_url": { "$ref": "#/components/schemas/LandingPageUrl" }, "cta_label": { "$ref": "#/components/schemas/CtaLabel" }, "submission_status": { "$ref": "#/components/schemas/SubmissionStatus" }, "creative": { "$ref": "#/components/schemas/CreativePatchRequest" }, "impression_measurement": { "$ref": "#/components/schemas/AdImpressionMeasurement" }, "is_price_label_enabled": { "$ref": "#/components/schemas/PriceLabelEnabled" } } }, "MediaFilePaginatedResponse": { "type": "object", "description": "A paginated list of media files with pagination metadata.", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaFileResponse" } }, "pagination": { "$ref": "#/components/schemas/PaginationInfoResponse" } } }, "MediaFileRequest": { "type": "object", "required": [ "file_name", "media_type", "media_file" ], "properties": { "file_name": { "description": "The filename of the uploaded file.\n", "type": "string" }, "media_type": { "$ref": "#/components/schemas/MediaType" }, "media_file": { "type": "string", "format": "binary", "description": "If the same file has been uploaded under the same ad account in the past, the existing media file will be returned.\n\nThere are 2 types of media which can be uploaded:\n- IMAGE\n- VIDEO\n\n## 1. IMAGE\n\nActual Image file to be uploaded to represent the visual image.\\\nMax File Size: 5 MiB\\\nAn image which width exceeds Full Size Max Width will be automatically resized to Full Size Max Width.\\\nA small size image can be uploaded if its width exceeds Min Width.\\\nThe aspect ratio of the image must match one the of pre-defined aspect ratios.\\\nMin Width and Full Size Max Width for each pre-defined Aspect Ratio Type are as follows:\n\n| Pre-defined aspect ratio | Min Width | Full Size Max Width | Example image size |\n|--------------------------|--------------|---------------------|--------------------|\n| 1:1 | 300 pixels | 600 pixels | 300px x 300px |\n| 6:5 | 500 pixels | 1080 pixels | 600px x 500px |\n| 16:9 | 600 pixels | 1280 pixels | 1280px x 720px |\n| 1.91:1 | 600 pixels | 1280 pixels | 1200px x 628px |\n\nAllowed Format\n - JPEG\n - PNG\n - GIF (animated GIF is not allowed)\n\n## 2. VIDEO\nActual Video file to be uploaded to represent the visual video.\n\n### Videos that pass the below conditions are allowed to upload:\n- Video Length: 3 (seconds) <= video length <= 60 (seconds)\n- Aspect Ratio: 16:9\n- Minimum Video Resolution: 360p\n- Maximum File size: 100 MiB\n\nAllowed Format\n - MP4\n" } } }, "GatewayTimeoutErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorBase" } } }, "Region": { "type": "string", "enum": [ "JP", "US" ], "x-enum-varnames": [ "JP", "US" ] }, "CommonSchemas_LocationId": { "type": "integer", "format": "int32", "example": 70149, "description": "The location ID which can be used for AdGroup level location targeting." }, "LocationNameJapanese": { "type": "string", "example": "北海道", "description": "The name of the location in Japanese." }, "LocationNameEnglish": { "type": "string", "example": "Hokkaido", "description": "The name of the location in English." }, "LocationNameData": { "type": "object", "required": [ "location_id", "ja", "en" ], "properties": { "location_id": { "$ref": "#/components/schemas/CommonSchemas_LocationId" }, "ja": { "$ref": "#/components/schemas/LocationNameJapanese" }, "en": { "$ref": "#/components/schemas/LocationNameEnglish" } } }, "Locations": { "type": "object", "required": [ "location_id", "ja", "en", "children" ], "properties": { "location_id": { "$ref": "#/components/schemas/CommonSchemas_LocationId" }, "ja": { "$ref": "#/components/schemas/LocationNameJapanese" }, "en": { "$ref": "#/components/schemas/LocationNameEnglish" }, "children": { "type": "array", "description": "An array of locations which are geographically contained within this location.\n", "items": { "$ref": "#/components/schemas/LocationNameData" } } } }, "ArticleCategoryId": { "type": "integer", "format": "int32" }, "ArticleCategoryMasterName": { "type": "object", "required": [ "en", "ja" ], "properties": { "en": { "type": "string", "description": "The English name of the article category.", "example": "Sports" }, "ja": { "type": "string", "description": "The Japanese name of the article category.", "example": "スポーツ" } } }, "ArticleCategoryMaster": { "type": "object", "required": [ "id", "parent_id", "name", "children" ], "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/ArticleCategoryId" } ], "description": "The unique ID of the article category.", "example": 1 }, "parent_id": { "allOf": [ { "$ref": "#/components/schemas/ArticleCategoryId" } ], "nullable": true, "description": "The parent category ID.\nA `null` value indicates a root category.\n", "example": null }, "name": { "$ref": "#/components/schemas/ArticleCategoryMasterName" }, "children": { "type": "array", "description": "Child categories under this category.", "items": { "$ref": "#/components/schemas/ArticleCategoryMaster" } } } }, "ArticleCategoryMasterResponse": { "type": "array", "description": "A nested tree of article category master data for contextual targeting.\n", "items": { "$ref": "#/components/schemas/ArticleCategoryMaster" }, "example": [ { "id": 1, "parent_id": null, "name": { "en": "Sports", "ja": "スポーツ" }, "children": [ { "id": 101, "parent_id": 1, "name": { "en": "Baseball", "ja": "野球" }, "children": [] } ] } ] }, "SmartViewArticleKeywordSearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "array", "description": "The list of keywords to search suggestions for.\n\nEach keyword supports both EN and JA input. Must be between 1 and 80 characters.\n\nNote: The maximum length is calculated by our standard length calculation rules: [See details](https://help-ads.smartnews.com/item-3888/)\n", "minItems": 1, "maxItems": 1000, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "size": { "type": "integer", "format": "int32", "description": "The maximum number of suggestions to return per keyword. Defaults to 20.\n\nValues less than 1 are rejected with a validation error. Values greater\nthan 20 are rejected with a validation error.\n", "minimum": 1, "maximum": 20, "default": 20 } } }, "SmartViewArticleKeywordSearchResponse": { "type": "object", "description": "A map of each input keyword to its list of suggested keywords sorted by relevance in descending order.\nWhen no matches are found for a keyword, an empty array is returned for that key.\n", "additionalProperties": { "type": "array", "items": { "type": "string", "description": "The preset article keyword suggestion." } }, "example": { "Ramen": [ "Ramen", "ラーメン" ], "Tokyo": [ "Tokyo", "東京" ] } }, "ChannelAliasLabelMasterName": { "type": "object", "required": [ "en", "ja" ], "properties": { "en": { "type": "string", "description": "The English name of the channel alias label.", "example": "News" }, "ja": { "type": "string", "description": "The Japanese name of the channel alias label.", "example": "ニュース" } } }, "ChannelAliasLabelMaster": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "The unique ID of the channel alias label.", "example": "CR_JA_TOP" }, "name": { "$ref": "#/components/schemas/ChannelAliasLabelMasterName" } } }, "ChannelAliasLabelMasterResponse": { "type": "array", "description": "An array of channel alias label master data.\n", "items": { "$ref": "#/components/schemas/ChannelAliasLabelMaster" }, "example": [ { "id": "CR_JA_TOP", "name": { "en": "News", "ja": "ニュース" } }, { "id": "CR_JA_POLITICS", "name": { "en": "Politics", "ja": "政治" } } ] }, "DisplayName": { "type": "object", "required": [ "en", "ja" ], "properties": { "en": { "type": "string", "example": "Food", "description": "The English name of the interest category." }, "ja": { "type": "string", "example": "食べ物", "description": "The Japanese name of the interest category." } } }, "IABInterestCategory": { "type": "object", "required": [ "iab_interest_category_id", "iab_interest_category_name", "display_name", "parent_iab_interest_category_id" ], "properties": { "iab_interest_category_id": { "example": 100, "type": "integer", "format": "int32", "description": "The interest category ID which can be used for AdGroup level interest targeting." }, "iab_interest_category_name": { "example": "Food", "type": "string", "description": "The name of the interest category." }, "display_name": { "$ref": "#/components/schemas/DisplayName" }, "parent_iab_interest_category_id": { "example": 1, "type": "integer", "format": "int32", "description": "The parent interest category ID. A value of `0` means there is no parent." } } }, "AdAccountId": { "type": "integer", "format": "int64", "description": "Unique ID of the ad account." }, "UserId": { "type": "integer", "format": "int64", "description": "Unique ID of the user who created the pixel." }, "CommonSchemas_Name": { "type": "string", "description": "The name of the pixel." }, "PixelTagId": { "type": "string", "example": "71ccbe033ff6837c48e6c3c6", "description": "Unique ID of the pixel which is used in tracking scripts." }, "CommonSchemas_CreatedAt": { "type": "string", "format": "date-time", "description": "The DateTime when the object was created." }, "PixelResponse": { "type": "object", "required": [ "user_id", "name", "pixel_tag_id", "created_at" ], "properties": { "user_id": { "$ref": "#/components/schemas/UserId" }, "name": { "$ref": "#/components/schemas/CommonSchemas_Name" }, "pixel_tag_id": { "$ref": "#/components/schemas/PixelTagId" }, "created_at": { "$ref": "#/components/schemas/CommonSchemas_CreatedAt" } } }, "PixelValidationStatus": { "type": "string", "enum": [ "EVENTS_RECEIVED", "PIXEL_NOT_FIRING", "CONVERSION_EVENTS_MISSING", "CONVERSION_EVENTS_NOT_MAPPING", "PARAMETERS_ERROR" ], "description": "* `EVENTS_RECEIVED` - Events received\n* `PIXEL_NOT_FIRING` - Pixel not firing\n* `CONVERSION_EVENTS_MISSING` - Conversion Events missing (pixel base code is implemented)\n* `CONVERSION_EVENTS_NOT_MAPPING` - Conversion Events not mapping to our list (pixel base code is implemented)\n* `PARAMETERS_ERROR` - Additional parameters error\n" }, "LastEventDateTime": { "type": "string", "format": "date-time", "nullable": true, "description": "The timestamp at which the last event was received for this pixel." }, "PixelWithValidationResponse": { "allOf": [ { "$ref": "#/components/schemas/PixelResponse" }, { "type": "object", "required": [ "last_event_date_time" ], "properties": { "status": { "$ref": "#/components/schemas/PixelValidationStatus" }, "last_event_date_time": { "$ref": "#/components/schemas/LastEventDateTime" } } } ] }, "PixelWithValidationArrayResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PixelWithValidationResponse" } } } }, "WebActivityRuleSchemas_PixelTagId": { "type": "string", "example": "71ccbe033ff6837c48e6c3c6", "description": "The pixel_tag_id of the pixel to target for this rule" }, "CustomAudienceEvent": { "type": "string", "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", "PAGE_VIEW" ], "nullable": true, "description": "Conversion event for custom audience to target." }, "Events": { "type": "array", "items": { "$ref": "#/components/schemas/CustomAudienceEvent" }, "description": "The events to target for this rule." }, "Urls": { "type": "array", "items": { "type": "string", "example": "http://example.com", "description": "A list of URLs to be used for the custom audience rule.\"" } }, "TimePeriod": { "type": "string", "description": "Past number of days of user activity to consider when creating the uuid list for the rule.\n\nOnly certain ad accounts can use `LAST_365_DAYS` and `LAST_540_DAYS`.\n", "enum": [ "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "LAST_60_DAYS", "LAST_90_DAYS", "LAST_365_DAYS", "LAST_540_DAYS" ] }, "CommonSchemas_UpdatedAt": { "type": "string", "format": "date-time", "description": "The DateTime when the object was last updated." }, "WebActivityRuleResponse": { "type": "object", "required": [ "custom_audience_web_activity_rule_id", "pixel_tag_id", "events", "urls", "time_period", "created_at", "updated_at" ], "properties": { "custom_audience_web_activity_rule_id": { "type": "integer", "format": "int64", "description": "Unique ID of the rule." }, "pixel_tag_id": { "$ref": "#/components/schemas/WebActivityRuleSchemas_PixelTagId" }, "events": { "$ref": "#/components/schemas/Events" }, "urls": { "$ref": "#/components/schemas/Urls" }, "time_period": { "$ref": "#/components/schemas/TimePeriod" }, "created_at": { "$ref": "#/components/schemas/CommonSchemas_CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/CommonSchemas_UpdatedAt" } } }, "AdGroupIds": { "description": "An array of Ad Group IDs to target engagement for.", "type": "array", "minItems": 1, "items": { "type": "number", "format": "int64" } }, "Action": { "type": "string", "description": "The user action to consider as engagement.", "enum": [ "CLICK", "VIEWABLE_IMPRESSION", "CONVERSION" ] }, "AdsEngagementRuleResponse": { "type": "object", "required": [ "custom_audience_ads_engagement_rule_id", "ad_group_ids", "action", "time_period", "created_at", "updated_at" ], "properties": { "custom_audience_ads_engagement_rule_id": { "type": "integer", "format": "int64", "description": "Unique ID of the rule." }, "ad_group_ids": { "$ref": "#/components/schemas/AdGroupIds" }, "action": { "$ref": "#/components/schemas/Action" }, "time_period": { "$ref": "#/components/schemas/TimePeriod" }, "created_at": { "$ref": "#/components/schemas/CommonSchemas_CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/CommonSchemas_UpdatedAt" } } }, "AudienceIdListFileId": { "type": "integer", "format": "int64", "description": "Unique identifier of the audience ID list file.\n" }, "FileType": { "type": "string", "description": "The type of the audience ID list file.", "enum": [ "ADID_SHA256" ] }, "OriginalFileName": { "minLength": 1, "maxLength": 255, "description": "Filename of the audience ID list file.\n", "type": "string", "example": "my_list.csv" }, "AudienceIdListRuleResponse": { "type": "object", "required": [ "custom_audience_audience_id_list_rule_id", "audience_id_list_file_id", "file_type", "original_file_name", "created_at", "updated_at" ], "properties": { "custom_audience_audience_id_list_rule_id": { "type": "integer", "format": "int64", "description": "Unique ID of the rule." }, "audience_id_list_file_id": { "$ref": "#/components/schemas/AudienceIdListFileId" }, "file_type": { "$ref": "#/components/schemas/FileType" }, "original_file_name": { "$ref": "#/components/schemas/OriginalFileName" }, "created_at": { "$ref": "#/components/schemas/CommonSchemas_CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/CommonSchemas_UpdatedAt" } } }, "KeywordWindow": { "description": "Period Window for the keyword mapping of keyword custom audience.\n", "type": "string", "enum": [ "LAST_3_DAYS", "LAST_7_DAYS", "LAST_14_DAYS", "LAST_30_DAYS", "LAST_60_DAYS", "LAST_90_DAYS", "LAST_120_DAYS", "LAST_150_DAYS", "LAST_180_DAYS", "LAST_210_DAYS", "LAST_240_DAYS", "LAST_270_DAYS", "LAST_300_DAYS", "LAST_330_DAYS", "LAST_360_DAYS", "LAST_390_DAYS" ] }, "KeywordFrequency": { "description": "Frequency for the keyword mapping of keyword custom audience.\n", "type": "integer", "format": "int64", "minimum": 1, "maximum": 15 }, "Keywords": { "description": "Keywords for keyword custom audience. If there is a duplicated keyword, it will return an error.\n\nEmpty strings are not allowed.\n\nThe following characters are not allowed:\n- single JP Character including あ、い.. ア、イ.. (but allow single Kanji)\n- punctuation including ,、“、(、%、&…\n- spaces (single-width and double-width)\n", "type": "array", "items": { "type": "string", "maxLength": 128, "minLength": 1 }, "minItems": 3, "maxItems": 120, "uniqueItems": true }, "KeywordRuleResponse": { "type": "object", "required": [ "custom_audience_keyword_rule_id", "window", "frequency", "keywords", "created_at", "updated_at" ], "properties": { "custom_audience_keyword_rule_id": { "type": "integer", "format": "int64", "description": "Unique ID of the rule." }, "window": { "$ref": "#/components/schemas/KeywordWindow" }, "frequency": { "$ref": "#/components/schemas/KeywordFrequency" }, "keywords": { "$ref": "#/components/schemas/Keywords" }, "created_at": { "$ref": "#/components/schemas/CommonSchemas_CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/CommonSchemas_UpdatedAt" } } }, "CustomAudienceSchemas_Name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "My Custom Audience", "description": "The name of the custom audience.\nPlease check [this document](https://help-ads.smartnews.com/item-3888/) for how the length is calculated.\n" }, "Type": { "type": "string", "enum": [ "WEB_ACTIVITY", "ADS_ENGAGEMENT", "AUDIENCE_ID_LIST_FILE", "KEYWORD", "LEGACY" ], "description": "The type of the custom audience. `LEGACY` custom audiences are those that were created in AMv1." }, "RulesCombiningLogic": { "type": "string", "enum": [ "AND", "OR" ], "description": "How the rules will be combined for this custom audience." }, "AvailabilityStatus": { "type": "string", "enum": [ "IN_PROGRESS", "FAILURE", "TOO_NARROW", "NARROW", "AVAILABLE", "UNUSED" ], "description": "The status of the custom audience processing, indicating whether it is ready to be used in AdGroup targeting or not." }, "UniqueAudienceCount": { "type": "integer", "format": "int64", "description": "The number of unique users in the custom audience.\nThis field is only valid when the `availability_status` is `AVAILABLE/TOO_NARROW/NARROW`.\n", "nullable": true }, "CustomAudienceResult": { "type": "object", "description": "The result of the custom audience backend processing.", "required": [ "availability_status", "uniqueAudienceCount", "created_at", "updated_at" ], "properties": { "availability_status": { "$ref": "#/components/schemas/AvailabilityStatus" }, "created_at": { "$ref": "#/components/schemas/CommonSchemas_CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/CommonSchemas_UpdatedAt" }, "unique_audience_count": { "$ref": "#/components/schemas/UniqueAudienceCount" } } }, "CustomAudienceConfiguredStatus": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED" ], "description": "- `ACTIVE`: The audience will be updated periodically based on the latest data.\n- `PAUSED`: The audience will not be updated until reactivated.\n- `DELETED`: The audience is deleted and cannot be used in Ad Group targeting.\n" }, "CustomAudienceResponse": { "type": "object", "description": "In Legacy Custom Audiences (type: LEGACY), only the `name`, `custom_audience_id` and `type` fields are valid.\nOther fields are dummy data.\n", "required": [ "custom_audience_id", "name", "type", "rules_combining_logic", "result", "configured_status", "created_at", "updated_at" ], "properties": { "custom_audience_id": { "type": "integer", "format": "int64", "description": "Unique ID of the custom audience." }, "web_activity_rules": { "type": "array", "description": "An array of web activity rules for this custom audience. It is `null` unless `type` is `WEB_ACTIVITY`.", "nullable": true, "items": { "$ref": "#/components/schemas/WebActivityRuleResponse" } }, "ads_engagement_rules": { "type": "array", "description": "An array of ads engagement rules for this custom audience. It is `null` unless `type` is `ADS_ENGAGEMENT`.", "nullable": true, "items": { "$ref": "#/components/schemas/AdsEngagementRuleResponse" } }, "audience_id_list_rules": { "type": "array", "description": "An array of audience id list rules for this custom audience. It is `null` unless `type` is `AUDIENCE_ID_LIST_FILE`.", "nullable": true, "items": { "$ref": "#/components/schemas/AudienceIdListRuleResponse" } }, "keyword_rules": { "type": "array", "description": "An array of keyword rules for this custom audience. It is `null` unless `type` is `KEYWORD`.", "nullable": true, "items": { "$ref": "#/components/schemas/KeywordRuleResponse" } }, "name": { "$ref": "#/components/schemas/CustomAudienceSchemas_Name" }, "type": { "$ref": "#/components/schemas/Type" }, "rules_combining_logic": { "$ref": "#/components/schemas/RulesCombiningLogic" }, "result": { "$ref": "#/components/schemas/CustomAudienceResult" }, "created_at": { "$ref": "#/components/schemas/CommonSchemas_CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/CommonSchemas_UpdatedAt" }, "configured_status": { "$ref": "#/components/schemas/CustomAudienceConfiguredStatus" } } }, "CustomAudienceArrayResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomAudienceResponse" } } } }, "CustomAudienceRequestType": { "type": "string", "enum": [ "WEB_ACTIVITY", "ADS_ENGAGEMENT", "AUDIENCE_ID_LIST_FILE", "KEYWORD" ], "description": "The type of the custom audience.\n\nNote: `KEYWORD` type is not available for US ad accounts.\n" }, "WebActivityRuleCreationRequest": { "type": "object", "required": [ "pixel_tag_id", "events", "urls", "time_period" ], "properties": { "pixel_tag_id": { "$ref": "#/components/schemas/WebActivityRuleSchemas_PixelTagId" }, "events": { "$ref": "#/components/schemas/Events" }, "urls": { "$ref": "#/components/schemas/Urls" }, "time_period": { "$ref": "#/components/schemas/TimePeriod" } } }, "AdsEngagementRuleCreationRequest": { "type": "object", "required": [ "ad_group_ids", "action", "time_period" ], "properties": { "ad_group_ids": { "$ref": "#/components/schemas/AdGroupIds" }, "action": { "$ref": "#/components/schemas/Action" }, "time_period": { "$ref": "#/components/schemas/TimePeriod" } } }, "AudienceIdListRuleCreationRequest": { "type": "object", "required": [ "audience_id_list_file_id" ], "properties": { "audience_id_list_file_id": { "type": "integer", "format": "int64", "description": "ID of the audience ID list file. The file itself can be uploaded via the endpoint [POST /ad_accounts/{ad_account_id}/audience_id_list_files](#tag/custom-audience/operation/postAudienceIdListFile).\n" } } }, "KeywordRuleCreationRequest": { "type": "object", "required": [ "window", "frequency", "keywords" ], "properties": { "window": { "$ref": "#/components/schemas/KeywordWindow" }, "frequency": { "$ref": "#/components/schemas/KeywordFrequency" }, "keywords": { "$ref": "#/components/schemas/Keywords" } } }, "CustomAudienceCreationRequest": { "type": "object", "required": [ "name", "type", "rules_combining_logic", "configured_status" ], "properties": { "name": { "$ref": "#/components/schemas/CustomAudienceSchemas_Name" }, "type": { "$ref": "#/components/schemas/CustomAudienceRequestType" }, "rules_combining_logic": { "$ref": "#/components/schemas/RulesCombiningLogic" }, "web_activity_rules": { "type": "array", "nullable": true, "description": "An array of web activity rules for this custom audience. It can only be specified when `type` is `WEB_ACTIVITY`.", "items": { "$ref": "#/components/schemas/WebActivityRuleCreationRequest" } }, "ads_engagement_rules": { "type": "array", "nullable": true, "description": "An array of ads engagement rules for this custom audience. It can only be specified when `type` is `ADS_ENGAGEMENT`.", "items": { "$ref": "#/components/schemas/AdsEngagementRuleCreationRequest" } }, "audience_id_list_rules": { "type": "array", "nullable": true, "description": "An array of id list rules for this custom audience. It can only be specified when `type` is `AUDIENCE_ID_LIST`.", "items": { "$ref": "#/components/schemas/AudienceIdListRuleCreationRequest" } }, "keyword_rules": { "type": "array", "nullable": true, "description": "An array of keyword rules for this custom audience. It can only be specified when `type` is `KEYWORD`.", "items": { "$ref": "#/components/schemas/KeywordRuleCreationRequest" } }, "configured_status": { "$ref": "#/components/schemas/CustomAudienceConfiguredStatus" } } }, "WebActivityRulePatchRequest": { "type": "object", "properties": { "custom_audience_web_activity_rule_id": { "type": "integer", "format": "int64", "description": "Unique ID of the rule." }, "pixel_tag_id": { "$ref": "#/components/schemas/WebActivityRuleSchemas_PixelTagId" }, "events": { "$ref": "#/components/schemas/Events" }, "urls": { "$ref": "#/components/schemas/Urls" }, "time_period": { "$ref": "#/components/schemas/TimePeriod" } } }, "AdsEngagementRulePatchRequest": { "type": "object", "properties": { "custom_audience_ads_engagement_rule_id": { "type": "integer", "format": "int64", "description": "Unique ID of the rule." }, "ad_group_ids": { "$ref": "#/components/schemas/AdGroupIds" }, "action": { "$ref": "#/components/schemas/Action" }, "time_period": { "$ref": "#/components/schemas/TimePeriod" } } }, "AudienceIdListRulePatchRequest": { "type": "object", "properties": { "custom_audience_audience_id_list_rule_id": { "type": "integer", "format": "int64", "description": "Unique ID of the rule." }, "audience_id_list_file_id": { "$ref": "#/components/schemas/AudienceIdListFileId" } } }, "KeywordRulePatchRequest": { "type": "object", "properties": { "custom_audience_keyword_rule_id": { "type": "integer", "format": "int64", "description": "Unique ID of the rule." }, "window": { "$ref": "#/components/schemas/KeywordWindow" }, "frequency": { "$ref": "#/components/schemas/KeywordFrequency" }, "keywords": { "$ref": "#/components/schemas/Keywords" } } }, "CustomAudiencePatchRequest": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/CustomAudienceSchemas_Name" }, "rules_combining_logic": { "$ref": "#/components/schemas/RulesCombiningLogic" }, "web_activity_rules": { "type": "array", "nullable": true, "description": "An array of web activity rules for this custom audience. It can only be specified when `type` is `WEB_ACTIVITY`.\n\nSee the CustomAudiencePatchRequest description for how to update rules.\n", "items": { "$ref": "#/components/schemas/WebActivityRulePatchRequest" } }, "ads_engagement_rules": { "type": "array", "nullable": true, "description": "An array of ads engagement rules for this custom audience. It can only be specified when `type` is `ADS_ENGAGEMENT`.\n\nSee the CustomAudiencePatchRequest description for how to update rules.\n", "items": { "$ref": "#/components/schemas/AdsEngagementRulePatchRequest" } }, "audience_id_list_rules": { "type": "array", "nullable": true, "description": "An array of id list rules for this custom audience. It can only be specified when `type` is `AUDIENCE_ID_LIST`.\nSee the CustomAudiencePatchRequest description for how to update rules.\n", "items": { "$ref": "#/components/schemas/AudienceIdListRulePatchRequest" } }, "keyword_rules": { "type": "array", "nullable": true, "description": "An array of keyword rules for this custom audience. It can only be specified when `type` is `KEYWORD`.\nSee the CustomAudiencePatchRequest description for how to update rules.\n", "items": { "$ref": "#/components/schemas/KeywordRulePatchRequest" } }, "configured_status": { "$ref": "#/components/schemas/CustomAudienceConfiguredStatus" } } }, "AdGroupArrayResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdGroupResponse" } } } }, "AudienceIdListFileRequest": { "type": "object", "required": [ "original_file_name", "file_type", "audience_id_list_file" ], "properties": { "original_file_name": { "$ref": "#/components/schemas/OriginalFileName" }, "file_type": { "$ref": "#/components/schemas/FileType" }, "audience_id_list_file": { "type": "string", "format": "binary", "description": "The file that contains the audience ID list. The file should be in CSV/TXT format.\n\nThe filesize must be ≥ 5KB and ≤ 100MB.\n\nPlease visit this [help page](https://help-ads.smartnews.com/item-3060/) for more details about the file contents.\n" } } }, "AudienceIdListFileResponse": { "type": "object", "required": [ "audience_id_list_file_id", "ad_account_id", "original_file_name", "file_type", "created_at" ], "properties": { "audience_id_list_file_id": { "$ref": "#/components/schemas/AudienceIdListFileId" }, "ad_account_id": { "type": "integer", "format": "int64", "description": "ID of the Ad Account that the file belongs to." }, "original_file_name": { "$ref": "#/components/schemas/OriginalFileName" }, "file_type": { "$ref": "#/components/schemas/FileType" }, "created_at": { "type": "string", "format": "date-time", "description": "The date-time at which the audience ID list file was created." } } }, "AdAccountNamespaceRole": { "type": "string", "enum": [ "ADS_ADVERTISER_OPERATOR", "ADS_ADVERTISER_ANALYST" ], "description": "An ad account namespace role is a role assigned to each ad account.\n- If a user has the ADS_ADVERTISER_OPERATOR role for a particular ad account, they can perform operations within that ad account as an advertiser operator, but this authority does not extend to other ad accounts even if they are in the same business.\n- If a user has the ADS_ADVERTISER_ANALYST role for a particular ad account, they have read-only access to that particular ad account, but this authority does not extend to other ad accounts even if they are in the same business.\n" }, "DeveloperAppAccessibleAdAccountResponse": { "type": "object", "required": [ "ad_account_id", "ad_account_name", "owner_business_id", "owner_business_name" ], "properties": { "ad_account_id": { "type": "integer", "format": "int64", "description": "The ID of the ad account." }, "ad_account_name": { "type": "string", "description": "The name of the ad account." }, "owner_business_id": { "type": "integer", "format": "int64", "description": "The ID of the owner business." }, "owner_business_name": { "type": "string", "description": "The name of the owner business." }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/AdAccountNamespaceRole" }, "description": "A list of roles that the ad account has." } } }, "DeveloperAppAccessibleAdAccountArrayResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperAppAccessibleAdAccountResponse" } } }, "description": "This response contains list of ad accounts that associated with the specified business.\n" }, "CommonSchemas_ResourceNotFoundErrorExtension": { "type": "object", "required": [ "type", "resource_type" ], "properties": { "type": { "type": "string", "enum": [ "NOT_FOUND", "DELETED" ] }, "resource_type": { "type": "string", "enum": [ "USER", "BUSINESS", "AD_ACCOUNT", "DEVELOPER_APP", "ENDPOINT", "USER_AD_ACCOUNT_ACCESS", "TERMS_OF_SERVICE", "BRAND", "CREDIT_CARD_PAYMENT_METHOD", "AD_ACCOUNT_PAYMENT_THRESHOLD", "MONTHLY_RECEIPT", "AD_ACCOUNT_OUTSTANDING_BALANCE", "AD_CREDIT_ACCOUNT", "CATALOG", "PRODUCT_SET", "STORE_SET" ] } } }, "CommonSchemas_ResourceNotFoundError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "CommonSchemas_ResourceNotFoundErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundError" } } }, "ReviewStatus": { "type": "string", "enum": [ "SUBMITTED", "APPROVED", "REJECTED" ] }, "TrackingType": { "type": "string", "enum": [ "ANDROID", "IOS", "ALL" ], "description": "The platform type for app tracking.\n- ANDROID: Android platform only\n- IOS: iOS platform only\n- ALL: Both Android and iOS platforms\n" }, "AppTracking": { "type": "object", "required": [ "tracking_type" ], "properties": { "tracking_type": { "$ref": "#/components/schemas/TrackingType" }, "ios_app_id": { "type": "string", "description": "iOS App ID. Required if tracking_type is IOS or ALL." }, "android_app_id": { "type": "string", "description": "Android App ID. Required if tracking_type is ANDROID or ALL." } }, "description": "Mobile app tracking configuration for the catalog." }, "CatalogAdAccount": { "type": "object", "required": [ "ad_account_id", "ad_account_name" ], "properties": { "ad_account_id": { "type": "string", "description": "Identifier of the ad account." }, "ad_account_name": { "type": "string", "description": "Name of the ad account." } }, "description": "Ad account that has access to the catalog." }, "CommonSchemas_FileType": { "type": "string", "enum": [ "CSV", "TSV" ], "description": "The file format for product feed.\n- CSV: Comma-separated values\n- TSV: Tab-separated values\n" }, "ProductSourceStatus": { "type": "string", "enum": [ "CREATED", "SUCCESS", "WARNING", "ERROR" ], "description": "Status of the product source, covering both the latest fetch (connection)\nand the health of the items it imported. On a successful fetch the status\nreflects the item import breakdown; WARNING is derived on the backend so the\nthreshold stays configurable (BMT-1190). out_of_stock items are NOT counted\nas excluded for the WARNING calculation.\n- CREATED: Product source has been created and is awaiting a successful fetch\n- SUCCESS: Last fetch completed successfully and at most 20% of input items\n were excluded (unparsable + blocked)\n- WARNING: Last fetch completed successfully but more than 20% of input items\n were excluded (unparsable + blocked). The threshold is backend-configurable.\n- ERROR: Last fetch failed with errors\n" }, "IngestionErrorReason": { "type": "string", "nullable": true, "enum": [ "AUTH_FAILED", "FILE_NOT_FOUND", "TIMEOUT", "INVALID_FORMAT", "REQUEST_ERROR", "SERVER_UNAVAILABLE", "UNKNOWN_ERROR" ], "description": "The reason for an ingestion error. Null when product source status is not ERROR.\n- AUTH_FAILED: Authentication failed (HTTP 401/403, FTP 530)\n- FILE_NOT_FOUND: File does not exist at the specified path (HTTP 404, FTP 550)\n- TIMEOUT: Server unreachable or timed out (HTTP 504, DNS failure)\n- INVALID_FORMAT: File is empty, starts with blank lines, or header cannot be parsed\n- REQUEST_ERROR: Bad URL, SSL issues, or too many redirects (HTTP 400)\n- SERVER_UNAVAILABLE: Server error or temporarily unavailable (HTTP 500/502/503/429, FTP 421-452/552, connection reset)\n- UNKNOWN_ERROR: Unclassifiable error (FTP 500-503/551, other)\n" }, "ProductSource": { "type": "object", "required": [ "product_source_id", "catalog_id", "product_source_name", "file_type", "file_url", "status", "last_fetched_at", "last_failed_item_count", "last_successful_item_count" ], "properties": { "product_source_id": { "type": "integer", "format": "int64", "description": "Unique identifier of the product source." }, "catalog_id": { "type": "integer", "format": "int64", "description": "Identifier of the catalog this product source belongs to." }, "product_source_name": { "type": "string", "description": "Name of the product source." }, "file_type": { "$ref": "#/components/schemas/CommonSchemas_FileType" }, "file_url": { "type": "string", "description": "FTP, HTTP, or HTTPS URL to the feed file." }, "username": { "type": "string", "nullable": true, "description": "Optional username for feed file access. The stored password is never\nreturned.\n" }, "status": { "$ref": "#/components/schemas/ProductSourceStatus" }, "ingestion_error_reason": { "$ref": "#/components/schemas/IngestionErrorReason" }, "ingestion_error_message": { "type": "string", "nullable": true, "description": "Localized human-readable error message resolved from ingestion_error_reason.\nLanguage is determined by the Accept-Language header. Null when status is not ERROR.\n" }, "last_fetched_at": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent ingestion attempt." }, "last_failed_item_count": { "type": "integer", "format": "int64", "minimum": 0, "description": "Number of items that failed in the latest ingestion." }, "last_successful_item_count": { "type": "integer", "format": "int64", "minimum": 0, "description": "Number of items successfully imported in the latest ingestion (deliverable: in stock and not blocked)." }, "last_out_of_stock_item_count": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true, "x-bypass-name-conversion": true, "description": "Number of items excluded in the latest ingestion because they are out of stock. Retained in the catalog but not deliverable. NOT counted toward the WARNING threshold. Null until a successful ingestion has produced a breakdown." }, "last_unparsable_item_count": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true, "x-bypass-name-conversion": true, "description": "Number of items in the latest ingestion that failed field validation (missing/invalid required fields). Null until a successful ingestion has produced a breakdown." }, "last_blocked_item_count": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true, "x-bypass-name-conversion": true, "description": "Number of items blocked by content/moderation policy in the latest ingestion. Aggregate across all blocking reasons (specific reasons are not disclosed). Null until a successful ingestion has produced a breakdown." } }, "description": "Product source configuration and operational data. Returned identically by\nthe catalog endpoints (nested under `product_sources`) and by the product\nsource endpoints, so a client always sees the same complete representation\nof a product source regardless of which API surface it consumed.\nItem import breakdown (last_out_of_stock_item_count, last_unparsable_item_count,\nlast_blocked_item_count) from the latest successful ingestion's ParseSummary:\n input = parsable + last_unparsable_item_count\n parsable = in_stock + last_out_of_stock_item_count\n in_stock = last_successful_item_count (deliverable) + last_blocked_item_count\nThe breakdown counts are null until a successful ingestion has produced them.\n" }, "CatalogResponse": { "type": "object", "required": [ "catalog_id", "business_id", "name", "review_status", "total_item_count", "ad_accounts", "product_sources", "created_at", "updated_at" ], "properties": { "catalog_id": { "type": "integer", "format": "int64", "description": "Unique identifier of the catalog." }, "business_id": { "type": "integer", "format": "int64", "description": "Identifier of the business that owns this catalog." }, "name": { "type": "string", "maxLength": 256, "description": "Human-readable display name for the catalog." }, "currency": { "type": "string", "description": "Currency for the catalog." }, "description": { "type": "string", "description": "Optional description of the catalog." }, "review_status": { "$ref": "#/components/schemas/ReviewStatus" }, "total_item_count": { "type": "integer", "format": "int32", "minimum": 0, "description": "Total number of product items currently available in the catalog across all product sources." }, "all_ad_account_access": { "type": "boolean", "description": "Whether all DA ad accounts of the business have access to this catalog." }, "pixel_tag_id": { "type": "string", "description": "Pixel tag ID associated with this catalog for web tracking." }, "app_tracking": { "$ref": "#/components/schemas/AppTracking" }, "ad_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogAdAccount" }, "description": "List of ad accounts that can access this catalog." }, "product_sources": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSource" }, "description": "List of product sources that populate the catalog with product data." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the catalog was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the catalog metadata or configuration was last updated." } }, "description": "Complete representation of a catalog including metadata and configuration." }, "CatalogArrayResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogResponse" }, "description": "Array of catalog objects returned by the list operation." } }, "description": "Response wrapper containing a list of catalogs for a given business." }, "ProductSourceRequest": { "type": "object", "required": [ "product_source_name", "file_type", "file_url" ], "properties": { "product_source_name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the product source." }, "file_type": { "$ref": "#/components/schemas/CommonSchemas_FileType" }, "file_url": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "FTP, HTTP, or HTTPS URL to the feed file." }, "username": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Optional username for feed file access." }, "password": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Optional password for feed file access." } }, "description": "Product source configuration for catalog creation." }, "CreateCatalogRequest": { "type": "object", "required": [ "name", "currency", "da_ad_account_ids", "pixel_tag_id", "product_source" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable display name for the catalog." }, "currency": { "type": "string", "enum": [ "JPY" ], "description": "Currency for the catalog. Currently only JPY is supported." }, "description": { "type": "string", "maxLength": 1024, "description": "Optional description of the catalog." }, "da_ad_account_ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "minItems": 1, "description": "List of dynamic ad account IDs that can access this catalog. At least one is required." }, "all_ad_account_access": { "type": "boolean", "default": false, "description": "If true, all DA ad accounts of the business have access to this catalog." }, "pixel_tag_id": { "type": "string", "maxLength": 64, "description": "Pixel tag ID to associate with this catalog for web tracking." }, "app_tracking": { "$ref": "#/components/schemas/AppTracking" }, "product_source": { "$ref": "#/components/schemas/ProductSourceRequest" } }, "description": "Request body for creating a new catalog." }, "CreateCatalogResponse": { "type": "object", "required": [ "catalog_id", "business_id", "name", "currency", "review_status", "total_item_count", "ad_accounts", "product_sources", "created_at", "updated_at" ], "properties": { "catalog_id": { "type": "integer", "format": "int64", "description": "Unique identifier of the newly created catalog." }, "business_id": { "type": "integer", "format": "int64", "description": "Identifier of the business that owns this catalog." }, "name": { "type": "string", "description": "Human-readable display name for the catalog." }, "currency": { "type": "string", "description": "Currency for the catalog." }, "description": { "type": "string", "description": "Optional description of the catalog." }, "review_status": { "$ref": "#/components/schemas/ReviewStatus" }, "total_item_count": { "type": "integer", "format": "int32", "minimum": 0, "description": "Total number of product items currently available in the catalog." }, "all_ad_account_access": { "type": "boolean", "description": "Whether all DA ad accounts of the business have access to this catalog." }, "pixel_tag_id": { "type": "string", "description": "Pixel tag ID associated with this catalog for web tracking." }, "app_tracking": { "$ref": "#/components/schemas/AppTracking" }, "ad_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogAdAccount" }, "description": "List of ad accounts that can access this catalog." }, "product_sources": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSource" }, "description": "List of product sources that populate the catalog with product data." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the catalog was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the catalog metadata or configuration was last updated." } }, "description": "Response for catalog creation containing the newly created catalog details." }, "CommonSchemas_ValidationErrorExtension": { "required": [ "type", "error_fields" ], "properties": { "type": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "error_fields": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string", "description": "The field name that doesn't pass the validation.\n" }, "reason": { "type": "string" } } } } } }, "CommonSchemas_ValidationError": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CommonSchemas_ValidationErrorExtension" }, { "$ref": "#/components/schemas/ErrorBase" } ] }, "CommonSchemas_ValidationErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/CommonSchemas_ValidationError" } } }, "UpdateCatalogRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable display name for the catalog." }, "da_ad_account_ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Ad account access is addition-only. This list carries only the newly\nadded dynamic ad account IDs to associate with the catalog; they are\nmerged with the existing associations. Existing associations cannot be\nremoved. Ignored when all_ad_account_access is true.\n" }, "all_ad_account_access": { "type": "boolean", "description": "Set to true to grant all DA ad accounts of the business access to this\ncatalog. Once enabled it cannot be reverted to specific ad accounts;\na request attempting to set it back to false is rejected with 400.\n" }, "pixel_tag_id": { "type": "string", "maxLength": 64, "description": "Pixel tag ID to associate with this catalog for web tracking. Can be\nchanged regardless of campaign delivery status.\n" }, "app_tracking": { "$ref": "#/components/schemas/AppTracking" } }, "description": "Request body for updating catalog metadata. Only catalog-level fields are\neditable; region, currency, and timezone are read-only. At least one field\nmust be provided.\n" }, "Status": { "type": "string", "enum": [ "CREATED", "READY", "ERROR" ], "description": "Status of the product set generation.\n- CREATED: Product set is pending processing or regeneration.\n- READY: Latest processing succeeded and the set is ready for delivery.\n- ERROR: Latest processing failed or produced zero matching items.\n" }, "RuleMatchType": { "type": "string", "enum": [ "ALL", "AT_LEAST_ONE" ], "description": "Rule matching strategy within a product set.\n- ALL: Products must satisfy every rule (logical AND).\n- AT_LEAST_ONE: Products may satisfy any single rule (logical OR).\n" }, "FilterField": { "type": "string", "enum": [ "ID", "TITLE", "PRICE", "PRODUCT_TYPE", "SHOP_ID", "RATING", "CUSTOM_LABEL_0", "CUSTOM_LABEL_1", "CUSTOM_LABEL_2", "CUSTOM_LABEL_3", "CUSTOM_LABEL_4", "CUSTOM_NUMBER_0", "CUSTOM_NUMBER_1", "CUSTOM_NUMBER_2", "CUSTOM_NUMBER_3", "CUSTOM_NUMBER_4" ], "description": "Supported fields for catalog product filtering." }, "FilterCondition": { "type": "string", "enum": [ "IS", "IS_NOT", "CONTAINS", "NOT_CONTAINS", "GREATER_THAN", "LESS_THAN", "GREATER_THAN_OR_EQUAL", "LESS_THAN_OR_EQUAL", "IS_ANY_OF_THE_FOLLOWINGS", "IS_NOT_ANY_OF_THE_FOLLOWINGS" ], "description": "Supported operators for catalog product filtering rules." }, "FilterRule": { "type": "object", "required": [ "filter_rule_id", "field", "condition", "values" ], "properties": { "filter_rule_id": { "type": "integer", "format": "int64", "description": "Unique identifier of the filter rule." }, "field": { "$ref": "#/components/schemas/FilterField" }, "condition": { "$ref": "#/components/schemas/FilterCondition" }, "values": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Array of values used by the condition. Maximum 10 values allowed for IS_ANY_OF_THE_FOLLOWINGS and IS_NOT_ANY_OF_THE_FOLLOWINGS conditions.\n" } }, "description": "Filter rule definition used to build a product set." }, "ProductSet": { "type": "object", "required": [ "product_set_id", "catalog_id", "name", "status", "rule_match_type", "item_count", "is_universal_set", "created_at", "updated_at" ], "properties": { "product_set_id": { "type": "integer", "format": "int64", "description": "Unique identifier of the product set." }, "catalog_id": { "type": "integer", "format": "int64", "description": "Identifier of the catalog this product set belongs to." }, "name": { "type": "string", "maxLength": 255, "description": "Human-readable display name for the product set." }, "status": { "$ref": "#/components/schemas/Status" }, "rule_match_type": { "$ref": "#/components/schemas/RuleMatchType" }, "filter_rules": { "type": "array", "minItems": 0, "items": { "$ref": "#/components/schemas/FilterRule" }, "description": "Collection of filter rules applied to build this product set. Empty array represents no filters applied." }, "item_count": { "type": "integer", "format": "int64", "minimum": 0, "description": "Number of catalog items that satisfied the filter rules in the latest run." }, "last_processed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the latest product set generation completion." }, "condition_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "The timestamp at which productSet’s condition (rule_match_type, filter_rules) are changed." }, "is_universal_set": { "type": "boolean", "description": "Indicates whether this product set represents the default all-items set." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the product set was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the product set configuration was last updated." } }, "description": "Product set definition along with the latest operational metadata." }, "ProductSetArrayResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSet" }, "description": "Collection of product sets owned by the catalog." } }, "description": "Response body containing multiple product sets." }, "FilterRuleRequest": { "type": "object", "required": [ "field", "condition", "values" ], "properties": { "field": { "$ref": "#/components/schemas/FilterField" }, "condition": { "$ref": "#/components/schemas/FilterCondition" }, "values": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 10, "description": "Array of values used by the condition. Maximum 10 values allowed for IS_ANY_OF_THE_FOLLOWINGS and IS_NOT_ANY_OF_THE_FOLLOWINGS conditions. Other conditions take only one value.\nFor numeric comparison conditions (GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL), values must be numeric strings. Non-numeric strings will result in an error.\n" } }, "description": "Filter rule input for creating or updating a product set." }, "PostProductSetRequest": { "type": "object", "required": [ "name", "rule_match_type" ], "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "description": "Human-readable display name for the product set." }, "rule_match_type": { "$ref": "#/components/schemas/RuleMatchType" }, "filter_rules": { "type": "array", "items": { "$ref": "#/components/schemas/FilterRuleRequest" }, "maxItems": 2, "minItems": 1, "description": "Collection of filter rules to apply. Each field can have 1 or up to 2 rules.\n" } }, "description": "Request body for creating a new product set." }, "ProductSetResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductSet" } }, "description": "Response body containing a single product set." }, "PatchProductSetRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "description": "Human-readable display name for the product set." }, "rule_match_type": { "$ref": "#/components/schemas/RuleMatchType" }, "filter_rules": { "type": "array", "items": { "$ref": "#/components/schemas/FilterRuleRequest" }, "description": "Collection of filter rules to apply. Each field can have 1 or up to 2 rules.\n" } }, "description": "Request body for updating an existing product set. At least one field must be provided." } }, "requestBodies": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRequest" } } } }, "post-requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupRequest" } } } }, "AdsByAdGroupPaginated_post-requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdRequest" } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/oauth/v1/access_tokens": { "post": { "tags": [ "oauth" ], "description": "Generate an access token for the developer application", "summary": "Generate an access token", "operationId": "generateAccessToken", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/GenerateAccessTokenRequest" } } } }, "responses": { "200": { "description": "An array of ad objects. If there is no matched item, it will return an empty array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAccessTokenResponse" } } } }, "400": { "description": "Bad request due to invalid grant_type or application_type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized due to invalid client_id or client_secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/oauth/v1/access_tokens/revoke": { "post": { "tags": [ "oauth" ], "description": "Revoke all active access tokens for the developer application", "summary": "Revoke all active access tokens for the developer application", "operationId": "revokeAccessToken", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RevokeAccessTokenRequest" } } } }, "responses": { "204": { "description": "Revoked successfully" }, "401": { "description": "Unauthorized due to invalid client_id or client_secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/insights/{layer}": { "get": { "tags": [ "insights" ], "description": "Get a list of metadata and metrics information for objects matching the query for the specified layer (Campaign/AdGroup/Ad).\n\nThe fields to include in the response must be specified by the API caller, using the `fields` parameter.\n\nNote: Only Ads Manager v2 objects can be retrieved by this API.\n\nBoth JSON (`application/json`) and CSV (`text/csv`) response formats are supported. Use the `Accept` header to specify the desired format.\n", "operationId": "getInsightsV3", "summary": "Insights", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "layer", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Layer" } }, { "name": "since", "required": true, "example": "2024-08-15T15:00:00Z", "description": "Only include metrics from this datetime (inclusive).\n\nIt must be specified in ISO 8601 format with UTC timezone (ends with `Z`).\n", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "example": "2024-08-15T15:00:00Z", "description": "Only include metrics until this datetime (inclusive).\n\nIt must be specified in ISO 8601 format with UTC timezone (ends with `Z`).\n", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "required": true, "description": "The fields to include in the response. For a detailed description of each field, see the response section under `metadata` or `metrics`.\n\nThe prefix indicates whether the field will be present in the `metadata` or `metrics` object of the response.\n\n- Starts with `metadata_`: Is a `metadata` field.\n- Starts with `metrics_`: Is a `metrics` field.\n\n* `metrics_reach` and `metrics_frequency` are not currently supported\n\n### Layer Specific Metadata fields\n\n#### Campaign\n- `metadata_objective`\n- `metadata_daily_budget_amount`\n- `metadata_start_date_time`\n- `metadata_end_date_time`\n- `metadata_optimization_event`\n- `metadata_optimization_goal`\n- `metadata_spending_limit`\n\n#### Ad Group\n- `metadata_campaign_id`\n- `metadata_campaign_name`\n\n#### Ad\n- `metadata_campaign_id`\n- `metadata_campaign_name`\n- `metadata_ad_group_id`\n- `metadata_ad_group_name`\n- `metadata_submission_status`\n- `metadata_moderation_status`\n- `metadata_thumbnails`\n- `metadata_video`\n- `metadata_ad_headline`\n- `metadata_ad_description`\n- `metadata_ad_creative_format`\n", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FieldV3" } } }, { "name": "breakdown_type", "in": "query", "description": "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. \n\n**When included in a JSON request, the following restrictions apply:**\n- cannot use the `city`, `county`, `os`, `device_type` or `hyper_location_segment` breakdowns.\n- cannot use `breakdown_type` together with `breakdown_period`.\n", "schema": { "$ref": "#/components/schemas/BreakdownType" } }, { "name": "breakdown_period", "in": "query", "description": "The time period to breakdown the report by. The breakdown can be found inside the `metrics_breakdown` field in the response. \n\nThis option combines with the `breakdown_type` param. For example `breakdown_type=age&breakdown_period=day` \nresults in one breakdown row for each day and age combination within the specified date range.\n\n**When included in a JSON request, the following restrictions apply:**\n- When using `hour` breakdown period, 1-5 object IDs must be specified using the `target_ids` parameter.\n- cannot use `breakdown_type` together with `breakdown_period`.\n", "schema": { "$ref": "#/components/schemas/BreakdownPeriod" } }, { "name": "include_deleted", "in": "query", "required": false, "description": "Boolean flag for including deleted objects in the response.", "schema": { "$ref": "#/components/schemas/IncludeDeleted" } }, { "name": "mobile_app_attribution_mode", "in": "query", "description": "The mobile app attribution mode for counting conversions of app campaigns only. The mobile app attribution mode will not be applied for web campaigns.\n\nThere are two modes: `all` and `mmp_only`.\n\n`all` mode counts all app campaigns' conversions including those attributed by a Mobile Measurement Partner and SmartNews attribution.\n`mmp_only` mode only counts app campaigns' conversions attributed by a Mobile Measurement Partner.\n", "schema": { "$ref": "#/components/schemas/MobileAppAttributionMode" } }, { "name": "click_attribution_window", "in": "query", "description": "The attribution window for counting conversions.\n\nCalculate the conversions that occur within the specified time window after a click.\n\nThe default value is 30 days.\n", "schema": { "$ref": "#/components/schemas/ClickAttributionWindow" } }, { "name": "vimp_attribution_window", "in": "query", "description": "The attribution window for counting conversions.\n\nCalculate the conversions that occur within the specified time window after a viewable impression.\n\nThe default value is 1 day.\n", "schema": { "$ref": "#/components/schemas/VimpAttributionWindow" } }, { "name": "target_ids", "in": "query", "description": "Filter by target id(s) (campaign_id for Campaign, ad_group_id for AdGroup, ad_id for Ad)\nOnly the ad object id of the specified layer (determined by the `layer` in the path) is supported.\n\n**When included in a JSON request, this field is required when either of the following parameters is specified:**\n- breakdown_type\n- breakdown_period\n\nNote: when `breakdown_period` is `hour`, the maximum size of `target_ids` is 5, not 100.\n", "schema": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "integer", "format": "int64" } }, "style": "form", "explode": false, "example": [ 1, 2, 3 ] }, { "name": "page_size", "in": "query", "required": false, "schema": { "example": 100, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "The number of objects to return per page.\n\nThe maximum page size is 100.\n" }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } }, { "name": "sort", "in": "query", "required": false, "description": "Specify an array of fields and orders to sort the response by. The format of each item is `{field}:{order}`.\n\nIf not specified, the default sort order is by `id` descending.\n\nOrder must be either `asc` or `desc`.\n\nFor available values of `field`, see the `SortableField` enum, which includes:\n\n- Sortable Metadata fields:\n - `metadata_configured_status`\n - `metadata_name`\n - `metadata_start_date_time`\n - `metadata_end_date_time`\n - `metadata_objective`\n - `metadata_daily_budget_amount`\n - `metadata_spending_limit`\n - `metadata_submission_status`\n - `metadata_moderation_status`\n - `metadata_campaign_name`\n - `metadata_ad_group_name`\n- Sortable Metrics fields:\n - All fields starting with `metrics_` are available for sorting, except for:\n - `metrics_reach`\n - `metrics_frequency`\n - `metrics_spent_before_this_month`\n - `metrics_lifetime_spent`\n", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SortParameter" }, "minItems": 1, "maxItems": 2 }, "style": "form", "explode": false, "example": [ "metrics_click:desc", "metadata_name:asc" ] }, { "name": "search", "in": "query", "schema": { "example": "My Campaign Name", "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Filter by objects in the specified layer whose name or ID contains the search query.\n" }, { "name": "parent_ids", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "minItems": 1, "maxItems": 100 }, "style": "form", "explode": false, "example": [ 1, 2, 3 ], "description": "Only available when `layer` is `ad_groups` or `ads`.\n\nA comma separated list of parent IDs to filter the result by.\n\nIn `ad_groups` layer, it represents the `campaign_id` of the campaign(s) which own the ad groups.\nIn `ads` layer, it represents the `ad_group_id` of the ad group(s) which own the ads.\n" }, { "name": "remove_csv_header", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Only applicable when the `Accept` header is `text/csv`.\n\nWhen set to `true`, the CSV header row is omitted from the response.\n\nThis is recommended when joining multiple CSV responses together, to avoid duplicate header rows.\n" } ], "responses": { "200": { "description": "Returns insights data in the requested format (JSON or CSV).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsResponseV3" } }, "text/csv": { "schema": { "type": "string", "description": "CSV formatted insights data." } } } }, "400": { "description": "Bad request, required query parameter is not found. (ie: metrics_fields)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the query is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "406": { "description": "Not Acceptable. The requested format is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotAcceptableErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/aggregated_insights/{layer}": { "get": { "tags": [ "insights" ], "description": "Get aggregated metrics information for objects matching the query for the specified layer (Campaign/AdGroup/Ad).\n\nThe fields to include in the response must be specified by the API caller, using the `fields` parameter.\n\nNote: Only Ads Manager v2 metrics can be retrieved by this API.\n", "operationId": "getAggregatedInsightsV3", "summary": "Aggregated Insights", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "layer", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Layer" } }, { "name": "since", "required": true, "example": "2024-08-15T15:00:00Z", "description": "Only include metrics from this datetime (inclusive).\n\nIt must be specified in ISO 8601 format with UTC timezone (ends with `Z`).\n", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "example": "2024-08-15T15:00:00Z", "description": "Only include metrics until this datetime (inclusive).\n\nIt must be specified in ISO 8601 format with UTC timezone (ends with `Z`).\n", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "description": "The fields to include in the response. For a detailed description of each field, see the response section under `metrics`.\n\nNote: only fields beginning with `metrics_` are supported for aggregated insights.\n", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FieldV3" } } }, { "name": "include_deleted", "in": "query", "required": false, "description": "Boolean flag for including deleted objects in the response.", "schema": { "$ref": "#/components/schemas/IncludeDeleted" } }, { "name": "mobile_app_attribution_mode", "in": "query", "description": "The mobile app attribution mode for counting conversions of app campaigns only. The mobile app attribution mode will not be applied for web campaigns.\n\nThere are two modes: `all` and `mmp_only`:\n\n- `all` mode counts all app campaigns' conversions including those attributed by a Mobile Measurement Partner and SmartNews attribution.\n- `mmp_only` mode only counts app campaigns' conversions attributed by a Mobile Measurement Partner.\n", "schema": { "$ref": "#/components/schemas/MobileAppAttributionMode" } }, { "name": "click_attribution_window", "in": "query", "description": "The attribution window for counting conversions.\n\nCalculate the conversions that occur within the specified time window after a click.\n\nThe default value is 30 days.\n", "schema": { "$ref": "#/components/schemas/ClickAttributionWindow" } }, { "name": "vimp_attribution_window", "in": "query", "description": "The attribution window for counting conversions.\n\nCalculate the conversions that occur within the specified time window after a viewable impression.\n\nThe default value is 1 day.\n", "schema": { "$ref": "#/components/schemas/VimpAttributionWindow" } }, { "name": "target_ids", "in": "query", "description": "Filter by target id(s) (campaign_id for Campaign, ad_group_id for AdGroup, ad_id for Ad)\nOnly the ad object id of the specified layer (determined by the `layer` in the path) is supported.\n", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "breakdown_period", "in": "query", "description": "The time period to breakdown the report by. The breakdown can be found inside the `metrics_breakdown` field in the response.\n", "schema": { "$ref": "#/components/schemas/BreakdownPeriod" } }, { "name": "breakdown_type", "in": "query", "description": "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.\n", "schema": { "$ref": "#/components/schemas/AggregatedInsightsBreakdownType" } } ], "responses": { "200": { "description": "An object of aggregated insights data of a specific object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AggregatedInsightsResponseV3" } } } }, "400": { "description": "Bad request, required query parameter is not found. (ie: metrics_fields)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the query is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "406": { "description": "Not Acceptable. The requested format is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotAcceptableErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/campaigns": { "get": { "tags": [ "campaign" ], "description": "Get a paginated list of campaign objects.\n\nThis endpoint returns campaigns with pagination support, including pagination metadata in the response.\n", "summary": "List Campaigns (Paginated)", "operationId": "getCampaignsPaginated", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_deleted", "in": "query", "required": false, "description": "Boolean flag for including deleted campaigns in the response.", "schema": { "$ref": "#/components/schemas/IncludeDeleted" } }, { "name": "campaign_ids", "in": "query", "required": false, "description": "Filter the response by a target list of campaign_ids", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "minItems": 1, "maxItems": 100 }, "style": "form", "explode": false, "example": [ 1, 2, 3 ] }, { "name": "page_size", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PageSize" } }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } } ], "responses": { "200": { "description": "A paginated list of campaign objects with pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignPaginatedResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the query is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "post": { "tags": [ "campaign" ], "description": "Create a campaign object. An ad account can only have up to 1,000 campaigns.\n\nWhen the number of campaigns exceed the limit, the API returns a Business Error.\n", "summary": "Create a Campaign", "operationId": "postCampaigns", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "$ref": "#/components/requestBodies/requestBody" }, "responses": { "200": { "description": "A newly created campaign object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "description": "Bad Request. The request body must be JSON format. This error response means the JSON body is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "409": { "description": "Business Error. The request body is formatted correctly but doesn't pass some ad account/system level restriction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id}": { "get": { "tags": [ "campaign" ], "description": "Get a single campaign object.", "summary": "Get a Campaign", "operationId": "getCampaignById", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "A single campaign object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "patch": { "tags": [ "campaign" ], "description": "Update an existing campaign by using the JSON Merge Patch specification, described in [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396).", "summary": "Update a Campaign", "operationId": "patchCampaignById", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/CampaignPatchRequest" } } } }, "responses": { "200": { "description": "A single campaign object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "description": "Bad Request. The request body must be JSON format. This error response means the JSON body is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "410": { "description": "The resource specified in the path is deleted and no longer available. If the user doesn't have permission to access the ad account, 404 is returned instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "delete": { "tags": [ "campaign" ], "description": "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.\n", "summary": "Delete a Campaign", "operationId": "deleteCampaignById", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Deletion completed successfully" }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "409": { "description": "Business Error. The request is formatted correctly but doesn't pass business rule validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id}/ad_groups": { "get": { "tags": [ "ad-group" ], "description": "Get a paginated list of ad group objects under a specified campaign.\n\nThis endpoint returns ad groups with pagination support, including pagination metadata in the response.\n", "summary": "List Ad Groups By Campaign (Paginated)", "operationId": "getAdGroupsByCampaignPaginated", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" }, "description": "Controls the language of response text." }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_deleted", "in": "query", "required": false, "description": "If `true`, deleted Ad Groups are included in the response.", "schema": { "$ref": "#/components/schemas/IncludeDeleted" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PageSize" } }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } } ], "responses": { "200": { "description": "A paginated list of ad group objects with pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupPaginatedResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "The user doesn't have permission to access the resource or the upper-level item doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "post": { "tags": [ "ad-group" ], "summary": "Create an Ad Group", "description": "Create an ad group object. A campaign can only have up to 1,000 ad groups.\n\nWhen the number of ad groups exceed the limit, the API returns a Business Error.\n", "operationId": "postAdGroup", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "$ref": "#/components/requestBodies/post-requestBody" }, "responses": { "200": { "description": "Ad group creation response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupResponse" } } } }, "400": { "description": "Bad Request. The request body must be JSON format. This error response means the JSON body is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the query is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "409": { "description": "Business Error. The request body is formatted correctly but doesn't pass some ad account/system level restriction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/ad_groups": { "get": { "tags": [ "ad-group" ], "description": "Get a paginated list of ad group objects by ad account.\n\nThis endpoint returns ad groups with pagination support, including pagination metadata in the response.\n", "summary": "List Ad Groups By Ad Account (Paginated)", "operationId": "getAdGroupsPaginated", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" }, "description": "Controls the language of response text." }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_deleted", "in": "query", "required": false, "description": "If `true`, deleted Ad Groups are included in the response.", "schema": { "$ref": "#/components/schemas/IncludeDeleted" } }, { "name": "ad_group_ids", "in": "query", "required": false, "description": "Filter the response by a target list of ad_group_ids", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "minItems": 1, "maxItems": 100 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PageSize" } }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } } ], "responses": { "200": { "description": "A paginated list of ad group objects with pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupPaginatedResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "The user doesn't have permission to access the resource or the upper-level item doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}": { "get": { "tags": [ "ad-group" ], "description": "Get a single Ad Group object.\n", "summary": "Get an Ad Group", "operationId": "getAdGroupById", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ad_group_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "A single adgroup object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "410": { "description": "The resource specified in the path is deleted and no longer available. If the user doesn't have permission to access the ad account, 404 is returned instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "patch": { "tags": [ "ad-group" ], "description": "Update an existing ad group by using the JSON Merge Patch specification, described in [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396).", "summary": "Update an Ad Group", "operationId": "patchAdGroupById", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ad_group_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/AdGroupPatchRequest" } } } }, "responses": { "200": { "description": "A single adgroup object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupResponse" } } } }, "400": { "description": "Bad Request. The request body must be JSON format. This error response means the JSON body is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "410": { "description": "The resource specified in the path is deleted and no longer available. If the user doesn't have permission to access the ad account, 404 is returned instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } } } }, "delete": { "tags": [ "ad-group" ], "description": "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.\n", "summary": "Delete an Ad Group", "operationId": "deleteAdGroupById", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ad_group_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Deletion completed successfully" }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "409": { "description": "Business Error. The request is formatted correctly but doesn't pass business rule validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/ads": { "get": { "tags": [ "ad" ], "description": "Get a paginated list of ad objects under a specified ad group.\n\nThis endpoint returns ads with pagination support, including pagination metadata in the response.\n", "summary": "List Ads By Ad Group (Paginated)", "operationId": "getAdsByAdGroupPaginated", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ad_group_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_deleted", "in": "query", "required": false, "description": "Boolean flag for including deleted ads in the response.", "schema": { "$ref": "#/components/schemas/IncludeDeleted" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PageSize" } }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } } ], "responses": { "200": { "description": "A paginated list of ad objects with pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdPaginatedResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "The user doesn't have permission to access the resource or the upper-level item doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "post": { "tags": [ "ad" ], "summary": "Create an Ad", "description": "Create an ad object. A single Ad Group can have up to 100 ads.\n\nWhen the number of ads exceed the limit, the API returns a Business Error.\n", "operationId": "postAd", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ad_group_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "$ref": "#/components/requestBodies/AdsByAdGroupPaginated_post-requestBody" }, "responses": { "200": { "description": "Ad creation response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the query is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "409": { "description": "Business Error. The request body is formatted correctly but doesn't pass some ad account/system level restriction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/ads": { "get": { "tags": [ "ad" ], "description": "Get a paginated list of ad objects by ad account.\n\nThis endpoint returns ads with pagination support, including pagination metadata in the response.\n", "summary": "List Ads By Ad Account (Paginated)", "operationId": "getAdsPaginated", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "include_deleted", "in": "query", "required": false, "description": "Boolean flag for including deleted ads in the response.", "schema": { "$ref": "#/components/schemas/IncludeDeleted" } }, { "name": "ad_ids", "in": "query", "required": false, "description": "Filter the response by a target list of ad_id", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "minItems": 1, "maxItems": 100 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PageSize" } }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } } ], "responses": { "200": { "description": "A paginated list of ad objects with pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdPaginatedResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "The user doesn't have permission to access the resource or the upper-level item doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/ads/{ad_id}": { "get": { "tags": [ "ad" ], "description": "Get a single ad object.", "summary": "Get an Ad", "operationId": "getAdById", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ad_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "A single ad object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "patch": { "tags": [ "ad" ], "description": "Update an existing Ad by using the JSON Merge Patch specification, described in [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396).\\\nThe 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\\\n- landing_page_url\\\n- cta_label\\\n- creative.headline\\\n- creative.description\\\n- creative.sponsored_name\\\n- creative.media_file_ids\n", "summary": "Update an Ad", "operationId": "patchAdById", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ad_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/AdPatchRequest" } } } }, "responses": { "200": { "description": "A single ad object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdResponse" } } } }, "400": { "description": "Bad Request. The request body must be JSON format. This error response means the JSON body is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "410": { "description": "The resource specified in the path is deleted and no longer available. If the user doesn't have permission to access the ad account, 404 is returned instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "delete": { "tags": [ "ad" ], "description": "Delete an existing ad.\n", "summary": "Delete an Ad", "operationId": "deleteAdById", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ad_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Deletion completed successfully" }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "409": { "description": "Business Error. The request is formatted correctly but doesn't pass business rule validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/media_files": { "get": { "tags": [ "media-file" ], "summary": "List Media Files", "operationId": "getMediaFiles", "description": "Get a paginated list of media files under the specified ad account.\nNote: Soft-deleted (inactive) media files are not returned by this endpoint.\n", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "query", "in": "query", "required": false, "description": "Search query string. Filters media files whose `file_name` contains this value (case-insensitive).\n", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, { "name": "media_type", "in": "query", "required": true, "description": "Filter by media type.", "schema": { "$ref": "#/components/schemas/MediaType" } }, { "name": "min_width", "in": "query", "required": false, "description": "Minimum width in pixels. Only media files with `width >= min_width` will be returned.\n", "schema": { "type": "integer", "minimum": 1 } }, { "name": "min_height", "in": "query", "required": false, "description": "Minimum height in pixels. Only media files with `height >= min_height` will be returned.\n", "schema": { "type": "integer", "minimum": 1 } }, { "name": "aspect_ratio_type", "in": "query", "required": false, "description": "Filter media files by the predefined aspect ratio. Applies to IMAGE media files.\nOnly assets whose primary image has the specified `aspect_ratio_type` are returned.\n", "schema": { "$ref": "#/components/schemas/AspectRatioType" } }, { "name": "sort", "in": "query", "required": false, "description": "Specify the sort order for the results. The format is `{field}:{order}` (e.g. `created_at:desc`).\nSupported fields: `created_at`, `updated_at`. Defaults to `created_at:desc`.\n", "schema": { "type": "array", "items": { "type": "string", "pattern": "^(created_at|updated_at):(asc|desc)$" }, "minItems": 1, "maxItems": 1, "example": [ "created_at:desc" ], "default": [ "created_at:desc" ] } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "page", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Page" } } ], "responses": { "200": { "description": "A paginated list of media file objects with pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaFilePaginatedResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "The user doesn't have permission to access the resource or the ad account doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "post": { "tags": [ "media-file" ], "summary": "Create a Media File", "operationId": "postMedia", "description": "Create a Media File which can be used in Ad Creatives.", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MediaFileRequest" } } } }, "responses": { "200": { "description": "`images` and `videos` fields are required in the response by following the rules:\n| Media Type | Required Fields |\n|------------|-----------------------|\n| IMAGE | `images` |\n| VIDEO | `images`, `videos` |\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaFileResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "409": { "description": "Business Error. The request body is formatted correctly but not correct in the business definitions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "422": { "description": "Validation Error. The request body doesn't pass the format check or some fields contain invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } }, "504": { "description": "Upload MediaFile timeout error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayTimeoutErrorResponse" } } } } } } }, "/api/ma/v3/locations": { "get": { "tags": [ "locations" ], "summary": "List Locations", "operationId": "getLocations", "parameters": [ { "name": "region", "in": "query", "required": false, "description": "The region to obtain locations for.\n\nThere are currently two regions: `JP` and `US`.\n- `JP`: contains all the prefectures and their cities in Japan.\n- `US`: contains all the states and their counties in the US.\n\nIf a value is not specified, the default is `JP`.\n", "schema": { "$ref": "#/components/schemas/Region" } } ], "description": "Returns an array of locations for the specified region (prefectures for `JP`, states for `US`).\n\nEach location contains an array of `children` objects, representing cities inside that prefecture for `JP`, and counties inside that state for `US`. \n\nDisplay names are provided in Japanese and English via the `ja` and `en` fields.\n", "responses": { "200": { "description": "A successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Locations" } }, "examples": { "japan": { "value": [ { "location_id": 70149, "ja": "北海道", "en": "Hokkaido", "children": [ { "location_id": 70196, "ja": "札幌市", "en": "Sapporo" }, { "location_id": 70197, "ja": "函館市", "en": "Hakodate" } ] } ], "summary": "A sample of the JP Locations." }, "us": { "value": [ { "location_id": 2, "en": "Washington", "ja": "Washington", "children": [ { "location_id": 3, "en": "Pierce County", "ja": "Pierce County" }, { "location_id": 76, "en": "Skagit County", "ja": "Skagit County" } ] } ], "summary": "A sample of the US Locations. Note that the \"ja\" names are not translated." } } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/article_categories": { "get": { "tags": [ "article category" ], "summary": "List article categories", "operationId": "getAllArticleCategories", "description": "Returns article category master data for contextual targeting.\n\nThe response is a nested category tree to simplify frontend implementation.\n", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleCategoryMasterResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/article_keywords/search": { "post": { "tags": [ "smart view article keyword" ], "summary": "Batch search SmartView article keyword suggestions", "description": "Accepts a list of keywords and returns preset SmartView article keyword\nsuggestions for each, suitable for autocomplete experiences.\n\n- Input is language-agnostic: both EN and JA queries are supported.\n- Results may contain both EN and JA keywords (exact and similar matches).\n- Results for each keyword are sorted by relevance in descending order.\n- When no matches are found for a keyword, an empty array is returned for that key.\n", "operationId": "postSearchSmartViewArticleKeywords", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartViewArticleKeywordSearchRequest" } } } }, "responses": { "200": { "description": "A map of each input keyword to its matching suggestions sorted by relevance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartViewArticleKeywordSearchResponse" } } } }, "400": { "description": "The request body is invalid (e.g. empty query list, more than 1000 keywords, a keyword longer than 80 characters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/channel_alias_labels": { "get": { "tags": [ "channel alias label" ], "summary": "List channel alias labels", "operationId": "getAllChannelAliasLabels", "description": "Returns channel alias label master data.\n", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelAliasLabelMasterResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/iab_interest_categories": { "get": { "tags": [ "interests" ], "summary": "List Interests", "operationId": "getAllIABInterestCategories", "description": "Returns an array of IAB interest categories which can be used for AdGroup level interest targeting.\n", "responses": { "200": { "description": "A successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IABInterestCategory" } } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "429": { "description": "Too many requests were made within a short period. Wait a while and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/pixels": { "get": { "tags": [ "pixel" ], "summary": "Get list of pixels which are linked to the ad_account_id.", "description": "- Get list of pixels which are linked to the ad_account_id.\n", "operationId": "getPixelList", "parameters": [ { "name": "ad_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AdAccountId" } } ], "responses": { "200": { "description": "Returns the list of pixels", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixelWithValidationArrayResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/pixels/{pixel_tag_id}": { "get": { "tags": [ "pixel" ], "summary": "Get the details of the pixel_tag_id linked to the ad_account_id.", "description": "- It will return the details of the pixel_tag_id\n- The pixel_tag_id should be linked to ad_account_id, Otherwise returns 404\n", "operationId": "getPixelDetail", "parameters": [ { "name": "ad_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AdAccountId" } }, { "name": "pixel_tag_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PixelTagId" } } ], "responses": { "200": { "description": "Returns the details of the pixel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixelWithValidationResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found or the user doesn't have permission to access the resource.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/custom_audiences": { "get": { "tags": [ "custom-audience" ], "summary": "List custom audiences", "description": "Get a list of Custom Audiences for an ad account ID.", "operationId": "listCustomAudience", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AdAccountId" } } ], "responses": { "200": { "description": "A list of custom audiences for the specified ad account ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomAudienceArrayResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the query is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "post": { "tags": [ "custom-audience" ], "summary": "Create a Custom Audience", "description": "Create a Custom Audience", "operationId": "createCustomAudience", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AdAccountId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomAudienceCreationRequest" } } } }, "responses": { "200": { "description": "Returns the created custom audience", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomAudienceResponse" } } } }, "400": { "description": "Bad Request. The request body must be JSON format. This error response means the JSON body is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "409": { "description": "Business Error. The request body is formatted correctly but doesn't pass some ad account/system level restriction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/custom_audiences/{custom_audience_id}": { "get": { "tags": [ "custom-audience" ], "summary": "Get a Custom Audience", "description": "Get a single custom audience by ID.", "operationId": "getCustomAudience", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AdAccountId" } }, { "name": "custom_audience_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "Unique ID of the custom audience" } } ], "responses": { "200": { "description": "The custom audience that matches the ID specified in the path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomAudienceResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the query is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "patch": { "tags": [ "custom-audience" ], "summary": "Update a Custom Audience", "description": "Update a custom audience.\n", "operationId": "updateCustomAudience", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AdAccountId" } }, { "name": "custom_audience_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "Unique id of the custom audience" } } ], "requestBody": { "required": true, "description": "`_rules` fields are array fields representing different types of rules that are updated using the following logic:\n - Create a rule: Include a rule object with all required fields specified, and no rule ID.\n - Update a rule: Include a rule object with the rule ID of the existing rule, and any fields which should be updated.\n - Keep a rule: Include a rule object with the rule ID of the existing rule, and no other fields specified.\n - Delete a rule: Omit the object with the rule ID that you want to delete.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomAudiencePatchRequest" } } } }, "responses": { "200": { "description": "Returns the created custom audience", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomAudienceResponse" } } } }, "400": { "description": "Bad Request. The request body must be JSON format. This error response means the JSON body is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "409": { "description": "Business Error. The request body is formatted correctly but doesn't pass some ad account/system level restriction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "delete": { "tags": [ "custom-audience" ], "summary": "Delete a Custom Audience", "description": "Delete a single custom audience by ID. NOTE: the custom audience must not be currently used in any Ad Group targeting.\n\nRemove the custom audience from all Ad Group targeting before attempting to delete it.\n\nUse the `GET ad_accounts/{ad_account_id}/custom_audiences/{custom_audience_id}/ad_groups` endpoint \nto determine which ad groups are currently using the custom audience.\n", "operationId": "deleteCustomAudience", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AdAccountId" } }, { "name": "custom_audience_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "description": "Unique id of the custom audience" } } ], "responses": { "204": { "description": "The custom audience was deleted successfully. There is no response body." }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the query is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "409": { "description": "Business Error. The request body is formatted correctly but doesn't pass some ad account/system level restriction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/custom_audiences/{custom_audience_id}/ad_groups": { "get": { "tags": [ "ad-group", "custom-audience" ], "summary": "Get ad groups by custom audience.", "description": "Get an array of adgroups that use the specified custom audience for targeting.", "operationId": "getAdGroupsByCustomAudience", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "$ref": "#/components/schemas/AcceptLanguage" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "custom_audience_id", "in": "path", "required": true, "description": "The ID of the custom audience to retrieve ad groups for.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "An array of ad group objects that use the specified custom audience for targeting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupArrayResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the query is not found or the user doesn't have permission to access the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/ma/v3/ad_accounts/{ad_account_id}/audience_id_list_files": { "post": { "tags": [ "custom-audience" ], "summary": "Create a audience ID list file.", "operationId": "postAudienceIdListFile", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "type": "string" } }, { "name": "ad_account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudienceIdListFileRequest" } } } }, "responses": { "200": { "description": "Return the created audience id list file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceIdListFileResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "409": { "description": "Business Error. The request body is formatted correctly but not correct in the business definitions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessErrorResponse" } } } }, "422": { "description": "Validation Error. The request body doesn't pass the format check or some fields contain invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } }, "504": { "description": "Upload MediaFile timeout error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayTimeoutErrorResponse" } } } } } } }, "/api/bm/v1/developer_apps/me/ad_accounts": { "get": { "tags": [ "developer-app" ], "description": "Get a list of ad accounts associated with a specific developer app.", "summary": "Get a list of ad accounts associated with a specific developer app", "operationId": "getAdAccountsByDeveloperAppId", "responses": { "200": { "description": "An array of ad_account objects associated with the specified developer app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperAppAccessibleAdAccountArrayResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the resource specified in the path is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/bm-external/v1/businesses/{business_id}/catalogs": { "get": { "tags": [ "catalog" ], "description": "Retrieve all catalogs associated with the specified business.\n", "operationId": "listBusinessCatalogs", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Identifier of the business whose catalogs will be listed.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Catalogs associated with the specified business.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogArrayResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "x-examples": { "expiredToken": { "summary": "Access token has expired.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token has expired.", "retriable": false } } }, "invalidToken": { "summary": "Access token is invalid.", "value": { "error": { "type": "UNAUTHORIZED", "message": "Token is invalid.", "retriable": false } } } } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Access is denied due to insufficient permissions.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Access denied.", "retriable": false } } } } } } }, "404": { "description": "When the business resource specified in the path is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "post": { "tags": [ "catalog" ], "description": "Create a new catalog for the specified business.\nOnly business admins can create catalogs.\nThe catalog will be created with the provided configuration and linked to the specified ad accounts.\n", "operationId": "createBusinessCatalog", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Identifier of the business that will own the catalog.", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCatalogRequest" } } } }, "responses": { "201": { "description": "Catalog created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCatalogResponse" } } } }, "400": { "description": "Bad Request. The request body or query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "terms_of_service_not_accepted": { "summary": "User has not accepted the terms of service.", "value": { "error": { "type": "TERMS_OF_SERVICE_NOT_ACCEPTED", "message": "The owner of the assets must accept the Ads terms of service.", "terms_of_service_path": "/terms/agreement", "retriable": false } } }, "access_denied": { "summary": "Only business admins can create catalogs.", "value": { "error": { "type": "ACCESS_DENIED", "message": "Only business admins can create catalogs.", "retriable": false } } } } } } }, "404": { "description": "When the business resource specified in the path is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ValidationErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/bm-external/v1/businesses/{business_id}/catalogs/{catalog_id}": { "get": { "tags": [ "catalog" ], "description": "Retrieve metadata of a specific catalog under the specified business.\n", "operationId": "getBusinessCatalog", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Identifier of the business that owns the catalog.", "schema": { "type": "integer", "format": "int64" } }, { "name": "catalog_id", "in": "path", "required": true, "description": "Identifier of the catalog to retrieve.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Catalog details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "access_denied": { "summary": "Missing `ViewCatalog` permission.", "value": { "error": { "type": "ACCESS_DENIED", "message": "ViewCatalog permission is required.", "retriable": false } } } } } } }, "404": { "description": "When the business or catalog resource specified in the path is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "patch": { "tags": [ "catalog" ], "description": "Update metadata of an existing catalog under the specified business.\nOnly the catalog-level fields are editable here; product source fields are\nmanaged via the product source endpoint and no connection validation is\ntriggered by this operation.\n", "operationId": "updateBusinessCatalog", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Identifier of the business that owns the catalog.", "schema": { "type": "integer", "format": "int64" } }, { "name": "catalog_id", "in": "path", "required": true, "description": "Identifier of the catalog to update.", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCatalogRequest" } } } }, "responses": { "200": { "description": "Catalog updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogResponse" } } } }, "400": { "description": "Bad Request. The request body or query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "404": { "description": "When the business or catalog resource specified in the path is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ValidationErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/bm-external/v1/businesses/{business_id}/catalogs/{catalog_id}/product_sets": { "get": { "tags": [ "catalog" ], "description": "Retrieve all product sets configured under the specified catalog.\n", "operationId": "listCatalogProductSets", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Identifier of the business that owns the catalog.", "schema": { "type": "integer", "format": "int64" } }, { "name": "catalog_id", "in": "path", "required": true, "description": "Identifier of the catalog whose product sets will be listed.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Product sets associated with the specified catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSetArrayResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "404": { "description": "When the business or catalog resource specified in the path is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "post": { "tags": [ "catalog" ], "description": "Create a new product set under the specified catalog.\nUsers can configure name, rule_match_type, and filter_rules.\nEach filter rule must specify a valid field, condition, and values combination.\n", "operationId": "createCatalogProductSet", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Identifier of the business that owns the catalog.", "schema": { "type": "integer", "format": "int64" } }, { "name": "catalog_id", "in": "path", "required": true, "description": "Identifier of the catalog under which to create the product set.", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostProductSetRequest" } } } }, "responses": { "201": { "description": "Product set created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSetResponse" } } } }, "400": { "description": "Bad Request. The request body or query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "404": { "description": "When the business or catalog resource specified in the path is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ValidationErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } }, "/api/bm-external/v1/businesses/{business_id}/catalogs/{catalog_id}/product_sets/{product_set_id}": { "get": { "tags": [ "catalog" ], "description": "Retrieve details of a specific product set under the specified catalog.\n", "operationId": "getCatalogProductSet", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Identifier of the business that owns the catalog.", "schema": { "type": "integer", "format": "int64" } }, { "name": "catalog_id", "in": "path", "required": true, "description": "Identifier of the catalog that contains the product set.", "schema": { "type": "integer", "format": "int64" } }, { "name": "product_set_id", "in": "path", "required": true, "description": "Identifier of the product set to retrieve.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Product set details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSetResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "404": { "description": "When the business, catalog, or product set resource specified in the path is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } }, "patch": { "tags": [ "catalog" ], "description": "Update an existing product set under the specified catalog.\nUsers can update name, rule_match_type, and filter_rules.\nEach filter rule must specify a valid field, condition, and values combination.\nAt least one field must be provided in the request body.\n", "operationId": "updateCatalogProductSet", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Identifier of the business that owns the catalog.", "schema": { "type": "integer", "format": "int64" } }, { "name": "catalog_id", "in": "path", "required": true, "description": "Identifier of the catalog that contains the product set.", "schema": { "type": "integer", "format": "int64" } }, { "name": "product_set_id", "in": "path", "required": true, "description": "Identifier of the product set to update.", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchProductSetRequest" } } } }, "responses": { "200": { "description": "Product set updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSetResponse" } } } }, "400": { "description": "Bad Request. The request body or query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized. The access token is either expired or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" } } } }, "403": { "description": "Forbidden. Access to the requested resource is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "404": { "description": "When the business, catalog, or product set resource specified in the path is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ResourceNotFoundErrorResponse" } } } }, "422": { "description": "Validation Error. This error is returned when the request body contains unknown fields, invalid fields or invalid values. The `error_fields` shows the fields that don't pass the validations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonSchemas_ValidationErrorResponse" } } } }, "500": { "description": "Unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnexpectedErrorResponse" } } } }, "503": { "description": "The service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } } } } } }