> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Update campaign > Update an existing campaign. All fields are optional. The `brief` and `name` fields are screened by the content-moderation engine and rejected with 422 `CONTENT_MODERATION_BLOCKED` on policy violation. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml put /campaigns/{campaignId} openapi: 3.0.0 info: title: Scope3 Buyer API version: 2.0.0 description: |- REST API for advertisers to manage advertisers, campaigns, and reporting. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/buyer` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.interchange.io/api/v2/buyer description: Production server security: [] tags: - name: Signup description: Request reviewed access to Interchange - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Advertisers description: Manage advertisers - name: Product Discovery description: Discover and select products - name: Campaigns description: Manage advertising campaigns - name: Creatives description: Build, manage, and sync campaign creatives via AdCP Creative Protocol - name: Reporting description: Access performance metrics - name: Event Sources description: >- Manage event source configurations and log conversion/marketing events for attribution - name: Property Lists description: Validate property lists against AAO registry - name: Sales Agents description: View and connect sales agents - name: Measurement description: Measurement sources, records, context, and freshness - name: Syndication description: Syndicate resources to ADCP agents - name: Tasks description: Track async operation status - name: Buyer Billing description: >- Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer. - name: MCP description: Model Context Protocol endpoints for AI agents paths: /campaigns/{campaignId}: put: tags: - Campaigns summary: Update campaign description: >- Update an existing campaign. All fields are optional. The `brief` and `name` fields are screened by the content-moderation engine and rejected with 422 `CONTENT_MODERATION_BLOCKED` on policy violation. operationId: updateCampaign parameters: - in: path name: id schema: type: string minLength: 1 description: Unique identifier for the campaign example: cmp_987654321 required: true description: Unique identifier for the campaign requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateCampaignOpenApiBody' responses: '200': description: Update campaign content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- Content rejected by moderation policy. See `POST /campaigns` for full criteria. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: UpdateCampaignOpenApiBody: anyOf: - $ref: '#/components/schemas/UpdateLegacyCampaignBody' - $ref: '#/components/schemas/UpdateDiscoveryCampaignBody' - $ref: '#/components/schemas/UpdatePerformanceCampaignBody' - $ref: '#/components/schemas/RefreshDirectedCampaignBody' CampaignResponse: type: object properties: campaign: $ref: '#/components/schemas/Campaign' warnings: description: >- Non-blocking advisories about the campaign. On create, includes a soft credit-limit warning when the budget already exceeds the org’s available Scope3 credit (the campaign is still created; the hard 402 gate fires at execute). type: array items: type: string required: - campaign additionalProperties: false description: Response containing a single campaign ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response UpdateLegacyCampaignBody: type: object properties: name: description: Updated campaign name type: string minLength: 1 maxLength: 255 flightDates: description: Updated campaign flight dates type: object properties: startDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Campaign start date (ISO 8601) example: '2025-01-15T00:00:00Z' endDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Campaign end date (ISO 8601) example: '2025-03-31T23:59:59Z' required: - startDate - endDate budget: description: Updated budget configuration (partial updates allowed) type: object properties: total: type: number minimum: 0 exclusiveMinimum: true currency: default: USD type: string minLength: 3 maxLength: 3 dailyCap: type: number minimum: 0 exclusiveMinimum: true pacing: type: string enum: - EVEN - ASAP - FRONTLOADED brief: description: Updated campaign brief type: string maxLength: 5000 constraints: description: Updated targeting constraints type: object properties: geo_countries: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_countries_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_regions: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback. geo_regions_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Exclude exact canonical ISO 3166-2 subdivisions. Support is independent from geo_regions inclusion support. Unknown identifiers and values also present in geo_regions are invalid. At create or update, sellers MUST reject unsupported identifiers and partial application; during get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. geo_metros: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: A targeted metro area. description: >- Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities. geo_metros_exclude: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes to exclude within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: >- Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Restrict delivery to specific postal areas. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas_exclude: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Exclude specific postal areas from delivery. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. language: minItems: 1 type: array items: type: string minLength: 2 maxLength: 63 pattern: >- ^(?:[a-z]{2,8}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*(?:-[0-9a-wy-z](?:-[a-z0-9]{2,8})+)*(?:-x(?:-[a-z0-9]{1,8})+)?|x(?:-[a-z0-9]{1,8})+)$ description: >- A well-formed BCP 47 language tag used by AdCP only as language identity. Script and region may refine that identity; other valid BCP 47 subtags remain part of tag matching but do not make this a general locale-settings object. It does not determine currency, time zone, number/date formatting, market, or legal jurisdiction. The AdCP canonical wire profile requires lower-case language and variants, title-case script, and upper-case region (for example `en-US`, `zh-Hant-TW`, or `x-private`). RFC 5646 comparisons are case-insensitive and its case regularization is optional; AdCP intentionally requires this stricter single wire spelling and receivers MUST reject differently cased tags rather than silently normalizing them. The schema pattern enforces the AdCP casing profile and extension structure for commonly used tags; conforming receivers additionally validate the complete RFC 5646 grammar and registry rules. Every new AdCP field carrying BCP 47 language identity or a concrete language range MUST reference this schema instead of declaring independent string constraints. description: >- Restrict to users with specific language preferences using canonical BCP 47 language ranges. Each buyer range is evaluated against a user's language-preference tag with RFC 4647 section 3.3.1 Basic Filtering: 'fr' matches 'fr', 'fr-CA', and 'fr-FR', while 'fr-CA' matches 'fr-CA' and more-specific descendants but not 'fr' or 'fr-FR'. Values use OR logic. device_platform: minItems: 1 type: array items: type: string enum: - ios - android - windows - macos - linux - chromeos - tvos - tizen - webos - fire_os - roku_os - unknown description: >- Operating system platforms for device targeting. Browser values from Sec-CH-UA-Platform standard, extended for CTV. description: >- Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV. device_type: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns). device_type_exclude: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns). channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: >- Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write. deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: {} channelGroups: description: >- Canonical buyer-declared inventory execution and reporting boundaries. Pass null to clear before any selection or media buy references a group. nullable: true minItems: 1 maxItems: 25 type: array items: type: object properties: channelGroupId: type: string minLength: 1 maxLength: 128 name: type: string minLength: 1 maxLength: 120 source: oneOf: - type: object properties: kind: type: string enum: - preset presetId: type: string enum: - display - olv - mobile_web_display - mobile_web_olv - ctv description: >- Versioned channel group preset to expand into AdCP inventory dimensions. presetVersion: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - kind - presetId - presetVersion additionalProperties: false - type: object properties: kind: type: string enum: - custom required: - kind additionalProperties: false type: object inventory: type: object properties: channels: description: Buyer-declared AdCP media channels. Values are OR. minItems: 1 type: array items: type: string enum: - display - olv - social - search - ctv - linear_tv - radio - streaming_audio - podcast - dooh - ooh - print - cinema - email - gaming - retail_media - influencer - affiliate - product_placement - sponsored_intelligence propertyTypes: description: Buyer-declared AdCP property types. Values are OR. minItems: 1 type: array items: type: string enum: - website - mobile_app - ctv_app - desktop_app - dooh - podcast - radio - linear_tv - streaming_audio - ai_assistant deviceTypes: description: Buyer-declared AdCP device types. Values are OR. minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown formatKinds: description: >- Buyer-declared AdCP canonical creative format kinds. Values are OR. minItems: 1 type: array items: type: string enum: - image - html5 - display_tag - image_carousel - video_hosted - video_vast - audio_hosted - audio_vast - audio_daast - sponsored_placement - native_in_feed - responsive_creative - agent_placement - seller_rendered_stateful_display - coordinated_placements - custom additionalProperties: false required: - channelGroupId - name - source - inventory additionalProperties: false storefrontIds: description: >- Updated storefront filter for the campaign. Pass an empty array to clear (no storefront limit). Subsequent product discovery runs against this campaign auto-apply the new filter. example: - 42 - 57 maxItems: 50 type: array items: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 discoveryId: description: Attach a discovery session to the campaign type: string minLength: 1 audienceConfig: description: >- Audience targeting and suppression configuration. Use deleteMissing: true to replace the full audience set. type: object properties: targetAudienceIds: description: >- Audience IDs to target. Can be empty when deleteMissing is true to remove all targeted audiences. example: - aud_123 - aud_456 maxItems: 100 type: array items: type: string minLength: 1 suppressAudienceIds: description: >- Audience IDs to suppress. Can be empty when deleteMissing is true to remove all suppressed audiences. example: - aud_789 maxItems: 100 type: array items: type: string minLength: 1 deleteMissing: description: >- When true, audiences NOT in the respective lists are removed. When false or omitted, lists are additive. type: boolean performanceConfig: description: >- Updated optimization goals (hints only). Pass null to clear. Goals are allowed on any campaign — they do not gate composition. Set `autonomy.inventorySelection: "automatic"` to delegate composition to the platform optimizer (AI-8988). nullable: true allOf: - $ref: '#/components/schemas/PerformanceConfig' optimizationApplyMode: description: >- Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual approval. If omitted, inherits the advertiser-level setting. allOf: - $ref: '#/components/schemas/OptimizationApplyMode' catalogId: description: Catalog ID to attach (or null to detach the current catalog) nullable: true type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 mediaBuys: description: >- Media buy actions. Each entry targets a specific media buy by ID. Use action: "update" (default) to modify, "cancel" to cancel, or "delete" to archive. type: array items: type: object properties: action: description: >- Action to perform. "update" (default) modifies the media buy, "cancel" cancels it, "delete" archives it. type: string enum: - update - cancel - delete mediaBuyId: type: string minLength: 1 description: ID of the media buy to act on reason: description: 'Cancellation reason (only for action: "cancel")' type: string maxLength: 1000 packageIds: description: >- Cancel specific packages instead of the whole media buy (only for action: "cancel") type: array items: type: string minLength: 1 name: description: Updated media buy name type: string minLength: 1 maxLength: 255 packages: description: Per-package updates (for media buys with deployed packages) type: array items: type: object properties: packageId: type: string minLength: 1 description: Package ID to update budget: description: Updated budget amount type: number minimum: 0 exclusiveMinimum: true pacing: description: Updated pacing strategy type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. nullable: true type: number startTime: description: >- Updated flight start date/time for this package (ISO 8601). Must fall within the media buy's date range. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ endTime: description: >- Updated flight end date/time for this package (ISO 8601). Must fall within the media buy's date range. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ targetingOverlay: type: object properties: audience_include: anyOf: - minItems: 1 type: array items: type: string description: >- Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities. - type: string nullable: true enum: - null audience_exclude: anyOf: - minItems: 1 type: array items: type: string description: >- Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities. - type: string nullable: true enum: - null geo_countries: anyOf: - minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). - type: string nullable: true enum: - null geo_regions: anyOf: - minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback. - type: string nullable: true enum: - null additionalProperties: false description: >- Per-dimension targeting patch. Omit a field to preserve its current value, pass null to clear it, or pass a value to replace it. Not every adapter supports every field at update time; an unsupported field is rejected with UNSUPPORTED_TARGETING_DIMENSION. required: - packageId additionalProperties: false pacingPeriods: description: >- Per-media-buy pacing schedule. When set, replaces the campaign-level pacingPeriods for this specific buy. Use to heavy-up or shape spend on one media buy without affecting others. Pass null to clear an existing per-buy schedule. Bootstrapping a schedule onto an unpaced media buy is only allowed in DRAFT or PENDING_APPROVAL status. See the Pacing Periods guide for the full state matrix and sales-agent capability requirements. nullable: true allOf: - $ref: '#/components/schemas/PacingPeriods' products: description: >- Product updates — additive (existing products not listed are preserved). Use remove: true to delete a product. type: array items: type: object properties: productId: type: string minLength: 1 description: Product ID storefrontId: description: Exact Storefront identity returned by discovery type: string pattern: ^[1-9]\d*$ inventorySourceId: description: >- Exact inventory-source identity returned by discovery; null identifies Storefront-owned inventory nullable: true type: string pattern: ^[1-9]\d*$ pricingOptionId: type: string buyerRef: description: >- Line-item handle from the media buy read. Required to target one line item when the same product appears more than once on the buy; omit when the product is unique. type: string minLength: 1 maxLength: 255 budget: type: number minimum: 0 exclusiveMinimum: true pacing: type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. nullable: true type: number remove: description: Set to true to remove this product from the media buy type: boolean pageId: description: >- Platform-specific page identity for ad placements. Required for Meta products when the connected ad account has more than one authorized Facebook Page — pass one of the page IDs listed in the error message. Omit when the account has exactly one authorized page. example: '1147910135081908' type: string minLength: 1 pixelId: description: >- Meta Pixel / Dataset ID for conversion tracking. Required for Meta Sales (OUTCOME_SALES) products — pass the pixel ID listed in the error message. There is no auto-select: every Meta Sales buy must explicitly specify a pixel. example: '123456789012345' type: string minLength: 1 instagramActorId: description: >- Meta Instagram account ID for Instagram Direct destinations (Instagram Direct Conversations, Instagram-based Lead Generation). Required when the connected ad account has more than one authorized Instagram account — unlike pageId, the error does not enumerate candidate IDs; obtain the Instagram Business Account ID from Meta Business Settings. Omit when the account has exactly one authorized Instagram account (the server selects it automatically). example: '17841400000000000' type: string minLength: 1 welcomeMessageFlowId: description: >- Meta welcome message flow ID for lead-to-message destinations (Messenger, Instagram Direct, and WhatsApp Lead Generation). Required for these products — pass one of the welcome-message-flow candidates returned by account resource readiness in the discovery/get_products response. example: '1122334455667788' type: string minLength: 1 required: - productId additionalProperties: false start_time: description: >- "asap" or ISO 8601 date-time. Start of this media buy. Cannot be earlier than the campaign's flightDates.startDate. Media buy dates MAY correspond to a pacingPeriods[].start when the media buy represents a specific period, but pacing periods do not govern media buy dates — a media buy can have any start within the campaign flight, with or without pacing periods. type: string end_time: description: >- ISO 8601 date-time. End of this media buy. Must fall within the campaign's flight dates. Media buy dates MAY correspond to a pacingPeriods[].end when the media buy represents a specific period, but pacing periods do not govern media buy dates — a media buy can have any end within the campaign flight, with or without pacing periods. type: string updated_reason: description: >- Reason for the update (stored with the new version for SCD Type 2) type: string suggestion_id: description: Suggestion ID from RL optimizer type: string optimization_goals: description: >- Optimization goals applied to every package at execution time. Each goal is either `{ kind: "event", event_sources: [{ event_source_id, event_type }], target? }` or `{ kind: "metric", metric, target? }`. Event target kinds: `cost_per` (CPA), `per_ad_spend` (ROAS), `maximize_value`. Metric target kinds: `cost_per`, `threshold_rate`. ALWAYS ask the buyer what they want to optimize for before updating — do not change goals silently. Pass an empty array to clear all goals. type: array items: anyOf: - type: object properties: kind: type: string enum: - metric metric: anyOf: - type: string enum: - clicks - type: string enum: - views - type: string enum: - completed_views - type: string enum: - viewed_seconds - type: string enum: - attention_seconds - type: string enum: - attention_score - type: string enum: - engagements - type: string enum: - follows - type: string enum: - saves - type: string enum: - profile_visits - type: string enum: - reach reach_unit: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom target_frequency: anyOf: - type: object properties: {} additionalProperties: {} - type: object properties: {} additionalProperties: {} view_duration_seconds: type: number target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - metric additionalProperties: {} - type: object properties: kind: type: string enum: - event event_sources: type: array items: type: object properties: event_source_id: type: string event_type: anyOf: - type: string enum: - page_view - type: string enum: - view_content - type: string enum: - select_content - type: string enum: - select_item - type: string enum: - search - type: string enum: - share - type: string enum: - add_to_cart - type: string enum: - remove_from_cart - type: string enum: - viewed_cart - type: string enum: - add_to_wishlist - type: string enum: - initiate_checkout - type: string enum: - add_payment_info - type: string enum: - purchase - type: string enum: - refund - type: string enum: - lead - type: string enum: - qualify_lead - type: string enum: - close_convert_lead - type: string enum: - disqualify_lead - type: string enum: - complete_registration - type: string enum: - subscribe - type: string enum: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - type: string enum: - start_trial - type: string enum: - app_install - type: string enum: - app_launch - type: string enum: - contact - type: string enum: - schedule - type: string enum: - donate - type: string enum: - submit_application - type: string enum: - custom custom_event_name: type: string value_field: type: string value_factor: type: number required: - event_source_id - event_type additionalProperties: {} target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: {} attribution_window: type: object properties: post_click: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} post_view: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string pattern: ^[a-z0-9_]+$ countries: type: array items: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media synthetic_depiction: type: boolean ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string created_time: type: string c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: integer minimum: 1 maximum: 9007199254740991 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - vendor - metric_id additionalProperties: {} creative_ids: description: >- Explicit creative IDs to attach to this media buy. When provided, overrides the campaign-level auto-sync (which otherwise pushes the campaign's manifest-linked creatives, filtered to formats accepted by this buy's products). Pass an empty array to clear all creatives. Omit (or leave undefined) to use auto-sync. Each ID must already be linked to this campaign and must match a format accepted by the media buy's products — otherwise the update fails with a validation error. type: array items: type: string minLength: 1 required: - mediaBuyId additionalProperties: false pacingPeriods: description: >- Pacing schedule for the campaign. Set to null to remove pacing periods and revert to standard single-period behavior. Can only be modified on DRAFT campaigns. nullable: true allOf: - $ref: '#/components/schemas/PacingPeriods' utmConfig: description: >- UTM (Urchin Tracking Module) parameter configuration for this campaign. Use deleteMissing: true to replace; otherwise additive. allOf: - $ref: '#/components/schemas/CampaignUtmConfig' dataDelivery: description: >- Campaign-scoped data-delivery configuration. Groups Data Delivery Outputs that override advertiser-scoped delivery for the same `dataDeliveryType`. Omit to leave existing config untouched. type: object properties: outputs: description: >- Campaign-scoped Data Delivery Outputs. Override advertiser-scoped Outputs by `dataDeliveryType`. Replaces all existing campaign-scoped Outputs when provided. Pass an empty array to clear. Omit to leave existing Outputs untouched. allOf: - $ref: '#/components/schemas/DataDeliveryOutputArrayInput' frequencyCaps: description: >- Buyer-side frequency cap configs for this campaign, enforced via Scope3's cross-publisher exposure tracking on TMP-connected inventory — not enforceable at request time on closed-platform integrations (e.g. TikTok, Meta, Snap). Use `targetingOverlay.frequency_cap` on the product for those. When provided, replaces all existing non-archived caps for this campaign (pass an empty array to clear). Omit to leave existing caps untouched. type: array items: $ref: '#/components/schemas/FrequencyCapConfigInput' autonomy: description: >- Autonomy settings for this campaign. Set inventorySelection: "automatic" to let the platform optimizer own composition; "manual" (default) allows buyer-driven staging. type: object properties: inventorySelection: description: >- How inventory is selected: manual (buyer-driven, default), propose (agent drafts for approval), automatic (platform optimizer owns composition — manual staging is rejected). type: string enum: - manual - propose - automatic rebriefing: description: >- How the brief is updated: manual (human), propose (agent drafts), automatic (agent applies). type: string enum: - manual - propose - automatic mode: not: {} UpdateDiscoveryCampaignBody: type: object properties: name: description: Updated campaign name type: string minLength: 1 maxLength: 255 flightDates: description: Updated campaign flight dates type: object properties: startDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Campaign start date (ISO 8601) example: '2025-01-15T00:00:00Z' endDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Campaign end date (ISO 8601) example: '2025-03-31T23:59:59Z' required: - startDate - endDate budget: description: Updated budget configuration (partial updates allowed) type: object properties: total: type: number minimum: 0 exclusiveMinimum: true currency: default: USD type: string minLength: 3 maxLength: 3 dailyCap: type: number minimum: 0 exclusiveMinimum: true pacing: type: string enum: - EVEN - ASAP - FRONTLOADED brief: description: Updated campaign brief type: string maxLength: 5000 constraints: description: Updated targeting constraints type: object properties: geo_countries: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_countries_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_regions: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback. geo_regions_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Exclude exact canonical ISO 3166-2 subdivisions. Support is independent from geo_regions inclusion support. Unknown identifiers and values also present in geo_regions are invalid. At create or update, sellers MUST reject unsupported identifiers and partial application; during get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. geo_metros: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: A targeted metro area. description: >- Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities. geo_metros_exclude: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes to exclude within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: >- Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Restrict delivery to specific postal areas. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas_exclude: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Exclude specific postal areas from delivery. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. language: minItems: 1 type: array items: type: string minLength: 2 maxLength: 63 pattern: >- ^(?:[a-z]{2,8}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*(?:-[0-9a-wy-z](?:-[a-z0-9]{2,8})+)*(?:-x(?:-[a-z0-9]{1,8})+)?|x(?:-[a-z0-9]{1,8})+)$ description: >- A well-formed BCP 47 language tag used by AdCP only as language identity. Script and region may refine that identity; other valid BCP 47 subtags remain part of tag matching but do not make this a general locale-settings object. It does not determine currency, time zone, number/date formatting, market, or legal jurisdiction. The AdCP canonical wire profile requires lower-case language and variants, title-case script, and upper-case region (for example `en-US`, `zh-Hant-TW`, or `x-private`). RFC 5646 comparisons are case-insensitive and its case regularization is optional; AdCP intentionally requires this stricter single wire spelling and receivers MUST reject differently cased tags rather than silently normalizing them. The schema pattern enforces the AdCP casing profile and extension structure for commonly used tags; conforming receivers additionally validate the complete RFC 5646 grammar and registry rules. Every new AdCP field carrying BCP 47 language identity or a concrete language range MUST reference this schema instead of declaring independent string constraints. description: >- Restrict to users with specific language preferences using canonical BCP 47 language ranges. Each buyer range is evaluated against a user's language-preference tag with RFC 4647 section 3.3.1 Basic Filtering: 'fr' matches 'fr', 'fr-CA', and 'fr-FR', while 'fr-CA' matches 'fr-CA' and more-specific descendants but not 'fr' or 'fr-FR'. Values use OR logic. device_platform: minItems: 1 type: array items: type: string enum: - ios - android - windows - macos - linux - chromeos - tvos - tizen - webos - fire_os - roku_os - unknown description: >- Operating system platforms for device targeting. Browser values from Sec-CH-UA-Platform standard, extended for CTV. description: >- Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV. device_type: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns). device_type_exclude: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns). channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: >- Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write. deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: {} channelGroups: description: >- Canonical buyer-declared inventory execution and reporting boundaries. Pass null to clear before any selection or media buy references a group. nullable: true minItems: 1 maxItems: 25 type: array items: type: object properties: channelGroupId: type: string minLength: 1 maxLength: 128 name: type: string minLength: 1 maxLength: 120 source: oneOf: - type: object properties: kind: type: string enum: - preset presetId: type: string enum: - display - olv - mobile_web_display - mobile_web_olv - ctv description: >- Versioned channel group preset to expand into AdCP inventory dimensions. presetVersion: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - kind - presetId - presetVersion additionalProperties: false - type: object properties: kind: type: string enum: - custom required: - kind additionalProperties: false type: object inventory: type: object properties: channels: description: Buyer-declared AdCP media channels. Values are OR. minItems: 1 type: array items: type: string enum: - display - olv - social - search - ctv - linear_tv - radio - streaming_audio - podcast - dooh - ooh - print - cinema - email - gaming - retail_media - influencer - affiliate - product_placement - sponsored_intelligence propertyTypes: description: Buyer-declared AdCP property types. Values are OR. minItems: 1 type: array items: type: string enum: - website - mobile_app - ctv_app - desktop_app - dooh - podcast - radio - linear_tv - streaming_audio - ai_assistant deviceTypes: description: Buyer-declared AdCP device types. Values are OR. minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown formatKinds: description: >- Buyer-declared AdCP canonical creative format kinds. Values are OR. minItems: 1 type: array items: type: string enum: - image - html5 - display_tag - image_carousel - video_hosted - video_vast - audio_hosted - audio_vast - audio_daast - sponsored_placement - native_in_feed - responsive_creative - agent_placement - seller_rendered_stateful_display - coordinated_placements - custom additionalProperties: false required: - channelGroupId - name - source - inventory additionalProperties: false storefrontIds: description: >- Updated storefront filter for the campaign. Pass an empty array to clear (no storefront limit). Subsequent product discovery runs against this campaign auto-apply the new filter. example: - 42 - 57 maxItems: 50 type: array items: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 discoveryId: description: Attach a discovery session to the campaign type: string minLength: 1 audienceConfig: description: >- Audience targeting and suppression configuration. Use deleteMissing: true to replace the full audience set. type: object properties: targetAudienceIds: description: >- Audience IDs to target. Can be empty when deleteMissing is true to remove all targeted audiences. example: - aud_123 - aud_456 maxItems: 100 type: array items: type: string minLength: 1 suppressAudienceIds: description: >- Audience IDs to suppress. Can be empty when deleteMissing is true to remove all suppressed audiences. example: - aud_789 maxItems: 100 type: array items: type: string minLength: 1 deleteMissing: description: >- When true, audiences NOT in the respective lists are removed. When false or omitted, lists are additive. type: boolean performanceConfig: description: >- Updated optimization goals (hints only). Pass null to clear. Goals are allowed on any campaign — they do not gate composition. Set `autonomy.inventorySelection: "automatic"` to delegate composition to the platform optimizer (AI-8988). nullable: true allOf: - $ref: '#/components/schemas/PerformanceConfig' optimizationApplyMode: description: >- Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual approval. If omitted, inherits the advertiser-level setting. allOf: - $ref: '#/components/schemas/OptimizationApplyMode' catalogId: description: Catalog ID to attach (or null to detach the current catalog) nullable: true type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 mediaBuys: description: >- Media buy actions. Each entry targets a specific media buy by ID. Use action: "update" (default) to modify, "cancel" to cancel, or "delete" to archive. type: array items: type: object properties: action: description: >- Action to perform. "update" (default) modifies the media buy, "cancel" cancels it, "delete" archives it. type: string enum: - update - cancel - delete mediaBuyId: type: string minLength: 1 description: ID of the media buy to act on reason: description: 'Cancellation reason (only for action: "cancel")' type: string maxLength: 1000 packageIds: description: >- Cancel specific packages instead of the whole media buy (only for action: "cancel") type: array items: type: string minLength: 1 name: description: Updated media buy name type: string minLength: 1 maxLength: 255 packages: description: Per-package updates (for media buys with deployed packages) type: array items: type: object properties: packageId: type: string minLength: 1 description: Package ID to update budget: description: Updated budget amount type: number minimum: 0 exclusiveMinimum: true pacing: description: Updated pacing strategy type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. nullable: true type: number startTime: description: >- Updated flight start date/time for this package (ISO 8601). Must fall within the media buy's date range. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ endTime: description: >- Updated flight end date/time for this package (ISO 8601). Must fall within the media buy's date range. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ targetingOverlay: type: object properties: audience_include: anyOf: - minItems: 1 type: array items: type: string description: >- Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities. - type: string nullable: true enum: - null audience_exclude: anyOf: - minItems: 1 type: array items: type: string description: >- Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities. - type: string nullable: true enum: - null geo_countries: anyOf: - minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). - type: string nullable: true enum: - null geo_regions: anyOf: - minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback. - type: string nullable: true enum: - null additionalProperties: false description: >- Per-dimension targeting patch. Omit a field to preserve its current value, pass null to clear it, or pass a value to replace it. Not every adapter supports every field at update time; an unsupported field is rejected with UNSUPPORTED_TARGETING_DIMENSION. required: - packageId additionalProperties: false pacingPeriods: description: >- Per-media-buy pacing schedule. When set, replaces the campaign-level pacingPeriods for this specific buy. Use to heavy-up or shape spend on one media buy without affecting others. Pass null to clear an existing per-buy schedule. Bootstrapping a schedule onto an unpaced media buy is only allowed in DRAFT or PENDING_APPROVAL status. See the Pacing Periods guide for the full state matrix and sales-agent capability requirements. nullable: true allOf: - $ref: '#/components/schemas/PacingPeriods' products: description: >- Product updates — additive (existing products not listed are preserved). Use remove: true to delete a product. type: array items: type: object properties: productId: type: string minLength: 1 description: Product ID storefrontId: description: Exact Storefront identity returned by discovery type: string pattern: ^[1-9]\d*$ inventorySourceId: description: >- Exact inventory-source identity returned by discovery; null identifies Storefront-owned inventory nullable: true type: string pattern: ^[1-9]\d*$ pricingOptionId: type: string buyerRef: description: >- Line-item handle from the media buy read. Required to target one line item when the same product appears more than once on the buy; omit when the product is unique. type: string minLength: 1 maxLength: 255 budget: type: number minimum: 0 exclusiveMinimum: true pacing: type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. nullable: true type: number remove: description: Set to true to remove this product from the media buy type: boolean pageId: description: >- Platform-specific page identity for ad placements. Required for Meta products when the connected ad account has more than one authorized Facebook Page — pass one of the page IDs listed in the error message. Omit when the account has exactly one authorized page. example: '1147910135081908' type: string minLength: 1 pixelId: description: >- Meta Pixel / Dataset ID for conversion tracking. Required for Meta Sales (OUTCOME_SALES) products — pass the pixel ID listed in the error message. There is no auto-select: every Meta Sales buy must explicitly specify a pixel. example: '123456789012345' type: string minLength: 1 instagramActorId: description: >- Meta Instagram account ID for Instagram Direct destinations (Instagram Direct Conversations, Instagram-based Lead Generation). Required when the connected ad account has more than one authorized Instagram account — unlike pageId, the error does not enumerate candidate IDs; obtain the Instagram Business Account ID from Meta Business Settings. Omit when the account has exactly one authorized Instagram account (the server selects it automatically). example: '17841400000000000' type: string minLength: 1 welcomeMessageFlowId: description: >- Meta welcome message flow ID for lead-to-message destinations (Messenger, Instagram Direct, and WhatsApp Lead Generation). Required for these products — pass one of the welcome-message-flow candidates returned by account resource readiness in the discovery/get_products response. example: '1122334455667788' type: string minLength: 1 required: - productId additionalProperties: false start_time: description: >- "asap" or ISO 8601 date-time. Start of this media buy. Cannot be earlier than the campaign's flightDates.startDate. Media buy dates MAY correspond to a pacingPeriods[].start when the media buy represents a specific period, but pacing periods do not govern media buy dates — a media buy can have any start within the campaign flight, with or without pacing periods. type: string end_time: description: >- ISO 8601 date-time. End of this media buy. Must fall within the campaign's flight dates. Media buy dates MAY correspond to a pacingPeriods[].end when the media buy represents a specific period, but pacing periods do not govern media buy dates — a media buy can have any end within the campaign flight, with or without pacing periods. type: string updated_reason: description: >- Reason for the update (stored with the new version for SCD Type 2) type: string suggestion_id: description: Suggestion ID from RL optimizer type: string optimization_goals: description: >- Optimization goals applied to every package at execution time. Each goal is either `{ kind: "event", event_sources: [{ event_source_id, event_type }], target? }` or `{ kind: "metric", metric, target? }`. Event target kinds: `cost_per` (CPA), `per_ad_spend` (ROAS), `maximize_value`. Metric target kinds: `cost_per`, `threshold_rate`. ALWAYS ask the buyer what they want to optimize for before updating — do not change goals silently. Pass an empty array to clear all goals. type: array items: anyOf: - type: object properties: kind: type: string enum: - metric metric: anyOf: - type: string enum: - clicks - type: string enum: - views - type: string enum: - completed_views - type: string enum: - viewed_seconds - type: string enum: - attention_seconds - type: string enum: - attention_score - type: string enum: - engagements - type: string enum: - follows - type: string enum: - saves - type: string enum: - profile_visits - type: string enum: - reach reach_unit: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom target_frequency: anyOf: - type: object properties: {} additionalProperties: {} - type: object properties: {} additionalProperties: {} view_duration_seconds: type: number target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - metric additionalProperties: {} - type: object properties: kind: type: string enum: - event event_sources: type: array items: type: object properties: event_source_id: type: string event_type: anyOf: - type: string enum: - page_view - type: string enum: - view_content - type: string enum: - select_content - type: string enum: - select_item - type: string enum: - search - type: string enum: - share - type: string enum: - add_to_cart - type: string enum: - remove_from_cart - type: string enum: - viewed_cart - type: string enum: - add_to_wishlist - type: string enum: - initiate_checkout - type: string enum: - add_payment_info - type: string enum: - purchase - type: string enum: - refund - type: string enum: - lead - type: string enum: - qualify_lead - type: string enum: - close_convert_lead - type: string enum: - disqualify_lead - type: string enum: - complete_registration - type: string enum: - subscribe - type: string enum: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - type: string enum: - start_trial - type: string enum: - app_install - type: string enum: - app_launch - type: string enum: - contact - type: string enum: - schedule - type: string enum: - donate - type: string enum: - submit_application - type: string enum: - custom custom_event_name: type: string value_field: type: string value_factor: type: number required: - event_source_id - event_type additionalProperties: {} target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: {} attribution_window: type: object properties: post_click: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} post_view: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string pattern: ^[a-z0-9_]+$ countries: type: array items: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media synthetic_depiction: type: boolean ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string created_time: type: string c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: integer minimum: 1 maximum: 9007199254740991 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - vendor - metric_id additionalProperties: {} creative_ids: description: >- Explicit creative IDs to attach to this media buy. When provided, overrides the campaign-level auto-sync (which otherwise pushes the campaign's manifest-linked creatives, filtered to formats accepted by this buy's products). Pass an empty array to clear all creatives. Omit (or leave undefined) to use auto-sync. Each ID must already be linked to this campaign and must match a format accepted by the media buy's products — otherwise the update fails with a validation error. type: array items: type: string minLength: 1 required: - mediaBuyId additionalProperties: false pacingPeriods: description: >- Pacing schedule for the campaign. Set to null to remove pacing periods and revert to standard single-period behavior. Can only be modified on DRAFT campaigns. nullable: true allOf: - $ref: '#/components/schemas/PacingPeriods' utmConfig: description: >- UTM (Urchin Tracking Module) parameter configuration for this campaign. Use deleteMissing: true to replace; otherwise additive. allOf: - $ref: '#/components/schemas/CampaignUtmConfig' dataDelivery: description: >- Campaign-scoped data-delivery configuration. Groups Data Delivery Outputs that override advertiser-scoped delivery for the same `dataDeliveryType`. Omit to leave existing config untouched. type: object properties: outputs: description: >- Campaign-scoped Data Delivery Outputs. Override advertiser-scoped Outputs by `dataDeliveryType`. Replaces all existing campaign-scoped Outputs when provided. Pass an empty array to clear. Omit to leave existing Outputs untouched. allOf: - $ref: '#/components/schemas/DataDeliveryOutputArrayInput' frequencyCaps: description: >- Buyer-side frequency cap configs for this campaign, enforced via Scope3's cross-publisher exposure tracking on TMP-connected inventory — not enforceable at request time on closed-platform integrations (e.g. TikTok, Meta, Snap). Use `targetingOverlay.frequency_cap` on the product for those. When provided, replaces all existing non-archived caps for this campaign (pass an empty array to clear). Omit to leave existing caps untouched. type: array items: $ref: '#/components/schemas/FrequencyCapConfigInput' autonomy: description: >- Autonomy settings for this campaign. Set inventorySelection: "automatic" to let the platform optimizer own composition; "manual" (default) allows buyer-driven staging. type: object properties: inventorySelection: description: >- How inventory is selected: manual (buyer-driven, default), propose (agent drafts for approval), automatic (platform optimizer owns composition — manual staging is rejected). type: string enum: - manual - propose - automatic rebriefing: description: >- How the brief is updated: manual (human), propose (agent drafts), automatic (agent applies). type: string enum: - manual - propose - automatic mode: type: string enum: - discovery description: >- Campaign mode. Present for symmetry with create; a campaign cannot change mode via update. Optimization goals (performanceConfig) are allowed regardless of mode — they are hints, not a composition-ownership declaration. required: - mode description: Request body for updating a discovery-mode campaign UpdatePerformanceCampaignBody: type: object properties: name: description: Updated campaign name type: string minLength: 1 maxLength: 255 flightDates: description: Updated campaign flight dates type: object properties: startDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Campaign start date (ISO 8601) example: '2025-01-15T00:00:00Z' endDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Campaign end date (ISO 8601) example: '2025-03-31T23:59:59Z' required: - startDate - endDate budget: description: Updated budget configuration (partial updates allowed) type: object properties: total: type: number minimum: 0 exclusiveMinimum: true currency: default: USD type: string minLength: 3 maxLength: 3 dailyCap: type: number minimum: 0 exclusiveMinimum: true pacing: type: string enum: - EVEN - ASAP - FRONTLOADED brief: description: Updated campaign brief type: string maxLength: 5000 constraints: description: Updated targeting constraints type: object properties: geo_countries: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_countries_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_regions: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback. geo_regions_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Exclude exact canonical ISO 3166-2 subdivisions. Support is independent from geo_regions inclusion support. Unknown identifiers and values also present in geo_regions are invalid. At create or update, sellers MUST reject unsupported identifiers and partial application; during get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. geo_metros: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: A targeted metro area. description: >- Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities. geo_metros_exclude: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes to exclude within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: >- Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Restrict delivery to specific postal areas. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas_exclude: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Exclude specific postal areas from delivery. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. language: minItems: 1 type: array items: type: string minLength: 2 maxLength: 63 pattern: >- ^(?:[a-z]{2,8}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*(?:-[0-9a-wy-z](?:-[a-z0-9]{2,8})+)*(?:-x(?:-[a-z0-9]{1,8})+)?|x(?:-[a-z0-9]{1,8})+)$ description: >- A well-formed BCP 47 language tag used by AdCP only as language identity. Script and region may refine that identity; other valid BCP 47 subtags remain part of tag matching but do not make this a general locale-settings object. It does not determine currency, time zone, number/date formatting, market, or legal jurisdiction. The AdCP canonical wire profile requires lower-case language and variants, title-case script, and upper-case region (for example `en-US`, `zh-Hant-TW`, or `x-private`). RFC 5646 comparisons are case-insensitive and its case regularization is optional; AdCP intentionally requires this stricter single wire spelling and receivers MUST reject differently cased tags rather than silently normalizing them. The schema pattern enforces the AdCP casing profile and extension structure for commonly used tags; conforming receivers additionally validate the complete RFC 5646 grammar and registry rules. Every new AdCP field carrying BCP 47 language identity or a concrete language range MUST reference this schema instead of declaring independent string constraints. description: >- Restrict to users with specific language preferences using canonical BCP 47 language ranges. Each buyer range is evaluated against a user's language-preference tag with RFC 4647 section 3.3.1 Basic Filtering: 'fr' matches 'fr', 'fr-CA', and 'fr-FR', while 'fr-CA' matches 'fr-CA' and more-specific descendants but not 'fr' or 'fr-FR'. Values use OR logic. device_platform: minItems: 1 type: array items: type: string enum: - ios - android - windows - macos - linux - chromeos - tvos - tizen - webos - fire_os - roku_os - unknown description: >- Operating system platforms for device targeting. Browser values from Sec-CH-UA-Platform standard, extended for CTV. description: >- Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV. device_type: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns). device_type_exclude: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns). channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: >- Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write. deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: {} channelGroups: description: >- Canonical buyer-declared inventory execution and reporting boundaries. Pass null to clear before any selection or media buy references a group. nullable: true minItems: 1 maxItems: 25 type: array items: type: object properties: channelGroupId: type: string minLength: 1 maxLength: 128 name: type: string minLength: 1 maxLength: 120 source: oneOf: - type: object properties: kind: type: string enum: - preset presetId: type: string enum: - display - olv - mobile_web_display - mobile_web_olv - ctv description: >- Versioned channel group preset to expand into AdCP inventory dimensions. presetVersion: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - kind - presetId - presetVersion additionalProperties: false - type: object properties: kind: type: string enum: - custom required: - kind additionalProperties: false type: object inventory: type: object properties: channels: description: Buyer-declared AdCP media channels. Values are OR. minItems: 1 type: array items: type: string enum: - display - olv - social - search - ctv - linear_tv - radio - streaming_audio - podcast - dooh - ooh - print - cinema - email - gaming - retail_media - influencer - affiliate - product_placement - sponsored_intelligence propertyTypes: description: Buyer-declared AdCP property types. Values are OR. minItems: 1 type: array items: type: string enum: - website - mobile_app - ctv_app - desktop_app - dooh - podcast - radio - linear_tv - streaming_audio - ai_assistant deviceTypes: description: Buyer-declared AdCP device types. Values are OR. minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown formatKinds: description: >- Buyer-declared AdCP canonical creative format kinds. Values are OR. minItems: 1 type: array items: type: string enum: - image - html5 - display_tag - image_carousel - video_hosted - video_vast - audio_hosted - audio_vast - audio_daast - sponsored_placement - native_in_feed - responsive_creative - agent_placement - seller_rendered_stateful_display - coordinated_placements - custom additionalProperties: false required: - channelGroupId - name - source - inventory additionalProperties: false storefrontIds: description: >- Updated storefront filter for the campaign. Pass an empty array to clear (no storefront limit). Subsequent product discovery runs against this campaign auto-apply the new filter. example: - 42 - 57 maxItems: 50 type: array items: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 discoveryId: description: Attach a discovery session to the campaign type: string minLength: 1 audienceConfig: description: >- Audience targeting and suppression configuration. Use deleteMissing: true to replace the full audience set. type: object properties: targetAudienceIds: description: >- Audience IDs to target. Can be empty when deleteMissing is true to remove all targeted audiences. example: - aud_123 - aud_456 maxItems: 100 type: array items: type: string minLength: 1 suppressAudienceIds: description: >- Audience IDs to suppress. Can be empty when deleteMissing is true to remove all suppressed audiences. example: - aud_789 maxItems: 100 type: array items: type: string minLength: 1 deleteMissing: description: >- When true, audiences NOT in the respective lists are removed. When false or omitted, lists are additive. type: boolean performanceConfig: description: >- Updated optimization goals (hints only). Pass null to clear. Goals are allowed on any campaign — they do not gate composition. Set `autonomy.inventorySelection: "automatic"` to delegate composition to the platform optimizer (AI-8988). nullable: true allOf: - $ref: '#/components/schemas/PerformanceConfig' optimizationApplyMode: description: >- Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual approval. If omitted, inherits the advertiser-level setting. allOf: - $ref: '#/components/schemas/OptimizationApplyMode' catalogId: description: Catalog ID to attach (or null to detach the current catalog) nullable: true type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 mediaBuys: description: >- Media buy actions. Each entry targets a specific media buy by ID. Use action: "update" (default) to modify, "cancel" to cancel, or "delete" to archive. type: array items: type: object properties: action: description: >- Action to perform. "update" (default) modifies the media buy, "cancel" cancels it, "delete" archives it. type: string enum: - update - cancel - delete mediaBuyId: type: string minLength: 1 description: ID of the media buy to act on reason: description: 'Cancellation reason (only for action: "cancel")' type: string maxLength: 1000 packageIds: description: >- Cancel specific packages instead of the whole media buy (only for action: "cancel") type: array items: type: string minLength: 1 name: description: Updated media buy name type: string minLength: 1 maxLength: 255 packages: description: Per-package updates (for media buys with deployed packages) type: array items: type: object properties: packageId: type: string minLength: 1 description: Package ID to update budget: description: Updated budget amount type: number minimum: 0 exclusiveMinimum: true pacing: description: Updated pacing strategy type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. nullable: true type: number startTime: description: >- Updated flight start date/time for this package (ISO 8601). Must fall within the media buy's date range. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ endTime: description: >- Updated flight end date/time for this package (ISO 8601). Must fall within the media buy's date range. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ targetingOverlay: type: object properties: audience_include: anyOf: - minItems: 1 type: array items: type: string description: >- Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities. - type: string nullable: true enum: - null audience_exclude: anyOf: - minItems: 1 type: array items: type: string description: >- Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities. - type: string nullable: true enum: - null geo_countries: anyOf: - minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). - type: string nullable: true enum: - null geo_regions: anyOf: - minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback. - type: string nullable: true enum: - null additionalProperties: false description: >- Per-dimension targeting patch. Omit a field to preserve its current value, pass null to clear it, or pass a value to replace it. Not every adapter supports every field at update time; an unsupported field is rejected with UNSUPPORTED_TARGETING_DIMENSION. required: - packageId additionalProperties: false pacingPeriods: description: >- Per-media-buy pacing schedule. When set, replaces the campaign-level pacingPeriods for this specific buy. Use to heavy-up or shape spend on one media buy without affecting others. Pass null to clear an existing per-buy schedule. Bootstrapping a schedule onto an unpaced media buy is only allowed in DRAFT or PENDING_APPROVAL status. See the Pacing Periods guide for the full state matrix and sales-agent capability requirements. nullable: true allOf: - $ref: '#/components/schemas/PacingPeriods' products: description: >- Product updates — additive (existing products not listed are preserved). Use remove: true to delete a product. type: array items: type: object properties: productId: type: string minLength: 1 description: Product ID storefrontId: description: Exact Storefront identity returned by discovery type: string pattern: ^[1-9]\d*$ inventorySourceId: description: >- Exact inventory-source identity returned by discovery; null identifies Storefront-owned inventory nullable: true type: string pattern: ^[1-9]\d*$ pricingOptionId: type: string buyerRef: description: >- Line-item handle from the media buy read. Required to target one line item when the same product appears more than once on the buy; omit when the product is unique. type: string minLength: 1 maxLength: 255 budget: type: number minimum: 0 exclusiveMinimum: true pacing: type: string enum: - even - asap - front_loaded bidPrice: description: Updated bid price (CPM). Pass null to clear. nullable: true type: number remove: description: Set to true to remove this product from the media buy type: boolean pageId: description: >- Platform-specific page identity for ad placements. Required for Meta products when the connected ad account has more than one authorized Facebook Page — pass one of the page IDs listed in the error message. Omit when the account has exactly one authorized page. example: '1147910135081908' type: string minLength: 1 pixelId: description: >- Meta Pixel / Dataset ID for conversion tracking. Required for Meta Sales (OUTCOME_SALES) products — pass the pixel ID listed in the error message. There is no auto-select: every Meta Sales buy must explicitly specify a pixel. example: '123456789012345' type: string minLength: 1 instagramActorId: description: >- Meta Instagram account ID for Instagram Direct destinations (Instagram Direct Conversations, Instagram-based Lead Generation). Required when the connected ad account has more than one authorized Instagram account — unlike pageId, the error does not enumerate candidate IDs; obtain the Instagram Business Account ID from Meta Business Settings. Omit when the account has exactly one authorized Instagram account (the server selects it automatically). example: '17841400000000000' type: string minLength: 1 welcomeMessageFlowId: description: >- Meta welcome message flow ID for lead-to-message destinations (Messenger, Instagram Direct, and WhatsApp Lead Generation). Required for these products — pass one of the welcome-message-flow candidates returned by account resource readiness in the discovery/get_products response. example: '1122334455667788' type: string minLength: 1 required: - productId additionalProperties: false start_time: description: >- "asap" or ISO 8601 date-time. Start of this media buy. Cannot be earlier than the campaign's flightDates.startDate. Media buy dates MAY correspond to a pacingPeriods[].start when the media buy represents a specific period, but pacing periods do not govern media buy dates — a media buy can have any start within the campaign flight, with or without pacing periods. type: string end_time: description: >- ISO 8601 date-time. End of this media buy. Must fall within the campaign's flight dates. Media buy dates MAY correspond to a pacingPeriods[].end when the media buy represents a specific period, but pacing periods do not govern media buy dates — a media buy can have any end within the campaign flight, with or without pacing periods. type: string updated_reason: description: >- Reason for the update (stored with the new version for SCD Type 2) type: string suggestion_id: description: Suggestion ID from RL optimizer type: string optimization_goals: description: >- Optimization goals applied to every package at execution time. Each goal is either `{ kind: "event", event_sources: [{ event_source_id, event_type }], target? }` or `{ kind: "metric", metric, target? }`. Event target kinds: `cost_per` (CPA), `per_ad_spend` (ROAS), `maximize_value`. Metric target kinds: `cost_per`, `threshold_rate`. ALWAYS ask the buyer what they want to optimize for before updating — do not change goals silently. Pass an empty array to clear all goals. type: array items: anyOf: - type: object properties: kind: type: string enum: - metric metric: anyOf: - type: string enum: - clicks - type: string enum: - views - type: string enum: - completed_views - type: string enum: - viewed_seconds - type: string enum: - attention_seconds - type: string enum: - attention_score - type: string enum: - engagements - type: string enum: - follows - type: string enum: - saves - type: string enum: - profile_visits - type: string enum: - reach reach_unit: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom target_frequency: anyOf: - type: object properties: {} additionalProperties: {} - type: object properties: {} additionalProperties: {} view_duration_seconds: type: number target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - metric additionalProperties: {} - type: object properties: kind: type: string enum: - event event_sources: type: array items: type: object properties: event_source_id: type: string event_type: anyOf: - type: string enum: - page_view - type: string enum: - view_content - type: string enum: - select_content - type: string enum: - select_item - type: string enum: - search - type: string enum: - share - type: string enum: - add_to_cart - type: string enum: - remove_from_cart - type: string enum: - viewed_cart - type: string enum: - add_to_wishlist - type: string enum: - initiate_checkout - type: string enum: - add_payment_info - type: string enum: - purchase - type: string enum: - refund - type: string enum: - lead - type: string enum: - qualify_lead - type: string enum: - close_convert_lead - type: string enum: - disqualify_lead - type: string enum: - complete_registration - type: string enum: - subscribe - type: string enum: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - type: string enum: - start_trial - type: string enum: - app_install - type: string enum: - app_launch - type: string enum: - contact - type: string enum: - schedule - type: string enum: - donate - type: string enum: - submit_application - type: string enum: - custom custom_event_name: type: string value_field: type: string value_factor: type: number required: - event_source_id - event_type additionalProperties: {} target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: {} attribution_window: type: object properties: post_click: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} post_view: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string pattern: ^[a-z0-9_]+$ countries: type: array items: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media synthetic_depiction: type: boolean ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string created_time: type: string c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: integer minimum: 1 maximum: 9007199254740991 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - vendor - metric_id additionalProperties: {} creative_ids: description: >- Explicit creative IDs to attach to this media buy. When provided, overrides the campaign-level auto-sync (which otherwise pushes the campaign's manifest-linked creatives, filtered to formats accepted by this buy's products). Pass an empty array to clear all creatives. Omit (or leave undefined) to use auto-sync. Each ID must already be linked to this campaign and must match a format accepted by the media buy's products — otherwise the update fails with a validation error. type: array items: type: string minLength: 1 required: - mediaBuyId additionalProperties: false pacingPeriods: description: >- Pacing schedule for the campaign. Set to null to remove pacing periods and revert to standard single-period behavior. Can only be modified on DRAFT campaigns. nullable: true allOf: - $ref: '#/components/schemas/PacingPeriods' utmConfig: description: >- UTM (Urchin Tracking Module) parameter configuration for this campaign. Use deleteMissing: true to replace; otherwise additive. allOf: - $ref: '#/components/schemas/CampaignUtmConfig' dataDelivery: description: >- Campaign-scoped data-delivery configuration. Groups Data Delivery Outputs that override advertiser-scoped delivery for the same `dataDeliveryType`. Omit to leave existing config untouched. type: object properties: outputs: description: >- Campaign-scoped Data Delivery Outputs. Override advertiser-scoped Outputs by `dataDeliveryType`. Replaces all existing campaign-scoped Outputs when provided. Pass an empty array to clear. Omit to leave existing Outputs untouched. allOf: - $ref: '#/components/schemas/DataDeliveryOutputArrayInput' frequencyCaps: description: >- Buyer-side frequency cap configs for this campaign, enforced via Scope3's cross-publisher exposure tracking on TMP-connected inventory — not enforceable at request time on closed-platform integrations (e.g. TikTok, Meta, Snap). Use `targetingOverlay.frequency_cap` on the product for those. When provided, replaces all existing non-archived caps for this campaign (pass an empty array to clear). Omit to leave existing caps untouched. type: array items: $ref: '#/components/schemas/FrequencyCapConfigInput' autonomy: description: >- Autonomy settings for this campaign. Set inventorySelection: "automatic" to let the platform optimizer own composition; "manual" (default) allows buyer-driven staging. type: object properties: inventorySelection: description: >- How inventory is selected: manual (buyer-driven, default), propose (agent drafts for approval), automatic (platform optimizer owns composition — manual staging is rejected). type: string enum: - manual - propose - automatic rebriefing: description: >- How the brief is updated: manual (human), propose (agent drafts), automatic (agent applies). type: string enum: - manual - propose - automatic mode: type: string enum: - performance description: >- Campaign mode. Present for symmetry with create; a campaign cannot change mode via update. required: - mode description: Request body for updating a performance-mode campaign RefreshDirectedCampaignBody: type: object properties: mode: type: string enum: - directed refresh: type: boolean enum: - true description: >- Trigger a mirror refresh against the upstream provider without writing to it. required: - mode - refresh additionalProperties: false description: >- Request body for refreshing a directed campaign mirror without an upstream mutation. Campaign: type: object properties: campaignId: type: string description: Unique identifier for the campaign example: cmp_987654321 advertiserId: nullable: true description: >- Advertiser ID that owns this campaign. Null for a small number of campaigns that predate advertiser linking and are accessible to every advertiser on the account. example: '12345' type: string name: type: string description: Campaign name example: Summer 2025 Campaign status: type: string enum: - DRAFT - ACTIVE - PAUSED - COMPLETED - CANCELED - ARCHIVED description: Current campaign status archivedAt: description: >- When this campaign was archived (ISO 8601). Archiving controls visibility and preserves the campaign status. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ mode: description: >- Who is steering this campaign — discovery, performance, or directed. Backfilled by projection for existing campaigns (see deriveCampaignMode); no data movement. The "directed" value is deprecated: read `management` instead. allOf: - $ref: '#/components/schemas/CampaignMode' management: description: >- Whether the platform acts on this campaign: "tracked" (a campaign the platform did not set up, mirrored read-only from a connected provider account) or "managed" (authored or adopted through the platform). allOf: - $ref: '#/components/schemas/CampaignManagement' directed: description: >- Subscription-backed directed mirror state — connection, upstream account, dual-keyed ids, and sync health. Not present on inbound single-storefront AdCP campaigns. allOf: - $ref: '#/components/schemas/DirectedCampaignInfo' mediaBuyRefs: description: >- Lightweight references to every media buy on this campaign (id + status). Surfaced early in the response so LLM callers can enumerate media buy IDs even when the full nested `mediaBuys[]` tail is truncated by a small context window. Use the `mediaBuyId` query param on `get_campaign` to drill into specific buys without loading the full tree. type: array items: $ref: '#/components/schemas/MediaBuyRef' brief: description: Campaign brief type: string flightDates: description: Campaign flight dates type: object properties: startDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Campaign start date (ISO 8601) example: '2025-01-15T00:00:00Z' endDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Campaign end date (ISO 8601) example: '2025-03-31T23:59:59Z' required: - startDate - endDate additionalProperties: false budget: description: Campaign budget configuration type: object properties: total: type: number minimum: 0 exclusiveMinimum: true currency: default: USD type: string minLength: 3 maxLength: 3 dailyCap: type: number minimum: 0 exclusiveMinimum: true pacing: type: string enum: - EVEN - ASAP - FRONTLOADED required: - total - currency additionalProperties: false allocatedBudget: description: >- Sum of the budgets of every media buy that still holds budget on this campaign — DRAFT, PENDING_APPROVAL, INPUT_REQUIRED, ACTIVE, and PAUSED — plus performance spend on media buys that have reached a terminal status (COMPLETED, CANCELED, FAILED, REJECTED, ARCHIVED) or have otherwise been archived. A DRAFT media buy holds budget exactly as a live one does and is already counted here. Only present when the campaign has a budget.total set. Expressed in the campaign budget currency. example: 7500 type: number minimum: 0 unallocatedBudget: description: >- Budget remaining for allocation — a new media buy, or an increase to an existing one — computed server-side as budget.total minus allocatedBudget. For a media buy that still holds budget on this campaign, allocatedBudget already includes that buy's current budget, so use this value directly rather than adding it back in. For a terminal media buy being revived, only its delivered spend sits in allocatedBudget — the ceiling for the revived buy's new budget is unallocatedBudget + that buy's delivered spend. Only present when the campaign has a budget.total set. Expressed in the campaign budget currency. May be negative if performance spend on terminal media buys exceeds budget.total. example: 2500 type: number pacingPeriods: description: >- Pacing schedule for the campaign, if configured. In responses, each period includes a resolved budget (computed dollar amount). In weight mode, weights are preserved alongside the resolved budget. allOf: - $ref: '#/components/schemas/PacingPeriodsOutput' constraints: description: Targeting constraints type: object properties: geo_countries: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_countries_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_regions: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback. geo_regions_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Exclude exact canonical ISO 3166-2 subdivisions. Support is independent from geo_regions inclusion support. Unknown identifiers and values also present in geo_regions are invalid. At create or update, sellers MUST reject unsupported identifiers and partial application; during get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. geo_metros: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: A targeted metro area. description: >- Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities. geo_metros_exclude: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes to exclude within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: >- Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system additionalProperties: false - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Restrict delivery to specific postal areas. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas_exclude: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system additionalProperties: false - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Exclude specific postal areas from delivery. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. language: minItems: 1 type: array items: type: string minLength: 2 maxLength: 63 pattern: >- ^(?:[a-z]{2,8}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*(?:-[0-9a-wy-z](?:-[a-z0-9]{2,8})+)*(?:-x(?:-[a-z0-9]{1,8})+)?|x(?:-[a-z0-9]{1,8})+)$ description: >- A well-formed BCP 47 language tag used by AdCP only as language identity. Script and region may refine that identity; other valid BCP 47 subtags remain part of tag matching but do not make this a general locale-settings object. It does not determine currency, time zone, number/date formatting, market, or legal jurisdiction. The AdCP canonical wire profile requires lower-case language and variants, title-case script, and upper-case region (for example `en-US`, `zh-Hant-TW`, or `x-private`). RFC 5646 comparisons are case-insensitive and its case regularization is optional; AdCP intentionally requires this stricter single wire spelling and receivers MUST reject differently cased tags rather than silently normalizing them. The schema pattern enforces the AdCP casing profile and extension structure for commonly used tags; conforming receivers additionally validate the complete RFC 5646 grammar and registry rules. Every new AdCP field carrying BCP 47 language identity or a concrete language range MUST reference this schema instead of declaring independent string constraints. description: >- Restrict to users with specific language preferences using canonical BCP 47 language ranges. Each buyer range is evaluated against a user's language-preference tag with RFC 4647 section 3.3.1 Basic Filtering: 'fr' matches 'fr', 'fr-CA', and 'fr-FR', while 'fr-CA' matches 'fr-CA' and more-specific descendants but not 'fr' or 'fr-FR'. Values use OR logic. device_platform: minItems: 1 type: array items: type: string enum: - ios - android - windows - macos - linux - chromeos - tvos - tizen - webos - fire_os - roku_os - unknown description: >- Operating system platforms for device targeting. Browser values from Sec-CH-UA-Platform standard, extended for CTV. description: >- Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV. device_type: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns). device_type_exclude: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns). channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: >- Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write. deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ geo_metro_names: description: >- Display labels for included geo_metros codes. Only present when requested with fields=geo_metro_names. allOf: - $ref: '#/components/schemas/CampaignGeoMetroNames' geo_metro_names_exclude: description: >- Display labels for excluded geo_metros_exclude codes. Only present when requested with fields=geo_metro_names. allOf: - $ref: '#/components/schemas/CampaignGeoMetroNames' additionalProperties: {} storefronts: description: >- Storefronts the campaign is pinned to. When set, every product discovery run for this campaign auto-applies the corresponding storefront filter. Each entry includes both the storefront DB `id` and the public `platformId` + `name` so the response is renderable without a follow-up lookup. Absent or empty means the campaign is not pinned to any specific storefronts. type: array items: $ref: '#/components/schemas/CampaignStorefrontRef' performanceConfig: description: Performance configuration (present for performance campaigns) allOf: - $ref: '#/components/schemas/PerformanceConfigOutput' autonomy: description: >- Buyer autonomy preferences for this campaign. Controls whether the agent acts automatically or requires human approval per dimension. type: object properties: inventorySelection: description: >- How the agent selects inventory: manual (human-driven), propose (agent drafts, human approves), automatic (agent acts). type: string enum: - manual - propose - automatic rebriefing: description: >- How the brief is updated: manual (human), propose (agent drafts), automatic (agent applies). type: string enum: - manual - propose - automatic additionalProperties: false optimizationApplyMode: description: >- Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual approval. Defaults to the advertiser-level setting if not explicitly set on the campaign. allOf: - $ref: '#/components/schemas/OptimizationApplyMode' catalogId: description: Attached catalog ID example: 42 type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 discoveryId: description: >- ID of the discovery session used to select products for this campaign. Only present for DRAFT campaigns; after execution, product data is represented through media buys. example: session_abc123 type: string productCount: description: >- Number of products selected for this campaign. Only present for DRAFT campaigns; after execution, product data is represented through media buys. example: 15 type: integer minimum: 0 maximum: 9007199254740991 products: description: >- Products selected for this campaign. Only present for DRAFT campaigns; after execution, product data is represented through media buys. type: array items: type: object properties: productId: type: string description: Unique identifier for the product example: prod_123 required: - productId additionalProperties: false audiences: description: >- Audiences associated with this campaign (both targeted and suppressed) type: array items: type: object properties: audienceId: type: string description: Unique identifier for the audience example: aud_123 name: nullable: true description: Display name of the audience example: Tech Enthusiasts 25-34 type: string status: type: string enum: - PROCESSING - ERROR - READY - TOO_SMALL description: >- Processing status of the audience (e.g. READY, PROCESSING, TOO_SMALL) example: READY type: type: string enum: - TARGET - SUPPRESS description: Whether this audience is targeted or suppressed (excluded) example: TARGET enabledAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: When the audience was enabled for this campaign (ISO 8601) example: '2025-03-01T12:00:00Z' required: - audienceId - name - status - type - enabledAt additionalProperties: false creativeFormats: description: >- Canonical creative format coverage for this campaign — URL-free format kinds required by selected products, covered by uploaded creatives, and still missing. Surface `missing` to prompt the user to upload the remaining creatives. type: object properties: required: type: array items: type: object properties: format_kind: type: string required: - format_kind additionalProperties: false covered: type: array items: type: object properties: format_kind: type: string required: - format_kind additionalProperties: false missing: type: array items: type: object properties: format_kind: type: string required: - format_kind additionalProperties: false required: - required - covered - missing additionalProperties: false propertyLists: description: >- Include/exclude property lists actually applied to this campaign via its media-buy packages. Only present when `includePropertyLists=true` is passed. An empty `propertyLists` array is the authoritative answer that no lists are applied; do not infer presence from the campaign brief or constraints. type: object properties: propertyLists: type: array items: type: object properties: listId: type: string name: type: string purpose: type: string enum: - include - exclude propertyCount: type: integer minimum: 0 maximum: 9007199254740991 createdAt: type: string updatedAt: type: string viaMediaBuys: type: array items: type: object properties: mediaBuyId: type: string packageIds: type: array items: type: string required: - mediaBuyId - packageIds additionalProperties: false required: - listId - name - purpose - propertyCount - createdAt - updatedAt - viaMediaBuys additionalProperties: false summary: type: object properties: totalLists: type: integer minimum: 0 maximum: 9007199254740991 includeCount: type: integer minimum: 0 maximum: 9007199254740991 excludeCount: type: integer minimum: 0 maximum: 9007199254740991 required: - totalLists - includeCount - excludeCount additionalProperties: false required: - propertyLists - summary additionalProperties: false mediaBuys: description: >- Media buys associated with this campaign. Present after execution; contains the product allocations, packages, and delivery data for each sales agent. type: array items: type: object properties: mediaBuyId: type: string description: Unique identifier for the media buy name: type: string description: Media buy name channelGroup: description: >- Campaign channel group that compiled into this media buy. Absent for legacy and ungrouped buys. type: object properties: channelGroupId: type: string name: type: string required: - channelGroupId - name additionalProperties: false status: type: string description: >- Current media buy status (e.g. DRAFT, ACTIVE, PAUSED, COMPLETED) revision: description: >- Last authoritative provider revision observed for this media buy. type: integer minimum: 0 maximum: 9007199254740991 validActions: description: >- Provider-reported AdCP actions that are currently valid for this media buy. type: array items: type: string pendingAt: description: >- Which layer the media buy is parked at; only present while status is PENDING_APPROVAL. 'storefront' = waiting for the storefront operator's manual approval, 'salesagent' = the inventory source is still processing the buy, 'unknown' = the pending layer is indeterminate. type: string enum: - storefront - salesagent - unknown pendingReason: description: >- Why the buy is not delivering yet, rolled up to the most-blocking wait across its legs. An annotation derived from persisted forwarding state — never a status. Absent when the buy is delivering, terminal, or not storefront-routed. allOf: - $ref: '#/components/schemas/MediaBuyPendingReason' pendingSince: description: >- When the current wait began (ISO 8601). Present when pendingReason is set and the start of the wait is known. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ errorCode: description: >- Buyer-safe structured error code when forwarding failed or the buy was rejected. Internal platform codes are mapped to this set and never emitted raw. allOf: - $ref: '#/components/schemas/BuyerMediaBuyErrorCode' errorOwner: description: >- Which party owns fixing the error. Present whenever errorCode is present. allOf: - $ref: '#/components/schemas/MediaBuyErrorOwner' sourceMessage: description: >- The source's rejection or moderation message, when one was provided — whitespace-collapsed, truncated, and known upstream identifiers removed. type: string forwardedAt: description: >- When the buy was forwarded to its inventory source(s) (ISO 8601). Absent when it has not been forwarded. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ buyerReference: description: >- Support reference for this buy (`sf::`). Quote it with the request timestamp when contacting the seller or Scope3 support. example: sf:42:sf_mb_1783031864469_8pbc8mmr type: string startTime: description: >- When this media buy starts. Either "asap" (start immediately on activation) or an ISO 8601 date-time. Falls within the parent campaign's flightDates. example: '2025-04-14T00:00:00Z' type: string endTime: description: >- When this media buy ends, as an ISO 8601 date-time. Falls within the parent campaign's flightDates. example: '2025-04-30T23:59:59Z' type: string budget_denomination: description: >- Denomination marker: every budget on this media buy is GROSS (fee-inclusive) in the buyer currency. Present only for buys with locked fee terms (it travels with budget_breakdown); absent for legacy buys created before fee terms were locked, whose budgets pass through as stored. type: string enum: - gross budget_breakdown: description: >- Read-only gross/media/fee split of the buy's total budget at the fee terms locked when the media buy was created. Omitted for legacy buys created before fee terms were locked. Buyer surfaces only. type: object properties: media_budget: type: number description: >- Media portion of the gross budget (gross minus the buyer fee) at the fee terms locked when the media buy was created, in major units. fee_amount: type: number description: >- Buyer fee carved from the gross budget at the locked fee rate, in major units. fee_rate_percent: type: number description: >- The Scope3 fee as a percentage of the media budget (fee ÷ media × 100). For example, a 5% fee on media produces a value of 5 here regardless of how the fee was stored internally. effective_gross_cpm: nullable: true description: >- Gross budget ÷ impression goal × 1000 — the CPM that makes "budget ÷ CPM = impressions" hold for the gross numbers the buyer operates on. Null when the buy has no positive impression goal. type: number required: - media_budget - fee_amount - fee_rate_percent - effective_gross_cpm additionalProperties: false products: description: Products configured for this media buy type: array items: type: object properties: productId: type: string description: Product identifier productName: description: >- Human-readable product name. May be absent for products whose `products` cache row has not yet been populated. type: string publisherName: description: >- Publisher name for this product. May be absent for products whose `products` cache row has not yet been populated. type: string salesAgentName: description: Name of the sales agent for this product type: string buyerRef: description: >- Stable per-line-item handle, distinct even when the same product appears more than once on the buy. Pass as products[].buyerRef on update to target this specific line item. type: string budget: description: Budget allocated to this product type: number budgetCurrency: description: Currency for the budget type: string formatOptions: description: >- Publisher-declared format requirements for this product. Each entry has a stable format_option_id selector when supplied by the seller, a format_kind (e.g. "video_vast", "video_hosted", "image", "html5"), and a params object. For video products, check entries with format_kind "video_vast" or "video_hosted" for params.duration_ms_exact (required duration in ms), params.width and params.height (required pixel dimensions). type: array items: type: object properties: format_kind: type: string enum: - image - html5 - display_tag - image_carousel - video_hosted - video_vast - audio_hosted - audio_vast - audio_daast - sponsored_placement - native_in_feed - responsive_creative - agent_placement - seller_rendered_stateful_display - coordinated_placements - custom params: type: object properties: width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 sizes: minItems: 1 type: array items: type: object properties: width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 required: - width - height additionalProperties: false min_width: type: integer minimum: 1 maximum: 9007199254740991 max_width: type: integer minimum: 1 maximum: 9007199254740991 min_height: type: integer minimum: 1 maximum: 9007199254740991 max_height: type: integer minimum: 1 maximum: 9007199254740991 duration_ms_exact: type: integer minimum: 1 maximum: 9007199254740991 duration_ms_range: type: array items: nullable: true type: number additionalProperties: {} format_option_id: type: string minLength: 1 required: - format_kind - params additionalProperties: false required: - productId additionalProperties: false pacingPeriods: description: >- Per-media-buy pacing schedule. When set, this buy is shaped by its own schedule rather than the campaign-level pacingPeriods. Each period includes a resolved budget; in weight mode, weights are preserved alongside the resolved budget. allOf: - $ref: '#/components/schemas/PacingPeriodsOutput' packages: description: Packages created after media buy execution type: array items: type: object properties: packageId: type: string description: Package identifier status: type: string description: Package status (active, paused) budget: description: Package budget amount type: number budgetCurrency: description: Budget currency code (e.g. USD) type: string pacing: description: Pacing strategy (even, asap, front_loaded) type: string bidPrice: description: Bid price for this package type: number startTime: description: >- Flight start date/time for this package (ISO 8601), if set. type: string endTime: description: >- Flight end date/time for this package (ISO 8601), if set. type: string targetingOverlay: allOf: - $ref: '#/components/schemas/CampaignPackageTargetingOverlay' providerTargeting: allOf: - $ref: '#/components/schemas/ProviderTargetingReadback' providerPlacementControls: type: object properties: placement_soft_opt_out: type: object properties: {} additionalProperties: false required: - placement_soft_opt_out additionalProperties: false requestedTargeting: description: >- Canonical targeting requested when Scope3 created this adapter package. allOf: - $ref: '#/components/schemas/ProviderTargetingReadback' targetingMatchesRequest: description: >- Whether the current provider-normalized targeting still equals the canonical request. type: boolean geoRegionMappings: description: ISO subdivision to provider-region identity evidence. type: array items: type: object properties: iso_code: type: string provider_key: type: string required: - iso_code - provider_key additionalProperties: false geoCityMappings: description: Canonical city to provider-city identity evidence. type: array items: type: object properties: country: type: string pattern: ^[A-Z]{2}$ name: type: string minLength: 1 provider_key: type: string pattern: ^\d+$ canonical_id: type: string minLength: 1 system: type: string minLength: 1 system_version: type: string minLength: 1 provider_country: type: string pattern: ^[A-Z]{2}$ provider_name: type: string minLength: 1 provider_canonical_id: type: string minLength: 1 required: - country - name - provider_key additionalProperties: false productIds: type: array items: type: string description: Product IDs in this package delivery: description: Delivery metrics for this package type: object properties: impressions: type: number description: Delivered impressions spend: type: number description: >- Delivered spend in the buyer's GROSS (fee-inclusive) denomination, grossed up at the buy's pinned pricing terms. Net-as-reported for legacy buys with no pinned terms. clicks: nullable: true description: Click count type: number required: - impressions - spend - clicks additionalProperties: false creatives: description: Creatives assigned to this package type: array items: type: object properties: creativeId: type: string description: Creative manifest ID name: type: string description: Creative display name formatId: type: object properties: id: type: string description: Format identifier (e.g. display_300x250) agent_url: type: string description: ADCP agent URL this format belongs to required: - id - agent_url additionalProperties: {} description: Format ID for this creative status: type: string description: Creative status sourceSyncStatus: type: array items: type: object properties: agentId: type: string description: >- Legacy internal ADCP agent database ID, preserved for compatibility sourceId: nullable: true description: >- Public ADCP agent or inventory source ID captured for this creative sync route. A legacy-agent value is the protocol-level agent ID, never the numeric database ID; null means retained history predates a captured public source identity type: string approvalStatus: nullable: true description: >- Approval status returned by the source for this creative type: string rejectionReason: nullable: true description: >- Rejection reason returned by the source, if any type: string required: - agentId - sourceId - approvalStatus - rejectionReason additionalProperties: false description: >- Per-source creative sync verdicts. Empty array when the creative has not yet been synced to any source. storefrontReviewStatus: nullable: true description: >- Storefront operator review status for this creative. Null when the storefront uses automatic approval or the creative has not been submitted for review. allOf: - $ref: '#/components/schemas/CreativeReviewStatus' required: - creativeId - name - formatId - status - sourceSyncStatus - storefrontReviewStatus additionalProperties: false required: - packageId - status - productIds additionalProperties: false optimizationGoals: description: >- Optimization goals applied to every package at execution time. Each goal is either `{ kind: "event", event_sources: [{ event_source_id, event_type }], target? }` or `{ kind: "metric", metric, target? }`. Event target kinds: `cost_per` (CPA), `per_ad_spend` (ROAS), `maximize_value`. Metric target kinds: `cost_per`, `threshold_rate`. type: array items: anyOf: - type: object properties: kind: type: string enum: - metric metric: anyOf: - type: string enum: - clicks - type: string enum: - views - type: string enum: - completed_views - type: string enum: - viewed_seconds - type: string enum: - attention_seconds - type: string enum: - attention_score - type: string enum: - engagements - type: string enum: - follows - type: string enum: - saves - type: string enum: - profile_visits - type: string enum: - reach reach_unit: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom target_frequency: anyOf: - type: object properties: {} additionalProperties: {} - type: object properties: {} additionalProperties: {} view_duration_seconds: type: number target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - metric additionalProperties: {} - type: object properties: kind: type: string enum: - event event_sources: type: array items: type: object properties: event_source_id: type: string event_type: anyOf: - type: string enum: - page_view - type: string enum: - view_content - type: string enum: - select_content - type: string enum: - select_item - type: string enum: - search - type: string enum: - share - type: string enum: - add_to_cart - type: string enum: - remove_from_cart - type: string enum: - viewed_cart - type: string enum: - add_to_wishlist - type: string enum: - initiate_checkout - type: string enum: - add_payment_info - type: string enum: - purchase - type: string enum: - refund - type: string enum: - lead - type: string enum: - qualify_lead - type: string enum: - close_convert_lead - type: string enum: - disqualify_lead - type: string enum: - complete_registration - type: string enum: - subscribe - type: string enum: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - type: string enum: - start_trial - type: string enum: - app_install - type: string enum: - app_launch - type: string enum: - contact - type: string enum: - schedule - type: string enum: - donate - type: string enum: - submit_application - type: string enum: - custom custom_event_name: type: string value_field: type: string value_factor: type: number required: - event_source_id - event_type additionalProperties: {} target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: {} attribution_window: type: object properties: post_click: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} post_view: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string pattern: ^[a-z0-9_]+$ countries: type: array items: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media synthetic_depiction: type: boolean ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string created_time: type: string c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: integer minimum: 1 maximum: 9007199254740991 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string minLength: 1 maxLength: 64 pattern: ^[a-z][a-z0-9_]*$ target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number required: - kind - vendor - metric_id additionalProperties: {} performance: description: >- Latest aggregate delivery snapshot for this media buy. windowStart/windowEnd identify the exact inclusive reporting period represented by the totals. type: object properties: impressions: type: number description: Total impressions delivered spend: type: number description: >- Total delivered spend in the buyer's GROSS (fee-inclusive) denomination, grossed up at the buy's pinned pricing terms. Net-as-reported for legacy buys with no pinned terms. clicks: type: number description: Total clicks views: type: number description: Total views (engagement-qualified) completedViews: type: number description: Total completed views (video / audio completions) conversions: type: number description: Total attributed conversions leads: type: number description: Total leads lastUpdated: description: When this snapshot was last refreshed (ISO 8601) type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ windowStart: description: >- Inclusive start date represented by this aggregate snapshot. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ windowEnd: description: Inclusive end date represented by this aggregate snapshot. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ required: - impressions - spend - clicks - views - completedViews - conversions - leads additionalProperties: false creatives: description: >- Creatives assigned to this media buy. Each entry includes source sync status across all sales agents. type: array items: type: object properties: creativeId: type: string description: Creative manifest ID name: type: string description: Creative display name formatId: type: object properties: id: type: string description: Format identifier (e.g. display_300x250) agent_url: type: string description: ADCP agent URL this format belongs to required: - id - agent_url additionalProperties: {} description: Format ID for this creative status: type: string description: Creative status sourceSyncStatus: type: array items: type: object properties: agentId: type: string description: >- Legacy internal ADCP agent database ID, preserved for compatibility sourceId: nullable: true description: >- Public ADCP agent or inventory source ID captured for this creative sync route. A legacy-agent value is the protocol-level agent ID, never the numeric database ID; null means retained history predates a captured public source identity type: string approvalStatus: nullable: true description: >- Approval status returned by the source for this creative type: string rejectionReason: nullable: true description: Rejection reason returned by the source, if any type: string required: - agentId - sourceId - approvalStatus - rejectionReason additionalProperties: false description: >- Per-source creative sync verdicts. Empty array when the creative has not yet been synced to any source. storefrontReviewStatus: nullable: true description: >- Storefront operator review status for this creative. Null when the storefront uses automatic approval or the creative has not been submitted for review. allOf: - $ref: '#/components/schemas/CreativeReviewStatus' required: - creativeId - name - formatId - status - sourceSyncStatus - storefrontReviewStatus additionalProperties: false createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: When the media buy was created (ISO 8601) updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: When the media buy was last updated (ISO 8601) required: - mediaBuyId - name - status - createdAt - updatedAt additionalProperties: false createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: When the campaign was created (ISO 8601) example: '2025-01-15T10:30:00Z' updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: When the campaign was last updated (ISO 8601) example: '2025-01-20T14:45:00Z' revision: default: 1 description: >- Monotonically increasing revision counter. Incremented on every mutation. Pass as expectedRevision in save_campaign to enable optimistic concurrency. example: 1 type: integer minimum: 1 maximum: 9007199254740991 dataDelivery: $ref: '#/components/schemas/CampaignDataDelivery' frequencyCaps: description: >- Buyer-side frequency cap configs for this campaign. Returned by `get_campaign`; not present on `list_campaigns` summary. type: array items: $ref: '#/components/schemas/FrequencyCapConfig' utmConfig: description: >- Resolved click-URL parameters for this campaign: campaign entries over advertiser entries, each with its `source`. Present only when at least one parameter resolves. type: array items: type: object properties: paramKey: type: string description: Output query parameter key example: utm_campaign paramValue: type: string description: Macro or static value example: '{CAMPAIGN_ID}' source: type: string enum: - advertiser - campaign description: >- Where this param was configured — "advertiser" for advertiser default, "campaign" for campaign override required: - paramKey - paramValue - source additionalProperties: false required: - campaignId - advertiserId - name - status - mode - management - optimizationApplyMode - createdAt - updatedAt - revision additionalProperties: false description: Campaign resource representation ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object PerformanceConfig: type: object properties: optimizationGoals: minItems: 1 type: array items: $ref: '#/components/schemas/OptimizationGoal' description: >- Optimization goals for the campaign. Each goal targets either conversion events or seller-native metrics. required: - optimizationGoals description: Configuration for performance campaign optimization OptimizationApplyMode: type: string enum: - AUTO - MANUAL description: >- Whether optimization suggestions are automatically applied or require human approval. PacingPeriods: type: object properties: mode: type: string enum: - weight - budget description: >- How period budgets are determined. "weight" uses relative weights to distribute the campaign budget proportionally. "budget" uses explicit dollar amounts per period. periods: minItems: 1 maxItems: 52 type: array items: type: object properties: label: type: string minLength: 1 maxLength: 100 description: >- Human-readable label for this period (e.g. "Memorial Day Heavy-Up") start: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Period start date (YYYY-MM-DD, inclusive) end: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Period end date (YYYY-MM-DD, inclusive) weight: description: >- Relative spend weight (1.0 = normal, 2.5 = 150% more, 0 = skip this period). Required when mode is "weight". type: number minimum: 0 maximum: 10 budget: description: >- Absolute budget for this period (0 = skip this period). Required when mode is "budget". type: number minimum: 0 required: - label - start - end description: Ordered list of pacing periods with date ranges and spend intensity required: - mode - periods description: >- Defines a pacing schedule for a campaign. Periods represent time windows with varying spend intensity. Gaps between periods are treated as pauses (no spend). Use weight mode for relative intensity (e.g., 2x during holidays) or budget mode for explicit dollar amounts per period. CampaignUtmConfig: type: object properties: params: maxItems: 50 type: array items: type: object properties: paramKey: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_.~-]{0,99}$ description: >- Output query parameter key appended to landing URL (e.g., "utm_source", "bg_campaign") example: utm_campaign paramValue: type: string minLength: 1 maxLength: 500 description: >- Macro name (e.g., "{CAMPAIGN_ID}") or static string (e.g., "scope3") to resolve as the value example: '{CAMPAIGN_ID}' required: - paramKey - paramValue description: Array of UTM parameter mappings for this campaign deleteMissing: description: >- If true, remove campaign-level UTM params not in this request (replace mode). If false/omitted, only add/update (additive mode). type: boolean required: - params description: >- UTM configuration for a campaign. Overrides advertiser-level defaults for matching param keys. DataDeliveryOutputArrayInput: maxItems: 20 type: array items: $ref: '#/components/schemas/DataDeliveryOutputInput' description: >- Array of Data Delivery Outputs for one scope (advertiser or campaign). At most one Output per (dataDeliveryType, credentialName) pair — the same data type can ship to multiple credentials by listing one Output per destination. FrequencyCapConfigInput: type: object properties: max_impressions: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Maximum number of impressions allowed within the window example: 3 window: $ref: '#/components/schemas/FrequencyCapWindow' required: - max_impressions - window additionalProperties: {} description: >- Frequency cap entry supplied inside a parent advertiser/campaign/creative request body. On PUT, the full array replaces all existing caps for that target. CampaignMode: type: string enum: - discovery - performance - directed description: >- Who is steering the campaign. "discovery" (brief-driven) and "performance" (objective-driven) are platform-managed. "directed" is a deprecated wire value retained for compatibility: read `management` instead — a directed campaign is either tracked (mirrored from a provider account we did not set up) or managed (authored through the platform against one storefront). CampaignManagement: type: string enum: - tracked - managed description: >- Whether the platform acts on this campaign. "tracked" = a campaign the platform did not set up, mirrored from a connected provider account: the shell is derived from the buys underneath, read-only, and updates automatically as the upstream campaign changes. "managed" = a campaign authored or adopted through the platform (get_products → create_media_buy → update_media_buy) — the platform sends instructions down. In both states the execution system remains the source of truth. DirectedCampaignInfo: oneOf: - $ref: '#/components/schemas/ConnectedAccountDirectedCampaignInfo' - $ref: '#/components/schemas/StorefrontEndpointDirectedCampaignInfo' description: >- Directed campaign provenance. Provider-account campaigns expose mirror health; storefront-endpoint campaigns expose the addressed storefront and dual-key identity. type: object discriminator: propertyName: provenance mapping: connected_account: $ref: '#/components/schemas/ConnectedAccountDirectedCampaignInfo' storefront_endpoint: $ref: '#/components/schemas/StorefrontEndpointDirectedCampaignInfo' MediaBuyRef: type: object properties: mediaBuyId: type: string description: Unique identifier for the media buy example: mb_ETBn4gJ9Wu channelGroup: description: Campaign channel group that compiled into this media buy. type: object properties: channelGroupId: type: string name: type: string required: - channelGroupId - name additionalProperties: false status: type: string description: >- Current or terminal status of the media buy (DRAFT, PENDING_APPROVAL, ACTIVE, PAUSED, COMPLETED, CANCELED, REJECTED, FAILED, ARCHIVED). Archived buys remain discoverable here as ARCHIVED even though they are omitted from the substantive mediaBuys array. A buy that is ACTIVE with a change awaiting approval reports ACTIVE here and carries `pendingChange`; a queued change never replaces this value. example: ACTIVE pendingAt: description: >- Which layer the media buy itself is parked at; only present while its own status is PENDING_APPROVAL (a buy awaiting its first approval). For a change queued behind an already-live buy, read `pendingChange.pendingAt`. 'storefront' = waiting for the storefront operator's manual approval, 'salesagent' = the inventory source is still processing the buy, 'unknown' = indeterminate. type: string enum: - storefront - salesagent - unknown pendingChange: $ref: '#/components/schemas/MediaBuyRefPendingChange' required: - mediaBuyId - status additionalProperties: false description: >- Lightweight media buy reference (id + live status). Used in Campaign.mediaBuyRefs so callers can enumerate media buys without loading the full nested tree. PacingPeriodsOutput: type: object properties: mode: type: string enum: - weight - budget description: >- How period budgets are determined. "weight" uses relative weights to distribute the campaign budget proportionally. "budget" uses explicit dollar amounts per period. periods: minItems: 1 maxItems: 52 type: array items: type: object properties: label: type: string minLength: 1 maxLength: 100 description: >- Human-readable label for this period (e.g. "Memorial Day Heavy-Up") start: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Period start date (YYYY-MM-DD, inclusive) end: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Period end date (YYYY-MM-DD, inclusive) weight: description: >- Relative spend weight (1.0 = normal, 2.5 = 150% more, 0 = skip this period). Required when mode is "weight". type: number minimum: 0 maximum: 10 budget: description: >- Absolute budget for this period (0 = skip this period). Required when mode is "budget". type: number minimum: 0 required: - label - start - end additionalProperties: false description: Ordered list of pacing periods with date ranges and spend intensity required: - mode - periods additionalProperties: false description: >- Defines a pacing schedule for a campaign. Periods represent time windows with varying spend intensity. Gaps between periods are treated as pauses (no spend). Use weight mode for relative intensity (e.g., 2x during holidays) or budget mode for explicit dollar amounts per period. CampaignGeoMetroNames: type: array items: type: object properties: system: type: string minLength: 1 description: >- Metro targeting system these display labels belong to, e.g. nielsen_dma. values: maxItems: 250 type: array items: type: object properties: code: type: string minLength: 1 description: Metro code from the corresponding metro targeting field. name: type: string minLength: 1 description: Human-readable display label for the metro code. required: - code - name additionalProperties: false required: - system - values additionalProperties: false description: >- Display labels for metro codes. Returned only when requested with fields=geo_metro_names; labels are derived from the local geo-metro label table and are not accepted on create/update. CampaignStorefrontRef: type: object properties: id: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Storefront DB ID example: 42 platformId: type: string description: >- Public-facing storefront slug (the platform identifier returned by `list_storefronts`) example: acme-media name: type: string description: Storefront display name example: Acme Media required: - id - platformId - name additionalProperties: false description: >- A storefront the campaign is pinned to, hydrated from the storefront IDs the buyer set on create/update. PerformanceConfigOutput: type: object properties: optimizationGoals: minItems: 1 type: array items: $ref: '#/components/schemas/OptimizationGoalOutput' description: >- Optimization goals for the campaign. Each goal targets either conversion events or seller-native metrics. required: - optimizationGoals additionalProperties: false description: Configuration for performance campaign optimization MediaBuyPendingReason: type: string enum: - forward_failed_needs_correction - forward_failed_retrying - awaiting_storefront_approval - awaiting_source_moderation - no_creatives_attached - source_rejected_creatives - creative_processing_at_source - awaiting_creative_approval - accepted_awaiting_trafficking - scheduled_not_started description: >- Why a not-yet-delivering media buy is waiting, and implicitly whose side owns the wait. A platform-derived annotation — never a status value. awaiting_storefront_approval / awaiting_source_moderation / creative_processing_at_source / awaiting_creative_approval = the seller side owns the wait; no_creatives_attached / source_rejected_creatives = the buyer owns it (attach or fix creatives); forward_failed_retrying / forward_failed_needs_correction = the platform owns it; accepted_awaiting_trafficking / scheduled_not_started = nothing is wrong, the buy is queued or scheduled. BuyerMediaBuyErrorCode: type: string enum: - product_no_longer_available - source_rejected - storefront_rejected - source_unavailable - invalid_request - quote_expired - platform_error description: >- Buyer-safe structured error code for a media buy that failed to forward or was rejected. Paired with errorOwner (who owns the fix) and, when the source provided one, a sanitized human-readable message. MediaBuyErrorOwner: type: string enum: - buyer_input - platform - seller description: >- Which party owns fixing the error: buyer_input (the request needs a correction from the buyer), platform (Scope3 owns the fault), seller (the storefront or its source made the decision or is unavailable). CampaignPackageTargetingOverlay: type: object properties: geo_countries: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_countries_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE'). geo_regions: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback. geo_regions_exclude: minItems: 1 type: array items: type: string pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$ description: >- Exclude exact canonical ISO 3166-2 subdivisions. Support is independent from geo_regions inclusion support. Unknown identifiers and values also present in geo_regions are invalid. At create or update, sellers MUST reject unsupported identifiers and partial application; during get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. geo_metros: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: A targeted metro area. description: >- Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities. geo_metros_exclude: minItems: 1 type: array items: type: object properties: system: type: string enum: - nielsen_dma - uk_itl1 - uk_itl2 - eurostat_nuts2 - custom description: >- Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2') values: minItems: 1 type: array items: type: string description: >- Metro codes to exclude within the system (e.g., ['501', '602'] for Nielsen DMAs) required: - system - values additionalProperties: false description: >- Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system additionalProperties: false - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Restrict delivery to specific postal areas. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. geo_postal_areas_exclude: minItems: 1 type: array items: anyOf: - allOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code for the postal values. system: type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Country-local postal code system (e.g., 'zip', 'outward', 'plz', 'postal_code'). values: minItems: 1 type: array items: type: string description: Postal codes within the country and system. required: - country - system - values additionalProperties: false - description: >- Valid country-local postal system pairing. Registered countries only accept their registered local systems; countries without a registered local system use postal_code or custom. anyOf: - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - US system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - zip - zip_plus_four required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - GB system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - outward - full required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - CA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - fsa - full required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - DE - CH - AT system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - plz required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - FR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - code_postal required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - AU system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postcode required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - BR system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - cep required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - IN system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - pin required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - type: string enum: - ZA system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code required: - country - system additionalProperties: false - type: object properties: country: allOf: - type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. - {} system: allOf: - type: string enum: - postal_code - zip - zip_plus_four - outward - full - fsa - plz - code_postal - postcode - cep - pin - custom - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: Country-local postal code system. - type: string enum: - postal_code - custom required: - country - system additionalProperties: false - type: object properties: system: type: string enum: - us_zip - us_zip_plus_four - gb_outward - gb_full - ca_fsa - ca_full - de_plz - fr_code_postal - au_postcode - ch_plz - at_plz description: >- Deprecated country-fused postal code system (e.g., 'us_zip', 'gb_outward'). Prefer country + postal-system. values: minItems: 1 type: array items: type: string description: Postal codes within the legacy system. required: - system - values additionalProperties: false description: >- Postal area values. Prefer the native country + postal system form. Deprecated legacy country-fused postal-system tokens remain accepted for compatibility. description: >- Exclude specific postal areas from delivery. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities. daypart_targets: minItems: 1 type: array items: type: object properties: days: minItems: 1 type: array items: type: string enum: - monday - tuesday - wednesday - thursday - friday - saturday - sunday description: Days of the week for daypart targeting description: >- Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object). start_hour: type: integer minimum: 0 maximum: 23 description: >- Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm. end_hour: type: integer minimum: 1 maximum: 24 description: >- End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour. timezone: default: inventory_local anyOf: - type: string enum: - inventory_local - description: >- Concrete timezone identifier in the implementation's supported IANA Time Zone Database, such as America/New_York, CET, or UTC. description: >- Civil-time clock used to evaluate this window. 'inventory_local' evaluates the hours in the seller-assigned local timezone of each inventory unit that can deliver the impression, such as a screen, venue, station, or publisher property; it never means the buyer, account, or server timezone. A concrete IANA timezone identifier (for example, 'America/New_York', 'CET', or 'UTC') evaluates one shared civil-time clock across the targeted inventory. Omission defaults to 'inventory_local'. Buyers that begin with a user or account preference MUST resolve it to a concrete IANA identifier before sending the daypart; 'user_timezone' and 'account_timezone' are not wire values. For each candidate delivery instant, convert the instant into this clock and compare its resulting local day and hour with the half-open window: a skipped DST hour has no matching instants, while both occurrences of a repeated hour match. This delivery clock is independent of reporting_capabilities.timezone. label: type: string description: >- Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time') required: - days - start_hour - end_hour - timezone additionalProperties: false description: >- A time window for daypart targeting. Specifies days of week, an hour range, and the civil-time clock used to evaluate it. start_hour is inclusive, end_hour is exclusive (e.g., 6-10 = 6:00am to 10:00am). Follows the Google Ads AdScheduleInfo / DV360 DayPartTargeting pattern. description: >- Restrict delivery to specific time windows. Each entry specifies days of week, an hour range, and an optional timezone that defaults to inventory_local. A concrete IANA zone uses one shared civil-time clock, while inventory_local evaluates each inventory unit in its seller-assigned local timezone. Entries are independent and MAY use different clocks. axe_include_segment: type: string description: >- Deprecated: Use TMP provider fields instead. AXE segment ID to include for targeting. axe_exclude_segment: type: string description: >- Deprecated: Use TMP provider fields instead. AXE segment ID to exclude from targeting. audience_include: minItems: 1 type: array items: type: string description: >- Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities. audience_exclude: minItems: 1 type: array items: type: string description: >- Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities. signal_targeting_groups: type: object properties: operator: type: string enum: - all description: >- Groups-level operator. Required even though v1 only supports 'all': every child group must be satisfied. groups: minItems: 1 type: array items: type: object properties: operator: type: string enum: - any - none description: >- How to evaluate the signals in this group. 'any' is an OR include group. 'none' is an exclusion group equivalent to NOT (A OR B OR C). signals: minItems: 1 type: array items: allOf: - type: object properties: pricing_option_id: type: string description: >- Pricing option selected for this signal. Use the pricing_option_id from the product's signal_targeting_options entry when product-scoped pricing is present; otherwise use the seller get_signals pricing only when the product option does not override it. Required when the selected signal has pricing_options; omit only when the signal is bundled into the product price or has no incremental cost. signal_agent_segment_id: type: string description: >- Optional opaque resolved-segment or seller execution handle for this signal. Omit when signal_ref plus the value expression is sufficient for the seller to resolve the signal. Include when the product option exposes a separate runtime or activation handle, and pass it verbatim. Buyers SHOULD prefer an exposed segment handle over reconstructing condition identity from categorical values because the handle can carry provider namespace and methodology distinctions. activation_key: allOf: - type: object additionalProperties: {} - {} description: >- Destination-specific activation key returned by get_signals or activate_signal. Usually omitted for seller-offered signals selected directly through the same seller; include only when the selected signal was separately activated and the seller requires the activation key to correlate the package selection. additionalProperties: {} - description: >- Predicate over a named signal definition. Signals are typed dimensions, similar to feature values: binary signals match true, categorical signals match one of a set of values, and numeric signals match a range. In package signal targeting groups, include/exclude semantics are controlled by the parent group operator, not by negating the expression. description: >- Buy-time selection of one seller-offered signal inside a package signal targeting group. The signal_ref uses scope 'product' for a product-local signal option, scope 'data_provider' for a signal defined in a data provider's published adagents.json signals[], or scope 'signal_source' for a source-native signal that is not published in adagents.json signals[]. The selected product's inline Product.signal_targeting_options, get_signals feed when inline options are omitted, and signal_targeting_rules define buy-time eligibility. Inclusion and exclusion are controlled by the parent group operator: use operator 'any' to include users matching the signal expression and operator 'none' to exclude users matching the signal expression. For binary signals, value MUST be true; do not use value=false for exclusion inside signal_targeting_groups. Use audience_include/audience_exclude only for buyer-managed first-party audiences registered through sync_audiences. description: >- Signal targeting entries evaluated by this group. Each entry uses the package signal targeting shape, including signal_ref, value expression, and optional pricing, execution-handle, or activation fields. required: - operator - signals additionalProperties: {} description: >- A basic Boolean group of package-level signal targeting entries. 'any' means the user must match at least one signal in the group. 'none' means the user must match none of the signals in the group. Use groups for portable include/exclude composition such as (A OR B) AND NOT (C OR D). description: >- Signal targeting groups to evaluate. Use operator 'any' for include groups and 'none' for exclusion groups. required: - operator - groups additionalProperties: {} description: >- Basic Boolean grouping for seller-offered signals. v1 supports a required top-level operator 'all' and child groups with operator 'any' for include groups or 'none' for exclusion groups. Example semantics: group 1 any(A, B) plus group 2 none(C, D) means (A OR B) AND NOT (C OR D). Signal entries reference named signal definitions with signal_ref scope 'product' for product-local signal options or scope 'data_provider' for external signals published in adagents.json signals[]. For simple include-only targeting, send one child group with operator 'any'. Sellers SHOULD reject entries that are not available for the product through inline signal_targeting_options or get_signals, are not active for the account, or exceed the product's signal_targeting_allowed/signal_targeting_rules/product terms. Signal targeting limits are product-scoped, not declared in get_adcp_capabilities, because products may be backed by different ad servers. Sellers MUST echo applied signal_targeting_groups on the resulting package state, including fixed/default selections. Sellers MAY return REQUOTE_REQUIRED when a targeting mutation changes commercial terms. signal_targeting: minItems: 1 type: array items: description: >- Targeting constraint for a specific signal. Uses value_type as discriminator to determine the targeting expression format. description: >- DEPRECATED. Use signal_targeting_groups for package-level signal targeting. Legacy flat signal_targeting remains accepted during the SignalRef migration window but cannot express grouped include/exclude composition or product-scoped pricing. demographics: type: object properties: age: allOf: - description: >- A canonical audience-age predicate in completed integer years. min and max are inclusive; omitting one bound means no restriction in that direction. At least one bound is required. include_unknown is always explicit because people whose age is unavailable are not members of any numeric interval. Implementations MUST reject min greater than max; JSON Schema draft-07 cannot compare sibling numeric values. anyOf: - type: object properties: min: allOf: - type: integer minimum: 0 maximum: 150 description: >- Inclusive minimum age in completed years. Omit for an open lower bound. - {} max: type: integer minimum: 0 maximum: 150 description: >- Inclusive maximum age in completed years. Omit for an open upper bound. include_unknown: type: boolean description: >- Whether delivery to people whose age is unavailable is part of this predicate. This field has no default and MUST be supplied. required: - include_unknown - min - type: object properties: min: type: integer minimum: 0 maximum: 150 description: >- Inclusive minimum age in completed years. Omit for an open lower bound. max: allOf: - type: integer minimum: 0 maximum: 150 description: >- Inclusive maximum age in completed years. Omit for an open upper bound. - {} include_unknown: type: boolean description: >- Whether delivery to people whose age is unavailable is part of this predicate. This field has no default and MUST be supplied. required: - include_unknown - max - type: object properties: accepted_bases: minItems: 1 type: array items: type: string enum: - verified - declared - inferred description: >- User-level bases that may resolve age for demographic targeting execution. Population estimates are deliberately absent because aggregate composition cannot establish an individual impression's age. description: >- User-level age determination bases the buyer permits for this predicate. Sellers MUST use only these bases or reject the request; they MUST NOT silently fall back to another basis. When omitted, the buyer imposes no determination-basis constraint beyond product capability and any age_restriction. population_estimate is structurally unavailable because aggregate evidence cannot identify an eligible user. accepted_verification_methods: minItems: 1 type: array items: type: string enum: - facial_age_estimation - id_document - digital_id - credit_card - world_id description: >- Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance. description: >- Verification methods acceptable when verified is an accepted basis. This field narrows verified demographic execution; age_restriction.accepted_methods independently governs legal eligibility and the two sets are intersected when both are present. additionalProperties: {} - anyOf: - {} - type: object properties: accepted_verification_methods: {} accepted_bases: {} required: - accepted_verification_methods - accepted_bases required: - age additionalProperties: {} description: >- Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis. frequency_cap: allOf: - type: object properties: suppress: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 description: Number of time units. Must be 1 when unit is 'campaign'. unit: type: string enum: - seconds - minutes - hours - days - campaign description: >- Time unit. 'seconds' for sub-minute precision. 'campaign' spans the full campaign flight. required: - interval - unit additionalProperties: false description: >- Cooldown period between consecutive exposures to the same entity. Prevents back-to-back ad delivery (e.g. {"interval": 60, "unit": "minutes"} for a 1-hour cooldown). Preferred over suppress_minutes. suppress_minutes: type: number minimum: 0 description: >- Deprecated — use suppress instead. Cooldown period in minutes between consecutive exposures to the same entity (e.g. 60 for a 1-hour cooldown). max_impressions: type: integer minimum: 1 maximum: 9007199254740991 description: >- Maximum number of impressions per entity per window. For duration windows, implementations typically use a rolling window. campaign applies across the owning field's full flight: the package flight for a targeting overlay, or the MediaBuy flight for a root cap. per: type: string enum: - individuals - households - devices - accounts - cookies - custom description: >- Entity granularity for impression counting. Required when max_impressions is set. window: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 description: Number of time units. Must be 1 when unit is 'campaign'. unit: type: string enum: - seconds - minutes - hours - days - campaign description: >- Time unit. 'seconds' for sub-minute precision. 'campaign' spans the full campaign flight. required: - interval - unit additionalProperties: false description: >- Time window for the max_impressions cap (e.g. {"interval": 7, "unit": "days"} or {"interval": 1, "unit": "campaign"} for the full flight). Required when max_impressions is set. additionalProperties: {} - anyOf: - type: object properties: suppress: {} required: - suppress additionalProperties: {} - type: object properties: suppress_minutes: {} required: - suppress_minutes additionalProperties: {} - type: object properties: max_impressions: {} required: - max_impressions additionalProperties: {} - anyOf: - {} - type: object properties: max_impressions: {} per: {} window: {} required: - max_impressions - per - window additionalProperties: {} - anyOf: - {} - type: object properties: per: {} max_impressions: {} required: - per - max_impressions additionalProperties: {} - anyOf: - {} - type: object properties: window: {} max_impressions: {} required: - window - max_impressions additionalProperties: {} description: >- Frequency capping settings for package-level application. Two types of frequency control can be used independently or together: suppress enforces a cooldown between consecutive exposures; max_impressions + per + window caps total exposures per entity in a time window. When both suppress and max_impressions are set, an impression is delivered only if both constraints permit it (AND semantics). At least one of suppress, suppress_minutes, or max_impressions must be set. Field location determines scope; this value has no scope discriminator. The MediaBuy root uses the narrower media-buy-frequency-cap schema, which permits maximum impressions only in 3.2. property_list: type: object properties: agent_url: type: string description: URL of the agent managing the property list list_id: type: string minLength: 1 description: Identifier for the property list within the agent auth_token: type: string description: >- JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access. required: - agent_url - list_id additionalProperties: false description: >- Reference to a property list for targeting specific properties within this product. The package runs on the intersection of the product's publisher_properties and this list. Sellers SHOULD return a validation error if the product has property_targeting_allowed: false. property_list_exclude: type: object properties: agent_url: type: string description: URL of the agent managing the property list list_id: type: string minLength: 1 description: Identifier for the property list within the agent auth_token: type: string description: >- JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access. required: - agent_url - list_id additionalProperties: false description: >- Reference to a property list whose properties must not carry the buyer's ads. Matched properties are removed from delivery. Use for brand-safety do-not-run lists (apps, sites). Exclude wins on overlap with property_list, and applies regardless of the product's property_targeting_allowed flag. Seller must declare support in get_adcp_capabilities. collection_list: type: object properties: agent_url: type: string description: URL of the agent managing the collection list list_id: type: string minLength: 1 description: Identifier for the collection list within the agent auth_token: type: string description: >- JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access. required: - agent_url - list_id additionalProperties: false description: >- Reference to a collection list for including specific collections (programs, publications, channels) within this product. The package runs on the intersection of matched collections and this list. Use for inclusion-based collection targeting. Seller must declare support in get_adcp_capabilities. collection_list_exclude: type: object properties: agent_url: type: string description: URL of the agent managing the collection list list_id: type: string minLength: 1 description: Identifier for the collection list within the agent auth_token: type: string description: >- JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access. required: - agent_url - list_id additionalProperties: false description: >- Reference to a collection list for excluding specific collections (programs, publications, channels) from this product. Matched collections must not carry the buyer's ads. Use for brand safety do-not-air lists. Seller must declare support in get_adcp_capabilities. placement_selection: allOf: - type: object additionalProperties: {} - {} description: >- Purchased placement selection within the product. This constrains package inventory; it is distinct from creative_assignments[].placement_refs, which only route individual creatives within the purchased set. On create, mode selected supplies the complete selected set and mode default uses the product default. In request-side Targeting Input, a non-null value replaces this dimension, omission preserves or inherits it, and null clears it when the product permits that broader inventory set. collection_selection: allOf: - type: object additionalProperties: {} - {} description: >- Purchased collection selection within the product. On create, mode selected supplies the complete selected set and mode default uses the product's full bundle. On package readback this is the committed selection sellers MUST echo as concrete selectors, materializing any collection_list composition; collection_list fields remain the buyer-managed list mechanism. In request-side Targeting Input, a non-null value replaces this dimension, omission preserves or inherits it, and null clears it when the product permits that broader inventory set. age_restriction: type: object properties: min: type: integer minimum: 13 maximum: 99 description: Minimum age required verification_required: default: false type: boolean description: Whether verified age (not inferred) is required for compliance accepted_methods: minItems: 1 type: array items: type: string enum: - facial_age_estimation - id_document - digital_id - credit_card - world_id description: >- Methods for verifying user age for compliance. Does not include 'inferred' as it is not accepted for regulatory compliance. description: >- Accepted verification methods. If omitted, any method the platform supports is acceptable. required: - min - verification_required additionalProperties: false description: >- Age restriction for compliance. Use for legal requirements (alcohol, gambling), not audience targeting. device_platform: minItems: 1 type: array items: type: string enum: - ios - android - windows - macos - linux - chromeos - tvos - tizen - webos - fire_os - roku_os - unknown description: >- Operating system platforms for device targeting. Browser values from Sec-CH-UA-Platform standard, extended for CTV. description: >- Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV. device_platform_exclude: minItems: 1 type: array items: type: string enum: - ios - android - windows - macos - linux - chromeos - tvos - tizen - webos - fire_os - roku_os - unknown description: >- Operating system platforms for device targeting. Browser values from Sec-CH-UA-Platform standard, extended for CTV. description: >- Exclude specific operating-system platforms from delivery. When a platform appears in both device_platform and device_platform_exclude, exclusion wins. Sellers MUST reject a request they cannot enforce rather than silently dropping the exclusion. device_type: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns). device_type_exclude: minItems: 1 type: array items: type: string enum: - desktop - mobile - tablet - ctv - dooh - unknown description: >- Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh. description: >- Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns). browser: minItems: 1 type: array items: type: string enum: - chrome - safari - firefox - edge - opera - samsung_internet - android_webview - other - unknown description: >- Portable browser families for targeting the impression delivery and rendering environment, not a post-click landing-page browser. Values identify browser families, not versions or seller-native browser IDs, and MUST NOT be inferred solely from operating system, device, web/mobile-web inventory, or placement. android_webview means an impression reliably classified as rendering in Android WebView. other means a seller-recognized browser family that is not explicitly enumerated; unknown means the seller cannot classify the browser into a recognized family. description: >- Restrict delivery to specific canonical browser families in the impression delivery and rendering environment, not the post-click landing-page browser. Values MUST NOT be inferred solely from operating system, device, web/mobile-web inventory, or placement. Values in this array use OR semantics. When browser is supplied, families not listed are ineligible: other includes a seller-recognized family that is not explicitly enumerated, while unknown includes a browser the seller cannot classify into a recognized family. When the same family appears in browser and browser_exclude, exclusion wins. Browser and device constraints intersect; a seller that cannot enforce the exact combination MUST exclude or explicitly reconfigure the product during discovery and MUST reject it at create or update rather than silently widening delivery. Browser versions and seller-native IDs are intentionally unsupported. browser_exclude: minItems: 1 type: array items: type: string enum: - chrome - safari - firefox - edge - opera - samsung_internet - android_webview - other - unknown description: >- Portable browser families for targeting the impression delivery and rendering environment, not a post-click landing-page browser. Values identify browser families, not versions or seller-native browser IDs, and MUST NOT be inferred solely from operating system, device, web/mobile-web inventory, or placement. android_webview means an impression reliably classified as rendering in Android WebView. other means a seller-recognized browser family that is not explicitly enumerated; unknown means the seller cannot classify the browser into a recognized family. description: >- Exclude specific canonical browser families from delivery. other excludes seller-recognized families that are not explicitly enumerated; unknown excludes browsers the seller cannot classify into a recognized family. When the same family appears in browser and browser_exclude, exclusion wins. Sellers MUST reject a request they cannot enforce rather than silently dropping the exclusion. store_catchments: minItems: 1 type: array items: type: object properties: catalog_id: type: string description: Synced store-type catalog ID from sync_catalogs. store_ids: minItems: 1 type: array items: type: string description: >- Filter to specific stores within the catalog. Omit to target all stores. catchment_ids: minItems: 1 type: array items: type: string description: >- Catchment zone IDs to target (e.g., 'walk', 'drive'). Omit to target all catchment zones. required: - catalog_id additionalProperties: {} description: >- Target users within store catchment areas from a synced store catalog. Each entry references a store-type catalog and optionally narrows to specific stores or catchment zones. geo_proximity: minItems: 1 type: array items: allOf: - type: object properties: lat: type: number minimum: -90 maximum: 90 description: >- Latitude in decimal degrees (WGS 84). Required for travel_time and radius methods. lng: type: number minimum: -180 maximum: 180 description: >- Longitude in decimal degrees (WGS 84). Required for travel_time and radius methods. label: type: string description: >- Human-readable label for this entry (e.g., 'Düsseldorf', 'Heathrow Airport', 'Primary trade area'). travel_time: type: object properties: value: type: number minimum: 1 description: Travel time limit. unit: type: string enum: - min - hr description: >- Time unit for isochrone (travel-time catchment) calculations. required: - value - unit additionalProperties: false description: >- Travel time limit for isochrone calculation. The platform resolves this to a geographic boundary based on actual transportation networks. transport_mode: type: string enum: - walking - cycling - driving - public_transport description: >- Transportation mode for isochrone calculation. Required when travel_time is provided. radius: type: object properties: value: type: number minimum: 0 exclusiveMinimum: true description: Radius distance. unit: type: string enum: - km - mi - m description: Distance unit. required: - value - unit additionalProperties: false description: >- Simple radius from the point. The platform draws a circle of this distance around the coordinates. geometry: type: object properties: type: type: string enum: - Polygon - MultiPolygon description: GeoJSON geometry type. coordinates: type: array items: {} description: >- GeoJSON coordinates array. For Polygon: array of linear rings. For MultiPolygon: array of polygons. required: - type - coordinates additionalProperties: false description: >- Pre-computed GeoJSON geometry defining the proximity boundary. Use when the buyer has already calculated isochrones (via TravelTime, Mapbox, etc.) or has custom boundaries. When geometry is provided, lat/lng are not required. ext: type: object additionalProperties: {} description: >- Extension object for platform-specific, vendor-namespaced parameters. Extensions are always optional and must be namespaced under a vendor/platform key (e.g., ext.gam, ext.roku). Used for custom capabilities, partner-specific configuration, and features being proposed for standardization. additionalProperties: {} - {} description: >- Target users within travel time, distance, or a custom boundary around arbitrary geographic points. Multiple entries use OR semantics — a user within range of any listed point is eligible. For campaigns targeting 10+ locations, consider using store_catchments with a location catalog instead. Seller must declare support in get_adcp_capabilities. language: minItems: 1 type: array items: type: string minLength: 2 maxLength: 63 pattern: >- ^(?:[a-z]{2,8}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*(?:-[0-9a-wy-z](?:-[a-z0-9]{2,8})+)*(?:-x(?:-[a-z0-9]{1,8})+)?|x(?:-[a-z0-9]{1,8})+)$ description: >- A well-formed BCP 47 language tag used by AdCP only as language identity. Script and region may refine that identity; other valid BCP 47 subtags remain part of tag matching but do not make this a general locale-settings object. It does not determine currency, time zone, number/date formatting, market, or legal jurisdiction. The AdCP canonical wire profile requires lower-case language and variants, title-case script, and upper-case region (for example `en-US`, `zh-Hant-TW`, or `x-private`). RFC 5646 comparisons are case-insensitive and its case regularization is optional; AdCP intentionally requires this stricter single wire spelling and receivers MUST reject differently cased tags rather than silently normalizing them. The schema pattern enforces the AdCP casing profile and extension structure for commonly used tags; conforming receivers additionally validate the complete RFC 5646 grammar and registry rules. Every new AdCP field carrying BCP 47 language identity or a concrete language range MUST reference this schema instead of declaring independent string constraints. description: >- Restrict to users with specific language preferences using canonical BCP 47 language ranges. Each buyer range is evaluated against a user's language-preference tag with RFC 4647 section 3.3.1 Basic Filtering: 'fr' matches 'fr', 'fr-CA', and 'fr-FR', while 'fr-CA' matches 'fr-CA' and more-specific descendants but not 'fr' or 'fr-FR'. Values use OR logic. keyword_targets: minItems: 1 type: array items: type: object properties: keyword: type: string minLength: 1 description: The keyword to target match_type: type: string enum: - broad - phrase - exact description: >- Keyword targeting match type. broad: ads may serve on queries semantically related to the keyword. phrase: ads serve when the query contains the keyword phrase. exact: ads serve only when the query matches the keyword exactly. bid_price: type: number minimum: 0 description: >- Per-keyword bid price, denominated in the same currency as the package's pricing option. Overrides the package-level bid_price for this keyword. Inherits the max_bid interpretation from the pricing option: when max_bid is true, this is the keyword's bid ceiling; when false, this is the exact bid. If omitted, the package bid_price applies. required: - keyword - match_type additionalProperties: false description: >- Keyword targeting for search and retail media platforms. Restricts delivery to queries matching the specified keywords. Each keyword is identified by the tuple (keyword, match_type) — the same keyword string with different match types are distinct targets. Sellers SHOULD reject duplicate (keyword, match_type) pairs within a single request. Seller must declare support in get_adcp_capabilities. negative_keywords: minItems: 1 type: array items: type: object properties: keyword: type: string minLength: 1 description: The keyword to exclude match_type: type: string enum: - broad - phrase - exact description: >- Keyword targeting match type. broad: ads may serve on queries semantically related to the keyword. phrase: ads serve when the query contains the keyword phrase. exact: ads serve only when the query matches the keyword exactly. required: - keyword - match_type additionalProperties: false description: An excluded keyword. description: >- Keywords to exclude from delivery. Queries matching these keywords will not trigger the ad. Each negative keyword is identified by the tuple (keyword, match_type). Seller must declare support in get_adcp_capabilities. additionalProperties: {} description: >- Targeting carried on a campaign package; directed adapters populate provider-normalized readback when supported. ProviderTargetingReadback: type: object properties: countries: type: array items: type: string regions: type: array items: type: string cities: type: array items: type: string zips: type: array items: type: string age_min: description: >- Provider-normalized minimum age. Readback can include provider-authored 13–17 targeting even though Scope3 controlled brief writes currently start at 18. type: integer minimum: 13 maximum: 65 age_max: description: >- Provider-normalized maximum age; 65 represents the provider 65+ upper bucket. type: integer minimum: 13 maximum: 65 genders: description: >- Provider-normalized gender restrictions. An empty array means unrestricted/all genders. type: array items: type: string enum: - FEMALE - MALE audience_include: description: >- Canonical buyer audience IDs confirmed as positively targeted. Native provider audience IDs are never exposed. type: array items: type: string minLength: 1 audience_exclude: description: >- Canonical buyer audience IDs confirmed as excluded. Native provider audience IDs are never exposed. type: array items: type: string minLength: 1 audience_expansion_enabled: description: >- Whether the provider confirmed audience expansion is enabled for this package. type: boolean publisher_platforms: type: array items: type: string enum: - facebook - instagram facebook_positions: type: array items: type: string enum: - facebook_reels - feed - story instagram_positions: type: array items: type: string enum: - reels - story - stream messenger_positions: type: array items: not: {} threads_positions: type: array items: not: {} device_platforms: type: array items: type: string enum: - mobile - desktop instream_video_skippable_excluded: type: boolean enum: - false required: - countries - regions - cities - zips additionalProperties: false description: >- Provider-normalized geographic, demographic, and audience targeting readback. Audience fields contain canonical buyer IDs, never native provider IDs. Only canonical allowlisted fields are exposed; raw provider extensions are never returned. CreativeReviewStatus: type: string enum: - pending - approved - rejected - revoked description: >- Lifecycle state of a buyer-submitted creative awaiting storefront review. `pending` until an operator decides; `approved` or `rejected` after a decision; `revoked` if an operator pulls a previously-approved creative. CampaignDataDelivery: description: >- Resolved data-delivery configuration for this campaign. Groups standing Data Delivery Outputs (with advertiser/campaign-scoped overrides applied). Distinct from media-buy reporting fields elsewhere in the API. type: object properties: outputs: description: >- Resolved Data Delivery Outputs for this campaign. Campaign-scoped Outputs override advertiser-scoped Outputs by `dataDeliveryType`. Each entry is tagged with `source` ("advertiser" or "campaign"). type: array items: $ref: '#/components/schemas/DataDeliveryOutput' additionalProperties: false FrequencyCapConfig: type: object properties: max_impressions: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Maximum number of impressions allowed within the window example: 3 window: $ref: '#/components/schemas/FrequencyCapWindow' id: type: string description: Unique identifier for the frequency cap config example: '12345' targetLevel: description: Level of the entity the cap applies to allOf: - $ref: '#/components/schemas/FrequencyCapTargetLevel' targetId: type: string description: >- Identifier of the entity at the chosen target level: advertiser_id when targetLevel is ADVERTISER, campaign_id when CAMPAIGN, creative_id when CREATIVE. example: camp_abc123 createdAt: type: string description: ISO 8601 creation timestamp updatedAt: type: string description: ISO 8601 last-updated timestamp archivedAt: description: ISO 8601 archive timestamp; null for active configs nullable: true type: string required: - max_impressions - window - id - targetLevel - targetId - createdAt - updatedAt additionalProperties: {} description: Buyer-side frequency cap configuration OptimizationGoal: oneOf: - $ref: '#/components/schemas/EventGoal' - $ref: '#/components/schemas/MetricGoal' description: >- A single optimization target. Either kind "event" (conversion events) or kind "metric" (seller-native delivery metric). type: object discriminator: propertyName: kind mapping: event: $ref: '#/components/schemas/EventGoal' metric: $ref: '#/components/schemas/MetricGoal' DataDeliveryOutputInput: type: object properties: dataDeliveryType: type: string enum: - MB_DELIVERY - IMPRESSIONS - CLICKS - VAST_EVENTS - CAPI_ATTRIBUTION - MMP_POSTBACKS description: The kind of LLD shipped by this Output. cadence: type: string enum: - HOURLY - DAILY - WEEKLY description: >- Firing rate. HOURLY fires at minute 0 every hour, DAILY at 00:00 UTC, WEEKLY at 00:00 UTC on syncWeeklyDay. syncWeeklyDay: description: >- Day of week for WEEKLY cadence (0=Sunday..6=Saturday). Required when cadence=WEEKLY, ignored otherwise. type: integer minimum: 0 maximum: 6 enabled: default: true description: >- When false, the Temporal schedule is paused — no new runs fire, in-flight runs continue. Defaults to true. type: boolean credentialName: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ description: >- Name of the Data Delivery Credential (within the same advertiser) that authenticates this Output. The credential carries the auth target (e.g., GCS bucket) and is Probe-validated. Must reference a credential whose destinationType matches deliveryConfig.type. deliveryConfig: $ref: '#/components/schemas/DeliveryConfig' required: - dataDeliveryType - cadence - credentialName - deliveryConfig description: >- A single Data Delivery Output entry. Used inline on advertiser/campaign create+update. FrequencyCapWindow: type: object properties: interval: type: integer minimum: 1 maximum: 9007199254740991 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} description: >- Rolling time window over which max_impressions applies (AdCP Duration shape). ConnectedAccountDirectedCampaignInfo: type: object properties: provenance: type: string enum: - connected_account description: >- This directed campaign is mirrored from or authored through a connected provider account. connectionId: type: string minLength: 1 description: >- The subscribed provider connection this directed campaign is mirrored from. example: conn_abc123 accountId: type: string minLength: 1 description: The connection's upstream account id. example: act_998877 provider: type: string minLength: 1 description: >- Adapter/provider key the connection resolves to, e.g. "tiktok", "pinterest", "talpa". example: tiktok storefrontId: description: >- Storefront DB id backing this connection, when the provider is modeled as an AdCP storefront. example: 42 type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 upstreamMediaBuyId: type: string minLength: 1 description: >- The seller's own identifier for the mirrored media buy/campaign — dual-keyed alongside our internal mediaBuyId, per the parity rule (a directed campaign IS a media buy). example: tt_campaign_44521 mediaBuyId: description: >- Our internal media buy id correlating to the upstream object, once the mirror row exists. type: string subscribed: type: boolean description: >- Whether the connected provider account is actively subscribed for periodic metadata mirroring. Alpha usage is dark-metered and not billed. mirrorState: type: string enum: - live - stale - error description: >- live = mirror is current; stale = last sync failed or is overdue; error = the provider reported an error. lastSyncedAt: description: >- When the mirror was last refreshed from the upstream platform (ISO 8601). type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - provenance - connectionId - accountId - provider - upstreamMediaBuyId - subscribed - mirrorState additionalProperties: false description: >- Subscription-backed directed campaign mirror state — connection, upstream account, dual-keyed identifiers, and sync health. StorefrontEndpointDirectedCampaignInfo: type: object properties: provenance: type: string enum: - storefront_endpoint description: >- This directed campaign was created by an external AdCP buyer addressing one storefront endpoint. storefrontId: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Storefront DB id that owns execution for this campaign. example: 42 buyerMediaBuyId: type: string minLength: 1 description: >- AdCP media-buy id used by the external buyer at the storefront boundary. example: buyer_mb_44521 mediaBuyId: description: >- Interchange media-buy id used by the campaign, contract, reporting, and ledger layers. Omitted only for legacy endpoint shells created before this projection was recorded. example: mb_ETBn4gJ9Wu type: string minLength: 1 required: - provenance - storefrontId - buyerMediaBuyId additionalProperties: false description: >- Provenance and dual-key identity for a direct buy through one storefront AdCP endpoint. MediaBuyRefPendingChange: description: >- Present when this buy has a submitted change that has not yet reached the delivering buy. Call `get_media_buy` for the field-level differences; this reference stays lightweight by design. type: object properties: status: type: string description: Lifecycle status of the queued change, typically PENDING_APPROVAL. example: PENDING_APPROVAL pendingAt: description: Which layer the queued change is parked at. type: string enum: - storefront - salesagent - unknown required: - status additionalProperties: false OptimizationGoalOutput: oneOf: - $ref: '#/components/schemas/EventGoalOutput' - $ref: '#/components/schemas/MetricGoalOutput' description: >- A single optimization target. Either kind "event" (conversion events) or kind "metric" (seller-native delivery metric). type: object discriminator: propertyName: kind mapping: event: $ref: '#/components/schemas/EventGoalOutput' metric: $ref: '#/components/schemas/MetricGoalOutput' DataDeliveryOutput: type: object properties: outputConfigId: type: string description: Database identifier for the underlying output config row. dataDeliveryType: type: string enum: - MB_DELIVERY - IMPRESSIONS - CLICKS - VAST_EVENTS - CAPI_ATTRIBUTION - MMP_POSTBACKS cadence: type: string enum: - HOURLY - DAILY - WEEKLY syncWeeklyDay: type: integer minimum: 0 maximum: 6 enabled: type: boolean credentialId: type: string description: >- Database identifier of the Data Delivery Credential authenticating this Output. credentialName: type: string description: >- Name of the Data Delivery Credential authenticating this Output (advertiser-scoped, unique among live credentials). deliveryConfig: $ref: '#/components/schemas/DeliveryConfigOutput' source: type: string enum: - advertiser - campaign description: >- Where this Output was configured — "advertiser" for default, "campaign" for an override. createdAt: type: string updatedAt: type: string required: - outputConfigId - dataDeliveryType - cadence - enabled - credentialId - credentialName - deliveryConfig - source - createdAt - updatedAt additionalProperties: false description: Resolved Data Delivery Output as returned by the API. FrequencyCapTargetLevel: type: string enum: - ADVERTISER - CAMPAIGN - CREATIVE description: Level of the entity the frequency cap applies to EventGoal: type: object properties: kind: type: string enum: - event description: Goal kind. eventSources: minItems: 1 maxItems: 10 type: array items: type: object properties: eventSourceId: type: string minLength: 1 description: >- Event source to include (must be configured via sync_event_sources) example: website_pixel eventType: type: string enum: - page_view - view_content - select_content - select_item - search - share - add_to_cart - remove_from_cart - viewed_cart - add_to_wishlist - initiate_checkout - add_payment_info - purchase - refund - lead - qualify_lead - close_convert_lead - disqualify_lead - complete_registration - subscribe - follow - content_view - watch_milestone - start_trial - app_install - app_launch - contact - schedule - donate - submit_application - custom description: IAB ECAPI event type to optimize for customEventName: description: >- Required when eventType is 'custom'. Platform-specific custom event name. type: string valueField: description: >- Field on custom_data carrying the monetary value. Required when target is 'per_ad_spend'. example: value type: string valueFactor: description: >- Multiplier for valueField (default 1). Use -1 for refunds, 0.01 for cents. example: 1 type: number required: - eventSourceId - eventType additionalProperties: false description: >- Event source and type pairs feeding this goal. Seller deduplicates by event_id across entries. target: description: >- Target cost or return. When omitted, the seller maximizes conversions within budget. oneOf: - type: object properties: kind: type: string enum: - cost_per description: Target kind. value: type: number minimum: 0 exclusiveMinimum: true description: Target cost per unit in buy currency example: 25 required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - per_ad_spend description: Target kind. value: type: number minimum: 0 exclusiveMinimum: true description: Target return ratio (e.g. 4.0 = $4 of value per $1 spent) example: 4 required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - maximize_value description: Target kind. required: - kind additionalProperties: false type: object attributionWindow: description: >- Attribution window for this goal. When omitted, the seller uses their default. allOf: - $ref: '#/components/schemas/OptimizationAttributionWindow' priority: description: >- Priority among goals on this package. 1 = highest. When omitted, sellers use array position. example: 1 type: integer minimum: 1 maximum: 9007199254740991 required: - kind - eventSources additionalProperties: false description: Optimize for advertiser-tracked conversion events via event sources. MetricGoal: type: object properties: kind: type: string enum: - metric description: Goal kind. metric: type: string enum: - clicks - views - completed_views - viewed_seconds - attention_seconds - attention_score - engagements - follows - saves - profile_visits - reach description: >- Metric name. Includes viewed_seconds, attention_seconds, attention_score, reach. See enum. viewDurationSeconds: description: Min video seconds for completed_views metric. type: number minimum: 0 exclusiveMinimum: true target: description: >- Target for this metric. When omitted, the seller maximizes metric volume within budget. oneOf: - type: object properties: kind: type: string enum: - cost_per description: Target kind. value: type: number minimum: 0 exclusiveMinimum: true description: Target cost per unit in buy currency example: 25 required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - threshold_rate description: Target kind. value: type: number minimum: 0 exclusiveMinimum: true description: >- Min per-impression threshold. Proportion, seconds, or score depending on metric. example: 0.001 required: - kind - value additionalProperties: false type: object attributionWindow: description: >- Attribution window for this goal. When omitted, the seller uses their default. allOf: - $ref: '#/components/schemas/OptimizationAttributionWindow' priority: description: >- Priority among goals on this package. 1 = highest. When omitted, sellers use array position. example: 2 type: integer minimum: 1 maximum: 9007199254740991 required: - kind - metric additionalProperties: false description: Optimize for a seller-tracked delivery metric. No event source required. DeliveryConfig: oneOf: - $ref: '#/components/schemas/GcsDeliveryConfig' - $ref: '#/components/schemas/S3DeliveryConfig' - $ref: '#/components/schemas/AzureBlobDeliveryConfig' description: >- Per-Output destination shape (non-secret). Additional destination types are added as new variants in this discriminated union. type: object discriminator: propertyName: type mapping: GCS: $ref: '#/components/schemas/GcsDeliveryConfig' S3: $ref: '#/components/schemas/S3DeliveryConfig' AZURE_BLOB: $ref: '#/components/schemas/AzureBlobDeliveryConfig' EventGoalOutput: type: object properties: kind: type: string enum: - event description: Goal kind. eventSources: minItems: 1 maxItems: 10 type: array items: type: object properties: eventSourceId: type: string minLength: 1 description: >- Event source to include (must be configured via sync_event_sources) example: website_pixel eventType: type: string enum: - page_view - view_content - select_content - select_item - search - share - add_to_cart - remove_from_cart - viewed_cart - add_to_wishlist - initiate_checkout - add_payment_info - purchase - refund - lead - qualify_lead - close_convert_lead - disqualify_lead - complete_registration - subscribe - follow - content_view - watch_milestone - start_trial - app_install - app_launch - contact - schedule - donate - submit_application - custom description: IAB ECAPI event type to optimize for customEventName: description: >- Required when eventType is 'custom'. Platform-specific custom event name. type: string valueField: description: >- Field on custom_data carrying the monetary value. Required when target is 'per_ad_spend'. example: value type: string valueFactor: description: >- Multiplier for valueField (default 1). Use -1 for refunds, 0.01 for cents. example: 1 type: number required: - eventSourceId - eventType additionalProperties: false description: >- Event source and type pairs feeding this goal. Seller deduplicates by event_id across entries. target: description: >- Target cost or return. When omitted, the seller maximizes conversions within budget. oneOf: - type: object properties: kind: type: string enum: - cost_per description: Target kind. value: type: number minimum: 0 exclusiveMinimum: true description: Target cost per unit in buy currency example: 25 required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - per_ad_spend description: Target kind. value: type: number minimum: 0 exclusiveMinimum: true description: Target return ratio (e.g. 4.0 = $4 of value per $1 spent) example: 4 required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - maximize_value description: Target kind. required: - kind additionalProperties: false type: object attributionWindow: description: >- Attribution window for this goal. When omitted, the seller uses their default. allOf: - $ref: '#/components/schemas/OptimizationAttributionWindowOutput' priority: description: >- Priority among goals on this package. 1 = highest. When omitted, sellers use array position. example: 1 type: integer minimum: 1 maximum: 9007199254740991 required: - kind - eventSources additionalProperties: false description: Optimize for advertiser-tracked conversion events via event sources. MetricGoalOutput: type: object properties: kind: type: string enum: - metric description: Goal kind. metric: type: string enum: - clicks - views - completed_views - viewed_seconds - attention_seconds - attention_score - engagements - follows - saves - profile_visits - reach description: >- Metric name. Includes viewed_seconds, attention_seconds, attention_score, reach. See enum. viewDurationSeconds: description: Min video seconds for completed_views metric. type: number minimum: 0 exclusiveMinimum: true target: description: >- Target for this metric. When omitted, the seller maximizes metric volume within budget. oneOf: - type: object properties: kind: type: string enum: - cost_per description: Target kind. value: type: number minimum: 0 exclusiveMinimum: true description: Target cost per unit in buy currency example: 25 required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - threshold_rate description: Target kind. value: type: number minimum: 0 exclusiveMinimum: true description: >- Min per-impression threshold. Proportion, seconds, or score depending on metric. example: 0.001 required: - kind - value additionalProperties: false type: object attributionWindow: description: >- Attribution window for this goal. When omitted, the seller uses their default. allOf: - $ref: '#/components/schemas/OptimizationAttributionWindowOutput' priority: description: >- Priority among goals on this package. 1 = highest. When omitted, sellers use array position. example: 2 type: integer minimum: 1 maximum: 9007199254740991 required: - kind - metric additionalProperties: false description: Optimize for a seller-tracked delivery metric. No event source required. DeliveryConfigOutput: oneOf: - $ref: '#/components/schemas/GcsDeliveryConfigOutput' - $ref: '#/components/schemas/S3DeliveryConfigOutput' - $ref: '#/components/schemas/AzureBlobDeliveryConfigOutput' description: >- Per-Output destination shape (non-secret). Additional destination types are added as new variants in this discriminated union. type: object discriminator: propertyName: type mapping: GCS: $ref: '#/components/schemas/GcsDeliveryConfigOutput' S3: $ref: '#/components/schemas/S3DeliveryConfigOutput' AZURE_BLOB: $ref: '#/components/schemas/AzureBlobDeliveryConfigOutput' OptimizationAttributionWindow: type: object properties: postClick: description: Click-through attribution window example: interval: 7 unit: days allOf: - $ref: '#/components/schemas/Duration' postView: description: View-through attribution window example: interval: 1 unit: days allOf: - $ref: '#/components/schemas/Duration' required: - postClick additionalProperties: false description: Attribution window for conversion optimization GcsDeliveryConfig: type: object properties: type: type: string enum: - GCS pathPrefix: default: '' description: >- Object key prefix within the credential's bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type S3DeliveryConfig: type: object properties: type: type: string enum: - S3 pathPrefix: default: '' description: >- Object key prefix within the credential's S3 bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type AzureBlobDeliveryConfig: type: object properties: type: type: string enum: - AZURE_BLOB pathPrefix: default: '' description: >- Blob name prefix within the credential's Azure container. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type OptimizationAttributionWindowOutput: type: object properties: postClick: description: Click-through attribution window example: interval: 7 unit: days allOf: - $ref: '#/components/schemas/DurationOutput' postView: description: View-through attribution window example: interval: 1 unit: days allOf: - $ref: '#/components/schemas/DurationOutput' required: - postClick additionalProperties: false description: Attribution window for conversion optimization GcsDeliveryConfigOutput: type: object properties: type: type: string enum: - GCS pathPrefix: default: '' description: >- Object key prefix within the credential's bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type - pathPrefix - format additionalProperties: false S3DeliveryConfigOutput: type: object properties: type: type: string enum: - S3 pathPrefix: default: '' description: >- Object key prefix within the credential's S3 bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type - pathPrefix - format additionalProperties: false AzureBlobDeliveryConfigOutput: type: object properties: type: type: string enum: - AZURE_BLOB pathPrefix: default: '' description: >- Blob name prefix within the credential's Azure container. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type - pathPrefix - format additionalProperties: false Duration: type: object properties: interval: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Interval count. unit: type: string enum: - minutes - hours - days - campaign description: Interval unit. required: - interval - unit description: A duration expressed as an interval and unit DurationOutput: type: object properties: interval: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Interval count. unit: type: string enum: - minutes - hours - days - campaign description: Interval unit. required: - interval - unit additionalProperties: false description: A duration expressed as an interval and unit securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````