> ## Documentation Index > Fetch the complete documentation index at: https://docs.interchange.io/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 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' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: CreateAdvertiserBody: description: Request body for creating a new advertiser type: object properties: name: description: Name of the advertiser example: Acme Corp type: string minLength: 1 maxLength: 255 description: description: Optional description of the advertiser example: Global advertising account for Acme Corporation type: string maxLength: 1000 brand: 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 type: string minLength: 1 saveBrand: 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. default: false 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: >- Primary ISO 4217 currency for this advertiser. Required. Every campaign under this advertiser is created in this currency, and media-buy product pricing must match it. The currency can be changed (via update_advertiser) only until the advertiser has its first campaign, after which it is locked. example: USD type: string minLength: 3 maxLength: 3 pattern: ^[A-Za-z]{3}$ sandbox: 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. default: false 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: description: >- Output query parameter key appended to landing URL (e.g., "utm_source", "bg_campaign") example: utm_campaign type: string pattern: ^[a-zA-Z0-9_-]{1,100}$ paramValue: description: >- Macro name (e.g., "{CAMPAIGN_ID}") or static string (e.g., "scope3") to resolve as the value example: '{CAMPAIGN_ID}' type: string minLength: 1 maxLength: 200 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 Advertiser: description: Advertiser resource representation type: object properties: id: description: Unique identifier for the advertiser example: '12345' type: string name: description: Name of the advertiser example: Acme Corp type: string description: description: Description of the advertiser example: Global advertising account for Acme Corporation type: string status: description: Current status of the advertiser type: string enum: - ACTIVE - ARCHIVED createdAt: description: When the advertiser was created (ISO 8601) example: '2025-01-15T10:30:00Z' 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))$ updatedAt: description: When the advertiser was last updated (ISO 8601) example: '2025-01-20T14:45:00Z' 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))$ linkedBrand: description: >- The brand linked to this advertiser. Only present when includeBrand=true is passed to the list endpoint. type: object properties: id: description: Brand ID example: brand_123 type: string name: description: Brand name example: Acme Brand type: string domain: description: Brand domain example: acme.com type: string 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 brandWarning: description: Warning about brand resolution (e.g., manifest not found) type: string sandbox: description: >- When true, this advertiser is in sandbox mode. All ADCP operations use sandbox-flagged accounts. Cannot be changed after creation. type: boolean 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: description: >- Primary 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 type: string minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ currencyLocked: description: >- True once the advertiser has at least one campaign. While false, `primaryCurrency` can still be changed; once true it is locked. type: boolean 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: description: Output query parameter key example: utm_campaign type: string paramValue: description: Macro or static value example: '{CAMPAIGN_ID}' type: string source: description: >- Where this param was configured — "advertiser" for advertiser default, "campaign" for campaign override type: string enum: - advertiser - campaign 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 - sandbox - optimizationApplyMode - primaryCurrency - currencyLocked additionalProperties: false ErrorResponse: description: Standard error response type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false LinkedAccountInput: description: An account to link to the advertiser type: object properties: storefrontId: description: >- Storefront the source lives on. Pair with `sourceId` to identify the source whose account is being linked. example: 42 type: integer maximum: 9007199254740991 minimum: 1 sourceId: description: >- Inventory source within `storefrontId` whose account is being linked. example: src_main type: string minLength: 1 accountId: description: >- Account ID at the source to link to this advertiser. Must come from `list_available_accounts`. example: acc_123 type: string minLength: 1 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 OptimizationApplyMode: description: >- Whether optimization suggestions are automatically applied or require human approval. type: string enum: - AUTO - MANUAL 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: 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. type: object properties: max_impressions: description: Maximum number of impressions allowed within the window example: 3 type: integer maximum: 9007199254740991 minimum: 1 window: $ref: '#/components/schemas/FrequencyCapWindow' required: - max_impressions - window additionalProperties: {} BrandManifestJson: description: Full brand.json profile conforming to the ADCP v2 schema type: object properties: name: description: Brand name (required) example: Acme Corporation type: string minLength: 1 maxLength: 500 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: description: URL to the logo image type: string format: uri 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 maximum: 9007199254740991 minimum: 1 height: description: Height of the logo in pixels type: integer maximum: 9007199254740991 minimum: 1 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: {} - description: Font list from enrichment sources (Brandfetch format) type: array items: type: object properties: name: type: string role: type: string required: - name additionalProperties: {} 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: description: Unique identifier for the asset type: string assetType: description: Type of asset (e.g., "image", "video", "audio") type: string url: description: URL to the asset type: string format: uri 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 maximum: 9007199254740991 minimum: 1 height: description: Height in pixels (for images/videos) type: integer maximum: 9007199254740991 minimum: 1 durationSeconds: description: Duration in seconds (for audio/video) type: number minimum: 0 exclusiveMinimum: true fileSizeBytes: description: File size in bytes type: integer maximum: 9007199254740991 minimum: 1 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: description: URL to the product feed type: string format: uri 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: description: Disclaimer text type: string context: description: Context in which the disclaimer applies type: string required: description: Whether the disclaimer is required default: true 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: {} LinkedAccount: description: A partner account linked to this advertiser type: object properties: linkId: description: Unique link identifier type: string accountId: description: Account identifier on the partner platform type: string 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: description: Account name nullable: true type: string sources: 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. type: array items: $ref: '#/components/schemas/BuyerCredentialSourceRef' status: description: Account status type: string createdAt: description: When linked (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))$ updatedAt: description: When 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))$ required: - linkId - accountId - name - sources - status - createdAt - updatedAt additionalProperties: false 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: description: Buyer-side frequency cap configuration type: object properties: max_impressions: description: Maximum number of impressions allowed within the window example: 3 type: integer maximum: 9007199254740991 minimum: 1 window: $ref: '#/components/schemas/FrequencyCapWindow' id: description: Unique identifier for the frequency cap config example: '12345' type: string targetLevel: description: Level of the entity the cap applies to allOf: - $ref: '#/components/schemas/FrequencyCapTargetLevel' targetId: 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 type: string createdAt: description: ISO 8601 creation timestamp type: string updatedAt: description: ISO 8601 last-updated timestamp type: string archivedAt: description: ISO 8601 archive timestamp; null for active configs nullable: true type: string required: - max_impressions - window - id - targetLevel - targetId - createdAt - updatedAt additionalProperties: {} ApiError: description: Structured error object type: object properties: code: description: Machine-readable error code type: string message: description: Human-readable error message type: string field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false DataDeliveryCredentialArrayInput: description: >- Array of Data Delivery Credentials for one advertiser. Names must be unique within the array. maxItems: 20 type: array items: $ref: '#/components/schemas/DataDeliveryCredentialInput' DataDeliveryOutputArrayInput: 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. maxItems: 20 type: array items: $ref: '#/components/schemas/DataDeliveryOutputInput' FrequencyCapWindow: description: >- Rolling time window over which max_impressions applies (AdCP Duration shape). type: object properties: interval: type: number minimum: 1 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: {} BuyerCredentialSourceRef: description: >- A storefront/source pair that a single credential row gives the buyer access to type: object properties: storefrontId: description: Storefront ID this credential covers type: integer minimum: -9007199254740991 maximum: 9007199254740991 storefrontName: description: Storefront display name type: string sourceId: description: Inventory source ID within the storefront type: string sourceName: description: Inventory source display name type: string required: - storefrontId - storefrontName - sourceId - sourceName additionalProperties: false DataDeliveryCredential: description: Resolved Data Delivery Credential as returned by the API. type: object properties: credentialId: description: Database identifier for the credential row. type: string name: type: string destinationType: type: string enum: - GCS - S3 - AZURE_BLOB - SNOWFLAKE - DATABRICKS config: $ref: '#/components/schemas/CredentialConfig' status: 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. type: string enum: - PENDING - VALIDATED - FAILED 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 DataDeliveryOutput: description: Resolved Data Delivery Output as returned by the API. type: object properties: outputConfigId: description: Database identifier for the underlying output config row. type: string 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: description: >- Database identifier of the Data Delivery Credential authenticating this Output. type: string credentialName: description: >- Name of the Data Delivery Credential authenticating this Output (advertiser-scoped, unique among live credentials). type: string deliveryConfig: $ref: '#/components/schemas/DeliveryConfigOutput' source: description: >- Where this Output was configured — "advertiser" for default, "campaign" for an override. type: string enum: - advertiser - campaign createdAt: type: string updatedAt: type: string required: - outputConfigId - dataDeliveryType - cadence - enabled - credentialId - credentialName - deliveryConfig - source - createdAt - updatedAt additionalProperties: false FrequencyCapTargetLevel: description: Level of the entity the frequency cap applies to type: string enum: - ADVERTISER - CAMPAIGN - CREATIVE DataDeliveryCredentialInput: description: >- A single Data Delivery Credential entry. Used inline on advertiser create+update; full-replace by name within one request. type: object properties: name: description: >- Buyer-meaningful identifier for this credential, unique per advertiser among live credentials. Data Delivery Outputs reference this by name. type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ config: $ref: '#/components/schemas/CredentialConfigInput' required: - name - config DataDeliveryOutputInput: description: >- A single Data Delivery Output entry. Used inline on advertiser/campaign create+update. type: object properties: dataDeliveryType: description: The kind of LLD shipped by this Output. type: string enum: - MB_DELIVERY - IMPRESSIONS - CLICKS - VAST_EVENTS - CAPI_ATTRIBUTION - MMP_POSTBACKS cadence: description: >- Firing rate. HOURLY fires at minute 0 every hour, DAILY at 00:00 UTC, WEEKLY at 00:00 UTC on syncWeeklyDay. type: string enum: - HOURLY - DAILY - WEEKLY 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: description: >- When false, the Temporal schedule is paused — no new runs fire, in-flight runs continue. Defaults to true. default: true type: boolean credentialName: 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. type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ deliveryConfig: $ref: '#/components/schemas/DeliveryConfig' required: - dataDeliveryType - cadence - credentialName - deliveryConfig CredentialConfig: 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. oneOf: - $ref: '#/components/schemas/GcsCredentialConfigOutput' - $ref: '#/components/schemas/S3CredentialConfigOutput' - $ref: '#/components/schemas/AzureBlobCredentialConfig' type: object discriminator: propertyName: type mapping: GCS: $ref: '#/components/schemas/GcsCredentialConfigOutput' S3: $ref: '#/components/schemas/S3CredentialConfigOutput' AZURE_BLOB: $ref: '#/components/schemas/AzureBlobCredentialConfig' DeliveryConfigOutput: description: >- Per-Output destination shape (non-secret). Additional destination types are added as new variants in this discriminated union. oneOf: - $ref: '#/components/schemas/GcsDeliveryConfigOutput' - $ref: '#/components/schemas/S3DeliveryConfigOutput' - $ref: '#/components/schemas/AzureBlobDeliveryConfigOutput' type: object discriminator: propertyName: type mapping: GCS: $ref: '#/components/schemas/GcsDeliveryConfigOutput' S3: $ref: '#/components/schemas/S3DeliveryConfigOutput' AZURE_BLOB: $ref: '#/components/schemas/AzureBlobDeliveryConfigOutput' CredentialConfigInput: 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. oneOf: - $ref: '#/components/schemas/GcsCredentialConfig' - $ref: '#/components/schemas/S3CredentialConfig' - $ref: '#/components/schemas/AzureBlobCredentialConfigInput' type: object discriminator: propertyName: type mapping: GCS: $ref: '#/components/schemas/GcsCredentialConfig' S3: $ref: '#/components/schemas/S3CredentialConfig' AZURE_BLOB: $ref: '#/components/schemas/AzureBlobCredentialConfigInput' DeliveryConfig: description: >- Per-Output destination shape (non-secret). Additional destination types are added as new variants in this discriminated union. oneOf: - $ref: '#/components/schemas/GcsDeliveryConfig' - $ref: '#/components/schemas/S3DeliveryConfig' - $ref: '#/components/schemas/AzureBlobDeliveryConfig' 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: 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. type: string minLength: 1 maxLength: 222 pattern: ^[a-z0-9][a-z0-9._-]*[a-z0-9]$ required: - type - bucket additionalProperties: false S3CredentialConfigOutput: type: object properties: type: type: string enum: - S3 bucket: 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. type: string minLength: 3 maxLength: 63 pattern: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$ region: description: >- AWS region of the target bucket. Supports commercial, GovCloud, and ISO partitions (e.g., us-east-1, us-gov-east-1). type: string pattern: ^[a-z]{2}(-[a-z]+)+-\d+$ required: - type - bucket - region additionalProperties: false AzureBlobCredentialConfig: type: object properties: type: type: string enum: - AZURE_BLOB storageAccountName: description: >- Azure Storage account hosting the target container, e.g. `datareports`. The container is accessed at `https://.blob.core.windows.net/`. type: string minLength: 3 maxLength: 24 pattern: ^[a-z0-9]+$ containerName: description: >- Azure Blob container that the Probe writes to and Data Delivery Outputs ship objects into. type: string minLength: 3 maxLength: 63 pattern: ^(?!.*--)[a-z0-9][a-z0-9-]*[a-z0-9]$ auth: $ref: '#/components/schemas/AzureBlobAuthStored' required: - type - storageAccountName - containerName - auth additionalProperties: false GcsDeliveryConfigOutput: type: object properties: type: type: string enum: - GCS pathPrefix: 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. default: '' 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: 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. default: '' 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: 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. default: '' 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: 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. type: string minLength: 1 maxLength: 222 pattern: ^[a-z0-9][a-z0-9._-]*[a-z0-9]$ required: - type - bucket S3CredentialConfig: type: object properties: type: type: string enum: - S3 bucket: 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. type: string minLength: 3 maxLength: 63 pattern: ^[a-z0-9][a-z0-9.-]*[a-z0-9]$ region: description: >- AWS region of the target bucket. Supports commercial, GovCloud, and ISO partitions (e.g., us-east-1, us-gov-east-1). type: string pattern: ^[a-z]{2}(-[a-z]+)+-\d+$ required: - type - bucket - region AzureBlobCredentialConfigInput: type: object properties: type: type: string enum: - AZURE_BLOB storageAccountName: description: >- Azure Storage account hosting the target container, e.g. `datareports`. The container is accessed at `https://.blob.core.windows.net/`. type: string minLength: 3 maxLength: 24 pattern: ^[a-z0-9]+$ containerName: description: >- Azure Blob container that the Probe writes to and Data Delivery Outputs ship objects into. type: string minLength: 3 maxLength: 63 pattern: ^(?!.*--)[a-z0-9][a-z0-9-]*[a-z0-9]$ auth: $ref: '#/components/schemas/AzureBlobAuthInput' required: - type - storageAccountName - containerName - auth GcsDeliveryConfig: type: object properties: type: type: string enum: - GCS pathPrefix: 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. default: '' 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: 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. default: '' 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: 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. default: '' 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: description: >- How Scope3 authenticates to the buyer-owned Azure Blob container. SAS_TOKEN uses a container-scoped Shared Access Signature. oneOf: - $ref: '#/components/schemas/AzureBlobSasAuthInput' 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: 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. type: string minLength: 1 maxLength: 4096 required: - mode - sasToken securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````