> ## 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. # List campaigns > List campaigns with optional filtering by advertiser and status. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml get /campaigns 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: get: tags: - Campaigns summary: List campaigns description: List campaigns with optional filtering by advertiser and status. operationId: listCampaigns parameters: - in: query name: labels schema: description: Internal V3 label predicate. type: string description: Internal V3 label predicate. - in: query name: advertiserId schema: description: Filter by advertiser ID example: '12345' type: string pattern: ^\d+$ description: Filter by advertiser ID - in: query name: name schema: description: Filter by campaign name (case-insensitive, partial match) example: Summer type: string description: Filter by campaign name (case-insensitive, partial match) - in: query name: status schema: description: >- Filter by campaign status. Accepts a single value or repeated values; pass "ALL" to include every status. Defaults to the non-terminal statuses (ACTIVE, DRAFT, PAUSED) — every campaign that could still spend. Completed, canceled, and archived campaigns require an explicit status filter (or "ALL"). example: ACTIVE anyOf: - type: array items: $ref: '#/components/schemas/CampaignStatusListFilter' - allOf: - $ref: '#/components/schemas/CampaignStatusListFilter' description: >- Filter by campaign status. Accepts a single value or repeated values; pass "ALL" to include every status. Defaults to the non-terminal statuses (ACTIVE, DRAFT, PAUSED) — every campaign that could still spend. Completed, canceled, and archived campaigns require an explicit status filter (or "ALL"). - in: query name: mode schema: description: >- Filter by campaign mode. Accepts a single mode (`?mode=directed`) or repeated values (`?mode=discovery&mode=performance`). example: directed anyOf: - type: array items: $ref: '#/components/schemas/CampaignMode' - allOf: - $ref: '#/components/schemas/CampaignMode' description: >- Filter by campaign mode. Accepts a single mode (`?mode=directed`) or repeated values (`?mode=discovery&mode=performance`). - in: query name: management schema: description: >- Filter by management state: "tracked" (campaigns the platform did not set up, mirrored from connected provider accounts), "managed" (campaigns authored or adopted through the platform), or "all" (both — the default). The default status lens (non-terminal: ACTIVE, DRAFT, PAUSED) is what keeps mirrored history out of the ambient list; browse tracked scale through the provider-account relationship rollup. example: managed default: all allOf: - $ref: '#/components/schemas/CampaignManagementFilter' description: >- Filter by management state: "tracked" (campaigns the platform did not set up, mirrored from connected provider accounts), "managed" (campaigns authored or adopted through the platform), or "all" (both — the default). The default status lens (non-terminal: ACTIVE, DRAFT, PAUSED) is what keeps mirrored history out of the ambient list; browse tracked scale through the provider-account relationship rollup. - in: query name: mediaBuyStatus schema: description: >- Filter to only campaigns that have at least one media buy matching any of the given statuses anyOf: - type: array items: type: string enum: - DRAFT - PENDING_APPROVAL - INPUT_REQUIRED - ACTIVE - PAUSED - COMPLETED - CANCELED - FAILED - REJECTED - ARCHIVED - type: string enum: - DRAFT - PENDING_APPROVAL - INPUT_REQUIRED - ACTIVE - PAUSED - COMPLETED - CANCELED - FAILED - REJECTED - ARCHIVED description: >- Filter to only campaigns that have at least one media buy matching any of the given statuses - in: query name: includeArchived schema: description: >- Include archived (soft-deleted) campaigns in the response (default: false). Implicitly treated as true when the status filter contains 'ARCHIVED'. type: string enum: - 'true' - 'false' description: >- Include archived (soft-deleted) campaigns in the response (default: false). Implicitly treated as true when the status filter contains 'ARCHIVED'. - in: query name: archivedOnly schema: description: >- Restrict the response to archived campaigns, including legacy ARCHIVED-status rows. type: boolean description: >- Restrict the response to archived campaigns, including legacy ARCHIVED-status rows. - in: query name: fields schema: description: >- Optional response enrichment fields. Pass geo_metro_names to include display labels for geo_metros from the local label table. example: geo_metro_names anyOf: - type: string - type: array items: type: string description: >- Optional response enrichment fields. Pass geo_metro_names to include display labels for geo_metros from the local label table. - in: query name: cursor schema: description: >- Opaque pagination cursor returned by the previous response. When provided, skip is derived from the cursor and any explicit skip param is ignored. example: eyJza2lwIjoxMH0= type: string description: >- Opaque pagination cursor returned by the previous response. When provided, skip is derived from the cursor and any explicit skip param is ignored. - in: query name: take schema: default: 50 description: Number of results to return (max 250) example: 50 type: integer minimum: 0 exclusiveMinimum: true maximum: 250 description: Number of results to return (max 250) - in: query name: skip schema: default: 0 description: Number of results to skip for pagination example: 0 type: integer minimum: 0 maximum: 9007199254740991 description: Number of results to skip for pagination responses: '200': description: List campaigns content: application/json: schema: $ref: '#/components/schemas/CampaignListResponse' '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: CampaignStatusListFilter: type: string enum: - DRAFT - ACTIVE - PAUSED - COMPLETED - CANCELED - ARCHIVED - ALL description: >- Campaign statuses to include in the list, or "ALL" to include every status. Defaults to the non-terminal statuses (ACTIVE, DRAFT, PAUSED) — every campaign that could still spend. 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). CampaignManagementFilter: type: string enum: - tracked - managed - all description: >- Management states to include in the list: "tracked", "managed", or "all" (both — the default). CampaignListResponse: type: object properties: campaigns: type: array items: $ref: '#/components/schemas/CampaignSummary' description: >- Campaigns matching the query, projected to the summary shape. Use `get_campaign` for full detail. total: type: integer minimum: 0 maximum: 9007199254740991 description: Total count of campaigns matching the query example: 42 items: description: >- V3 projection of campaign list items. Parallel to campaigns[] for backward compatibility. type: array items: type: object properties: campaign: type: object properties: campaignId: type: string name: type: string handling: type: string enum: - tracking - managing phase: type: string enum: - draft - active - completed - canceled isPaused: type: boolean isArchived: type: boolean autonomy: type: object properties: inventorySelection: type: object properties: mode: type: string enum: - manual - propose - automatic source: type: string enum: - inherited - overridden required: - mode - source additionalProperties: false rebriefing: type: object properties: mode: type: string enum: - manual - propose - automatic source: type: string enum: - inherited - overridden required: - mode - source additionalProperties: false required: - inventorySelection - rebriefing additionalProperties: false source: type: object properties: kind: type: string enum: - interchange - connected_account - adcp sellerId: type: string freshness: type: string enum: - live - stale - error lastSyncedAt: type: string required: - kind additionalProperties: false createdAt: type: string updatedAt: type: string required: - campaignId - name - handling - phase - isPaused - isArchived - createdAt - updatedAt additionalProperties: false advertiser: type: object properties: advertiserId: nullable: true type: string name: type: string required: - advertiserId - name additionalProperties: false flight: type: object properties: startAt: type: string endAt: type: string progress: type: number required: - startAt - endAt additionalProperties: false market: type: string financials: type: object properties: budget: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object spend: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object pacing: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: percent: type: number verdict: type: string enum: - behind - on_track - ahead required: - percent - verdict additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: percent: type: number verdict: type: string enum: - behind - on_track - ahead required: - percent - verdict additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object dailyBudget: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object spendToday: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object required: - budget - spend - pacing additionalProperties: false outcome: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: label: type: string actual: type: number target: type: number unit: type: string verdict: type: string enum: - working - off_goal - neutral required: - label - actual - unit - verdict additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: label: type: string actual: type: number target: type: number unit: type: string verdict: type: string enum: - working - off_goal - neutral required: - label - actual - unit - verdict additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object attention: type: array items: type: string enum: - blocked - off_goal - drifted - stale attentionNote: type: string nextAction: type: object properties: action: type: string label: type: string params: type: object additionalProperties: {} required: - action - label additionalProperties: false required: - campaign - advertiser - financials - outcome - attention additionalProperties: false activeCount: description: >- Count of active (not paused/archived) campaigns across the whole query scope, independent of pagination. Present only for the V3 Campaigns experience. example: 23 type: integer minimum: 0 maximum: 9007199254740991 v3Enabled: description: >- Whether the V3 Campaigns experience (enriched list + redesign) is enabled for this caller via the campaigns-v3 flag. The widget renders the V3 redesign only when true. type: boolean nextCursor: description: Opaque cursor for the next page. Absent when there is no next page. type: string hasMore: type: boolean description: Whether there are more campaigns beyond this page. required: - campaigns - total - hasMore additionalProperties: false description: Response containing a paginated list of campaign summaries 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 CampaignSummary: 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' 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 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: {} 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 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' budget: description: >- Compact budget — total + currency only. Use `get_campaign` for the full budget (dailyCap, pacing) plus allocatedBudget, unallocatedBudget. type: object properties: total: type: number minimum: 0 exclusiveMinimum: true currency: default: USD type: string minLength: 3 maxLength: 3 required: - total - currency additionalProperties: false mediaBuyCount: description: >- Number of staged media buys on the campaign: current buys that are not archived and not in a terminal seller verdict (CANCELED, FAILED, REJECTED). Present on list rows so a caller can tell an empty campaign from one with inventory without loading `get_campaign`. type: integer minimum: 0 maximum: 9007199254740991 required: - campaignId - advertiserId - name - status - mode - management - createdAt - updatedAt additionalProperties: false description: >- Compact campaign view returned by list endpoints. Use `get_campaign` for the full resource. 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 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' 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. 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. securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````