> ## 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. # Create advertiser > Create a new advertiser. Advertisers are the top-level entity for campaigns. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml post /advertisers 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: /advertisers: post: tags: - Advertisers summary: Create advertiser description: >- Create a new advertiser. Advertisers are the top-level entity for campaigns. operationId: createAdvertiser parameters: - in: header name: Idempotency-Key schema: type: string minLength: 16 maxLength: 255 pattern: ^[A-Za-z0-9_.:-]+$ description: >- Optional replay key. Reusing the same key and validated request within 24 hours returns the original advertiser; changing the request under the same key returns a conflict. example: advertiser-create-20260821-001 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAdvertiserBody' responses: '201': description: Create advertiser content: application/json: schema: $ref: '#/components/schemas/Advertiser' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- Idempotency key conflict, expiry, or an equivalent request still in flight 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: CreateAdvertiserBody: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Name of the advertiser example: Acme Corp description: description: Optional description of the advertiser example: Global advertising account for Acme Corporation type: string maxLength: 1000 brand: type: string minLength: 1 description: >- Brand domain (e.g., "nike.com") or brand website URL. Brand identity is resolved from /.well-known/brand.json, the AdCP registry, or Brandfetch enrichment. example: nike.com saveBrand: default: false description: >- When true, auto-saves the resolved brand identity to the AdCP registry if the brand is not yet registered. Normally not required for advertiser creation when enrichment succeeds; set this only after reviewing enrichment or when the user confirms registry persistence is desired. type: boolean linkedAccounts: description: >- Accounts to link to this advertiser at creation time. Each entry references a discovered account from a partner. type: array items: $ref: '#/components/schemas/LinkedAccountInput' optimizationApplyMode: description: >- Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser. When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval. Defaults to "MANUAL". allOf: - $ref: '#/components/schemas/OptimizationApplyMode' primaryCurrency: description: >- ISO 4217 currency for this advertiser. Required and fixed at creation. Every campaign under this advertiser is created in this currency, and media-buy product pricing must match it. example: USD type: string minLength: 3 maxLength: 3 pattern: ^[A-Za-z]{3}$ brandCountries: description: >- Canonical ISO 3166-1 alpha-2 countries that qualify this advertiser's AdCP BrandKey scope (for example, Nike Italy uses IT). Empty means no country qualifier. Campaigns may inherit this market scope and refine it with delivery targeting. maxItems: 249 type: array items: type: string preferredTimezone: default: UTC type: string minLength: 1 maxLength: 64 description: >- Preferred IANA timezone for seller account calendar and reporting boundaries. Each seller may use a different fixed or assigned timezone. example: Europe/Amsterdam channels: default: [] maxItems: 25 type: array items: anyOf: - type: string enum: - display - type: string enum: - olv - type: string enum: - social - type: string enum: - search - type: string enum: - ctv - type: string enum: - linear_tv - type: string enum: - radio - type: string enum: - streaming_audio - type: string enum: - podcast - type: string enum: - dooh - type: string enum: - ooh - type: string enum: - print - type: string enum: - cinema - type: string enum: - email - type: string enum: - gaming - type: string enum: - retail_media - type: string enum: - influencer - type: string enum: - affiliate - type: string enum: - product_placement - type: string enum: - sponsored_intelligence description: >- AdCP media channels this advertiser expects to use. These are editable planning preferences, not seller qualification or proof that supply is available. sandbox: default: false description: >- When true, this advertiser operates in sandbox mode. All ADCP operations will use sandbox-flagged accounts — no real platform calls, no real spend. Cannot be changed after creation. type: boolean utmConfig: description: >- Default UTM (Urchin Tracking Module) parameters for this advertiser. These are appended to landing page URLs during clickthrough redirection. Campaign-level UTM config can override these per param key. maxItems: 20 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 dataDelivery: $ref: '#/components/schemas/AdvertiserDataDeliveryInput' frequencyCaps: description: >- Buyer-side frequency cap configs to apply to this advertiser. Enforced by Scope3 across all publishers; distinct from publisher-side caps in package target_overlay. type: array items: $ref: '#/components/schemas/FrequencyCapConfigInput' required: - name - brand - primaryCurrency description: Request body for creating a new advertiser Advertiser: type: object properties: id: type: string description: Unique identifier for the advertiser example: '12345' name: type: string description: Name of the advertiser example: Acme Corp description: description: Description of the advertiser example: Global advertising account for Acme Corporation type: string status: type: string enum: - ACTIVE - ARCHIVED description: Current status of the advertiser 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 advertiser 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 advertiser was last updated (ISO 8601) example: '2025-01-20T14:45:00Z' linkedBrand: description: >- The brand linked to this advertiser. Only present when includeBrand=true is passed to the list endpoint. type: object properties: id: type: string description: Brand ID example: brand_123 name: type: string description: Brand name example: Acme Brand domain: type: string description: Brand domain example: acme.com manifest: description: >- Full resolved brand identity data — includes logos, colors, fonts, tone, tagline, assets, product catalog, disclaimers, and more allOf: - $ref: '#/components/schemas/BrandManifestJson' logoUrl: description: Primary brand logo URL example: https://acme.com/logo.png type: string industry: description: Brand industry example: Technology type: string colors: description: Brand color palette example: primary: '#FF5733' type: object additionalProperties: type: string tagline: description: Brand tagline example: Innovation for Everyone type: string tone: description: Brand voice and tone example: Professional, friendly, and innovative type: string required: - id - name - domain - manifest additionalProperties: false brand: description: The brand domain associated with this advertiser example: nike.com type: string brandCountries: type: array items: type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW description: >- Canonical country qualifiers for this advertiser's BrandKey scope. Empty means no country qualifier when brandCountriesKnown is true. Campaigns may inherit this market scope and refine it with delivery targeting. brandCountriesKnown: type: boolean description: >- False only for a legacy advertiser whose BrandKey country scope has not been classified. When false, an empty brandCountries array means unknown rather than a confirmed global scope. brandWarning: description: Warning about brand resolution (e.g., manifest not found) type: string sandbox: type: boolean description: >- When true, this advertiser is in sandbox mode. All ADCP operations use sandbox-flagged accounts. Cannot be changed after creation. optimizationApplyMode: description: >- Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser. When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval. allOf: - $ref: '#/components/schemas/OptimizationApplyMode' primaryCurrency: type: string minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ description: >- ISO 4217 currency for this advertiser. Every campaign under this advertiser is created in this currency, and selected product pricing must match it. example: USD preferredTimezone: nullable: true description: >- Preferred IANA timezone. A connected seller may use a different fixed or assigned timezone. example: Europe/Amsterdam type: string currencyLocked: type: boolean description: >- True once the advertiser has at least one campaign or seller-account binding. Direct v2 API clients may change currency only while this is false; the canonical UI keeps Currency read-only after creation. reportingTimezoneLocked: type: boolean description: >- True once the advertiser has at least one campaign or linked seller account. While false, the reporting time-zone preference can still be changed. channels: type: array items: anyOf: - type: string enum: - display - type: string enum: - olv - type: string enum: - social - type: string enum: - search - type: string enum: - ctv - type: string enum: - linear_tv - type: string enum: - radio - type: string enum: - streaming_audio - type: string enum: - podcast - type: string enum: - dooh - type: string enum: - ooh - type: string enum: - print - type: string enum: - cinema - type: string enum: - email - type: string enum: - gaming - type: string enum: - retail_media - type: string enum: - influencer - type: string enum: - affiliate - type: string enum: - product_placement - type: string enum: - sponsored_intelligence description: >- Editable AdCP media-channel preferences for this advertiser. These do not represent seller qualification or guaranteed supply. linkedAccounts: description: >- Linked partner accounts for this advertiser. Only present when includeAccounts=true is passed to the list endpoint. type: array items: $ref: '#/components/schemas/LinkedAccount' utmConfig: description: >- Advertiser-level UTM parameter configuration. Only present when UTM params are configured for this advertiser. 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 dataDelivery: $ref: '#/components/schemas/AdvertiserDataDelivery' frequencyCaps: description: >- Buyer-side frequency cap configs for this advertiser. Always present on single-GET; on LIST only when includeFrequencyCaps=true. type: array items: $ref: '#/components/schemas/FrequencyCapConfig' required: - id - name - status - createdAt - updatedAt - brandCountries - brandCountriesKnown - sandbox - optimizationApplyMode - primaryCurrency - preferredTimezone - currencyLocked - reportingTimezoneLocked - channels additionalProperties: false description: Advertiser resource representation 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 LinkedAccountInput: type: object properties: storefrontId: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: >- Storefront the source lives on. Pair with `sourceId` to identify the source whose account is being linked. example: 42 sourceId: type: string minLength: 1 description: >- Inventory source within `storefrontId` whose account is being linked. example: src_main accountId: type: string minLength: 1 description: >- Account ID at the source to link to this advertiser. Must come from `list_available_accounts`. example: acc_123 credentialId: description: >- Credential ID returned by `list_available_accounts`. Include it when multiple mapped connections expose the same account ID. example: '42' type: string billingType: description: Billing arrangement type (e.g. "advertiser", "operator", "agent") example: advertiser type: string required: - storefrontId - sourceId - accountId description: An account to link to the advertiser OptimizationApplyMode: type: string enum: - AUTO - MANUAL description: >- Whether optimization suggestions are automatically applied or require human approval. AdvertiserDataDeliveryInput: description: >- Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs and the credentials they reference. Distinct from media-buy reporting fields elsewhere in the API. type: object properties: credentials: description: >- Data Delivery Credentials owned by this advertiser. Replaces all existing live credentials when provided. Pass an empty array to archive every live credential (only allowed when no live Output references one). Applied before `outputs` so newly created credentials can be referenced by name. allOf: - $ref: '#/components/schemas/DataDeliveryCredentialArrayInput' outputs: description: >- Standing log-level data subscriptions to ship from Scope3 to a buyer-owned destination. Replaces all existing advertiser-scoped Data Delivery Outputs when provided. Pass an empty array to clear. allOf: - $ref: '#/components/schemas/DataDeliveryOutputArrayInput' 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. BrandManifestJson: type: object properties: name: type: string minLength: 1 maxLength: 500 description: Brand name (required) example: Acme Corporation url: description: Brand website URL example: https://www.acme.com type: string format: uri logos: description: Brand logos type: array items: type: object properties: url: type: string format: uri description: URL to the logo image tags: description: Tags categorizing the logo (e.g., "primary", "dark", "square") type: array items: type: string background: description: >- Backdrop the logo is designed for (dark-bg for a light or knockout logo, light-bg for a dark logo, transparent-bg for a logo with no baked-in background). type: string enum: - dark-bg - light-bg - transparent-bg width: description: Width of the logo in pixels type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 height: description: Height of the logo in pixels type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - url additionalProperties: {} colors: description: Brand color palette type: object properties: primary: description: Primary brand color in hex format example: '#FF5733' type: string pattern: ^#[0-9A-Fa-f]{6}$ secondary: description: Secondary brand color in hex format type: string pattern: ^#[0-9A-Fa-f]{6}$ accent: description: Accent brand color in hex format type: string pattern: ^#[0-9A-Fa-f]{6}$ background: description: Background color in hex format type: string pattern: ^#[0-9A-Fa-f]{6}$ text: description: Text color in hex format type: string pattern: ^#[0-9A-Fa-f]{6}$ additionalProperties: {} fonts: description: Brand typography anyOf: - type: object properties: primary: description: Primary font family name example: Roboto type: string secondary: description: Secondary font family name type: string fontUrls: description: URLs to font files type: array items: type: string format: uri additionalProperties: {} - type: array items: type: object properties: name: type: string role: type: string required: - name additionalProperties: {} description: Font list from enrichment sources (Brandfetch format) tone: description: Brand voice and tone description example: Professional, friendly, and innovative type: string maxLength: 2000 tagline: description: Brand tagline or slogan example: Innovation for Everyone type: string maxLength: 500 assets: description: Brand assets (images, videos, etc.) type: array items: type: object properties: assetId: type: string description: Unique identifier for the asset assetType: type: string description: Type of asset (e.g., "image", "video", "audio") url: type: string format: uri description: URL to the asset name: description: Human-readable name for the asset type: string description: description: Description of the asset type: string tags: description: Tags categorizing the asset type: array items: type: string width: description: Width in pixels (for images/videos) type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 height: description: Height in pixels (for images/videos) type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 durationSeconds: description: Duration in seconds (for audio/video) type: number minimum: 0 exclusiveMinimum: true fileSizeBytes: description: File size in bytes type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 format: description: File format (e.g., "png", "mp4") type: string metadata: description: Additional metadata type: object additionalProperties: {} required: - assetId - assetType - url additionalProperties: {} productCatalog: description: Product catalog configuration type: object properties: feedUrl: type: string format: uri description: URL to the product feed feedFormat: description: Format of the product feed type: string enum: - google_merchant_center - facebook_catalog - custom categories: description: Product categories type: array items: type: string lastUpdated: description: When the catalog was last updated (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))$ updateFrequency: description: How often the catalog is updated type: string enum: - realtime - hourly - daily - weekly required: - feedUrl additionalProperties: {} disclaimers: description: Legal disclaimers and required text type: array items: type: object properties: text: type: string description: Disclaimer text context: description: Context in which the disclaimer applies type: string required: default: true description: Whether the disclaimer is required type: boolean required: - text - required additionalProperties: {} industry: description: Industry or sector example: Technology type: string maxLength: 255 advertiserIndustry: description: >- Canonical AdCP advertiser-industry code (normalized from the free-text industry). Drives category-based starter briefs and cross-platform interop. example: food_beverage.restaurants type: string enum: - automotive - automotive.electric_vehicles - automotive.parts_accessories - automotive.luxury - beauty_cosmetics - beauty_cosmetics.skincare - beauty_cosmetics.fragrance - beauty_cosmetics.haircare - cannabis - cpg - cpg.personal_care - cpg.household - dating - education - education.higher_education - education.online_learning - education.k12 - energy_utilities - energy_utilities.renewable - fashion_apparel - fashion_apparel.luxury - fashion_apparel.sportswear - finance - finance.banking - finance.insurance - finance.investment - finance.cryptocurrency - food_beverage - food_beverage.alcohol - food_beverage.restaurants - food_beverage.packaged_goods - gambling_betting - gambling_betting.sports_betting - gambling_betting.casino - gaming - gaming.mobile - gaming.console_pc - gaming.esports - government_nonprofit - government_nonprofit.political - government_nonprofit.charity - healthcare - healthcare.pharmaceutical - healthcare.medical_devices - healthcare.wellness - home_garden - home_garden.furniture - home_garden.home_improvement - media_entertainment - media_entertainment.podcasts - media_entertainment.music - media_entertainment.film_tv - media_entertainment.publishing - media_entertainment.live_events - pets - professional_services - professional_services.legal - professional_services.consulting - real_estate - real_estate.residential - real_estate.commercial - recruitment_hr - retail - retail.ecommerce - retail.department_stores - sports_fitness - sports_fitness.equipment - sports_fitness.teams_leagues - technology - technology.software - technology.hardware - technology.ai_ml - telecom - telecom.mobile_carriers - telecom.internet_providers - transportation_logistics - travel_hospitality - travel_hospitality.airlines - travel_hospitality.hotels - travel_hospitality.cruise - travel_hospitality.tourism targetAudience: description: Target audience description example: Small business owners aged 25-45 type: string maxLength: 1000 contact: description: Contact information type: object properties: email: description: Contact email address 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,}$ phone: description: Contact phone number type: string website: description: Contact website URL type: string format: uri additionalProperties: {} metadata: description: Manifest metadata type: object properties: createdDate: description: When the manifest was created (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))$ updatedDate: description: When the manifest was last updated (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))$ version: description: Version of the manifest example: 1.0.0 type: string additionalProperties: {} required: - name additionalProperties: {} description: Full brand.json profile conforming to the ADCP v2 schema LinkedAccount: type: object properties: linkId: type: string description: Unique link identifier accountId: type: string description: Account identifier on the partner platform credentialId: description: >- Credential row that owns this linked account. Include this value when updating linked accounts so duplicate account IDs across mapped connections remain unambiguous. example: '42' nullable: true type: string name: nullable: true description: Account name type: string sources: type: array items: $ref: '#/components/schemas/BuyerCredentialSourceRef' description: >- Storefront sources that surface this linked account to the buyer. Empty when the underlying agent is no longer linked to any active storefront source. status: type: string description: Account status 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 linked (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 last updated (ISO 8601) required: - linkId - accountId - name - sources - status - createdAt - updatedAt additionalProperties: false description: A partner account linked to this advertiser AdvertiserDataDelivery: description: >- Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs and the credentials they reference. Distinct from media-buy reporting fields elsewhere in the API. type: object properties: credentials: description: >- Live Data Delivery Credentials owned by this advertiser. Only present when at least one credential exists. type: array items: $ref: '#/components/schemas/DataDeliveryCredential' outputs: description: >- Advertiser-scoped Data Delivery Outputs (standing LLD subscriptions). Only present when at least one Output is configured. 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 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 DataDeliveryCredentialArrayInput: maxItems: 20 type: array items: $ref: '#/components/schemas/DataDeliveryCredentialInput' description: >- Array of Data Delivery Credentials for one advertiser. Names must be unique within the array. 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. 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). BuyerCredentialSourceRef: type: object properties: storefrontId: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Storefront ID this credential covers storefrontName: type: string description: Storefront display name sourceId: type: string description: Inventory source ID within the storefront sourceName: type: string description: Inventory source display name required: - storefrontId - storefrontName - sourceId - sourceName additionalProperties: false description: >- A storefront/source pair that a single credential row gives the buyer access to DataDeliveryCredential: type: object properties: credentialId: type: string description: Database identifier for the credential row. name: type: string destinationType: type: string enum: - GCS - S3 - AZURE_BLOB - SNOWFLAKE - DATABRICKS config: $ref: '#/components/schemas/CredentialConfig' status: type: string enum: - PENDING - VALIDATED - FAILED description: >- Outcome of the most recent Probe. PENDING until the first Probe completes, VALIDATED when the credential is reachable, FAILED when not. Data Delivery Outputs may reference any status; ReportDeliveryWorkflow checks at run time. statusError: description: Human-readable Probe failure reason when status=FAILED. type: string validatedAt: description: ISO timestamp of the most recent successful Probe. type: string expiresAt: description: >- ISO timestamp at which the credential is known to expire. Populated for credential shapes that carry an expiry claim (e.g., the `se=` field of an Azure SAS token). Absent when the destination does not encode an expiry. type: string createdAt: type: string updatedAt: type: string required: - credentialId - name - destinationType - config - status - createdAt - updatedAt additionalProperties: false description: Resolved Data Delivery Credential as returned by the API. 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 DataDeliveryCredentialInput: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ description: >- Buyer-meaningful identifier for this credential, unique per advertiser among live credentials. Data Delivery Outputs reference this by name. config: $ref: '#/components/schemas/CredentialConfigInput' required: - name - config description: >- A single Data Delivery Credential entry. Used inline on advertiser create+update; full-replace by name within one request. 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. CredentialConfig: oneOf: - $ref: '#/components/schemas/GcsCredentialConfigOutput' - $ref: '#/components/schemas/S3CredentialConfigOutput' - $ref: '#/components/schemas/AzureBlobCredentialConfig' description: >- Destination-specific auth target as stored on the credential row. AZURE_BLOB omits the SAS token — the token lives in Google Secret Manager and is fetched at probe / delivery time. type: object discriminator: propertyName: type mapping: GCS: $ref: '#/components/schemas/GcsCredentialConfigOutput' S3: $ref: '#/components/schemas/S3CredentialConfigOutput' AZURE_BLOB: $ref: '#/components/schemas/AzureBlobCredentialConfig' 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' CredentialConfigInput: oneOf: - $ref: '#/components/schemas/GcsCredentialConfig' - $ref: '#/components/schemas/S3CredentialConfig' - $ref: '#/components/schemas/AzureBlobCredentialConfigInput' description: >- Destination-specific auth target as submitted by the buyer. AZURE_BLOB carries the SAS token; the API persists it to Google Secret Manager and stores only a reference. Additional destination types are added as new variants. type: object discriminator: propertyName: type mapping: GCS: $ref: '#/components/schemas/GcsCredentialConfig' S3: $ref: '#/components/schemas/S3CredentialConfig' AZURE_BLOB: $ref: '#/components/schemas/AzureBlobCredentialConfigInput' 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' GcsCredentialConfigOutput: type: object properties: type: type: string enum: - GCS bucket: type: string minLength: 1 maxLength: 222 pattern: ^[a-z0-9][a-z0-9._-]*[a-z0-9]$ description: >- Target GCS bucket the Probe writes to and Data Delivery Outputs ship objects into. The Scope3 service account must have objectCreator on this bucket. required: - type - bucket additionalProperties: false S3CredentialConfigOutput: type: object properties: type: type: string enum: - S3 bucket: type: string minLength: 3 maxLength: 63 pattern: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$ description: >- Target S3 bucket the Probe writes to and Data Delivery Outputs ship objects into. The bucket policy must grant the Scope3 AWS IAM principal s3:PutObject (and s3:DeleteObject for the Probe sweep) on objects under the Output path prefix. region: type: string pattern: ^[a-z]{2}(-[a-z]+)+-\d+$ description: >- AWS region of the target bucket. Supports commercial, GovCloud, and ISO partitions (e.g., us-east-1, us-gov-east-1). required: - type - bucket - region additionalProperties: false AzureBlobCredentialConfig: type: object properties: type: type: string enum: - AZURE_BLOB storageAccountName: type: string minLength: 3 maxLength: 24 pattern: ^[a-z0-9]+$ description: >- Azure Storage account hosting the target container, e.g. `datareports`. The container is accessed at `https://.blob.core.windows.net/`. containerName: type: string minLength: 3 maxLength: 63 pattern: ^(?!.*--)[a-z0-9][a-z0-9-]*[a-z0-9]$ description: >- Azure Blob container that the Probe writes to and Data Delivery Outputs ship objects into. auth: $ref: '#/components/schemas/AzureBlobAuthStored' required: - type - storageAccountName - containerName - auth additionalProperties: false 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 GcsCredentialConfig: type: object properties: type: type: string enum: - GCS bucket: type: string minLength: 1 maxLength: 222 pattern: ^[a-z0-9][a-z0-9._-]*[a-z0-9]$ description: >- Target GCS bucket the Probe writes to and Data Delivery Outputs ship objects into. The Scope3 service account must have objectCreator on this bucket. required: - type - bucket S3CredentialConfig: type: object properties: type: type: string enum: - S3 bucket: type: string minLength: 3 maxLength: 63 pattern: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$ description: >- Target S3 bucket the Probe writes to and Data Delivery Outputs ship objects into. The bucket policy must grant the Scope3 AWS IAM principal s3:PutObject (and s3:DeleteObject for the Probe sweep) on objects under the Output path prefix. region: type: string pattern: ^[a-z]{2}(-[a-z]+)+-\d+$ description: >- AWS region of the target bucket. Supports commercial, GovCloud, and ISO partitions (e.g., us-east-1, us-gov-east-1). required: - type - bucket - region AzureBlobCredentialConfigInput: type: object properties: type: type: string enum: - AZURE_BLOB storageAccountName: type: string minLength: 3 maxLength: 24 pattern: ^[a-z0-9]+$ description: >- Azure Storage account hosting the target container, e.g. `datareports`. The container is accessed at `https://.blob.core.windows.net/`. containerName: type: string minLength: 3 maxLength: 63 pattern: ^(?!.*--)[a-z0-9][a-z0-9-]*[a-z0-9]$ description: >- Azure Blob container that the Probe writes to and Data Delivery Outputs ship objects into. auth: $ref: '#/components/schemas/AzureBlobAuthInput' required: - type - storageAccountName - containerName - auth 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 AzureBlobAuthStored: oneOf: - $ref: '#/components/schemas/AzureBlobSasAuthStored' type: object discriminator: propertyName: mode mapping: SAS_TOKEN: $ref: '#/components/schemas/AzureBlobSasAuthStored' AzureBlobAuthInput: oneOf: - $ref: '#/components/schemas/AzureBlobSasAuthInput' description: >- How Scope3 authenticates to the buyer-owned Azure Blob container. SAS_TOKEN uses a container-scoped Shared Access Signature. type: object discriminator: propertyName: mode mapping: SAS_TOKEN: $ref: '#/components/schemas/AzureBlobSasAuthInput' AzureBlobSasAuthStored: type: object properties: mode: type: string enum: - SAS_TOKEN required: - mode additionalProperties: false AzureBlobSasAuthInput: type: object properties: mode: type: string enum: - SAS_TOKEN sasToken: type: string minLength: 1 maxLength: 4096 description: >- Shared Access Signature (SAS) query string. Provide the part after the `?` from the SAS URL — leading `?` is tolerated. Accepts either a Service SAS scoped to the container (`sr=c`) or an Account SAS with `srt` including `o` (Object); blob-scoped Service SAS (`sr=b`) is not supported because the Probe writes to a randomized path. The SAS must grant Create + Write + Delete (`sp=cwd`). Persisted to Google Secret Manager; the credential row stores only a resource reference. Not returned on subsequent GETs — to rotate, submit a new credential. required: - mode - sasToken securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````