> ## 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. # Apply a proposal > Apply a sales agent proposal to auto-add products with recommended budget allocations. Requires discover-products to have been called first. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml post /discovery/{discoveryId}/apply-proposal 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: /discovery/{discoveryId}/apply-proposal: post: tags: - Product Discovery summary: Apply a proposal description: >- Apply a sales agent proposal to auto-add products with recommended budget allocations. Requires discover-products to have been called first. operationId: applyProposal parameters: - in: path name: discoveryId schema: description: Discovery ID example: abc123-def456-ghi789 type: string minLength: 1 required: true description: Discovery ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApplyProposalRequest' responses: '200': description: Apply a proposal content: application/json: schema: $ref: '#/components/schemas/ApplyProposalResponse' '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: ApplyProposalRequest: description: >- Apply a sales agent proposal to auto-add products with recommended budget allocations type: object properties: proposalId: description: Proposal ID from the discover-products response to apply example: proposal_abc123 type: string totalBudget: description: >- Total budget to distribute across products. Defaults to the proposal totalBudgetGuidance.recommended. example: 50000 type: number minimum: 0 exclusiveMinimum: true replace: description: When true, replaces all existing products instead of merging type: boolean required: - proposalId ApplyProposalResponse: description: Response from applying a proposal type: object properties: discoveryId: description: Discovery ID type: string proposal: description: The proposal that was applied allOf: - $ref: '#/components/schemas/AppliedProposalSummary' totalBudgetUsed: description: Total budget distributed across products from this proposal type: number productsApplied: description: Number of products added from the proposal type: integer minimum: -9007199254740991 maximum: 9007199254740991 productsSkipped: description: >- Product IDs from the proposal that could not be found in discovery results type: array items: type: string products: description: All selected products after applying the proposal type: array items: $ref: '#/components/schemas/SelectedProduct' totalProducts: description: Total number of selected products type: integer minimum: -9007199254740991 maximum: 9007199254740991 budgetContext: description: Budget allocation context allOf: - $ref: '#/components/schemas/BudgetContextResponse' campaignBound: description: >- Whether the discovery session is attached to an active campaign. When false, the products are saved to the session but no active campaign reflects them yet. type: boolean campaignWarning: description: >- Guidance shown only when campaignBound is false: either the session is not attached to any campaign, or the campaign it was attached to has been archived. Pass campaignId for an active campaign (or restore the archived one) so the campaign reflects the products. type: string required: - discoveryId - proposal - totalBudgetUsed - productsApplied - productsSkipped - products - totalProducts 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 AppliedProposalSummary: description: Summary of the proposal that was applied type: object properties: proposalId: description: ID of the applied proposal type: string name: description: Name of the applied proposal type: string salesAgentName: description: Sales agent that generated the proposal type: string required: - proposalId - name additionalProperties: false SelectedProduct: description: A product selected for inclusion in a discovery session type: object properties: productId: description: Product ID type: string storefrontId: description: Storefront this product selection came from type: string inventorySourceId: description: Typed inventory source selected for execution type: string pattern: ^[1-9]\d*$ selectionId: description: >- Per-instance selection identity. Present only on repeat instances (the same product selected more than once); absent on a product’s single "base" selection. type: string salesAgentId: description: Sales agent ID type: string bidPrice: description: Bid price (CPM) the buyer set for the product type: number budget: description: Budget allocation for this product type: number targetingOverlay: description: Per-line-item AdCP targeting saved with this selection type: object properties: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} daypart_targets: type: array items: type: object properties: days: type: array items: anyOf: - type: string enum: - monday - type: string enum: - tuesday - type: string enum: - wednesday - type: string enum: - thursday - type: string enum: - friday - type: string enum: - saturday - type: string enum: - sunday start_hour: type: number minimum: 0 maximum: 23 end_hour: type: number minimum: 1 maximum: 24 label: type: string required: - days - start_hour - end_hour additionalProperties: {} axe_include_segment: type: string axe_exclude_segment: type: string audience_include: type: array items: type: string audience_exclude: type: array items: type: string signal_targeting_groups: type: object properties: operator: type: string enum: - all groups: type: array items: type: object properties: operator: anyOf: - type: string enum: - any - type: string enum: - none signals: type: array items: type: object properties: pricing_option_id: type: string signal_agent_segment_id: type: string activation_key: anyOf: - type: object properties: type: type: string enum: - segment_id segment_id: type: string required: - type - segment_id additionalProperties: {} - type: object properties: type: type: string enum: - key_value key: type: string value: type: string required: - type - key - value additionalProperties: {} additionalProperties: {} required: - operator - signals additionalProperties: {} required: - operator - groups additionalProperties: {} signal_targeting: type: array items: anyOf: - type: object properties: signal_ref: anyOf: - type: object properties: scope: type: string enum: - product signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - data_provider data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - data_provider_domain - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - signal_source signal_source_url: type: string signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_source_url - signal_id additionalProperties: {} signal_id: anyOf: - type: object properties: source: type: string enum: - catalog data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - data_provider_domain - id additionalProperties: {} - type: object properties: source: type: string enum: - agent agent_url: type: string id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - agent_url - id additionalProperties: {} value_type: type: string enum: - binary value: type: boolean required: - value_type - value additionalProperties: {} - type: object properties: signal_ref: anyOf: - type: object properties: scope: type: string enum: - product signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - data_provider data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - data_provider_domain - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - signal_source signal_source_url: type: string signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_source_url - signal_id additionalProperties: {} signal_id: anyOf: - type: object properties: source: type: string enum: - catalog data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - data_provider_domain - id additionalProperties: {} - type: object properties: source: type: string enum: - agent agent_url: type: string id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - agent_url - id additionalProperties: {} value_type: type: string enum: - categorical values: type: array items: type: string required: - value_type - values additionalProperties: {} - type: object properties: signal_ref: anyOf: - type: object properties: scope: type: string enum: - product signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - data_provider data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - data_provider_domain - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - signal_source signal_source_url: type: string signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_source_url - signal_id additionalProperties: {} signal_id: anyOf: - type: object properties: source: type: string enum: - catalog data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - data_provider_domain - id additionalProperties: {} - type: object properties: source: type: string enum: - agent agent_url: type: string id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - agent_url - id additionalProperties: {} value_type: type: string enum: - numeric min_value: type: number max_value: type: number required: - value_type additionalProperties: {} frequency_cap: type: object properties: suppress: 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: {} suppress_minutes: type: number minimum: 0 max_impressions: type: number minimum: 1 per: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom window: 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: {} additionalProperties: {} property_list: type: object properties: agent_url: type: string list_id: type: string minLength: 1 auth_token: type: string required: - agent_url - list_id additionalProperties: {} collection_list: type: object properties: agent_url: type: string list_id: type: string minLength: 1 auth_token: type: string required: - agent_url - list_id additionalProperties: {} collection_list_exclude: type: object properties: agent_url: type: string list_id: type: string minLength: 1 auth_token: type: string required: - agent_url - list_id additionalProperties: {} age_restriction: type: object properties: min: type: number minimum: 13 maximum: 99 verification_required: type: boolean accepted_methods: type: array items: anyOf: - type: string enum: - facial_age_estimation - type: string enum: - id_document - type: string enum: - digital_id - type: string enum: - credit_card - type: string enum: - world_id required: - min additionalProperties: {} device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown store_catchments: type: array items: type: object properties: catalog_id: type: string store_ids: type: array items: type: string catchment_ids: type: array items: type: string required: - catalog_id additionalProperties: {} geo_proximity: type: array items: anyOf: - type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 label: type: string travel_time: type: object properties: value: type: number minimum: 1 unit: anyOf: - type: string enum: - min - type: string enum: - hr required: - value - unit additionalProperties: {} transport_mode: anyOf: - type: string enum: - walking - type: string enum: - cycling - type: string enum: - driving - type: string enum: - public_transport ext: type: object properties: {} additionalProperties: {} required: - lat - lng - travel_time - transport_mode additionalProperties: {} - type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 label: type: string transport_mode: anyOf: - type: string enum: - walking - type: string enum: - cycling - type: string enum: - driving - type: string enum: - public_transport radius: type: object properties: value: type: number unit: anyOf: - type: string enum: - km - type: string enum: - mi - type: string enum: - m required: - value - unit additionalProperties: {} ext: type: object properties: {} additionalProperties: {} required: - lat - lng - radius additionalProperties: {} - type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 label: type: string transport_mode: anyOf: - type: string enum: - walking - type: string enum: - cycling - type: string enum: - driving - type: string enum: - public_transport geometry: type: object properties: type: anyOf: - type: string enum: - Polygon - type: string enum: - MultiPolygon coordinates: type: array items: {} required: - type - coordinates additionalProperties: {} ext: type: object properties: {} additionalProperties: {} required: - geometry additionalProperties: {} language: type: array items: type: string keyword_targets: type: array items: type: object properties: keyword: type: string minLength: 1 match_type: anyOf: - type: string enum: - broad - type: string enum: - phrase - type: string enum: - exact bid_price: type: number minimum: 0 required: - keyword - match_type additionalProperties: {} negative_keywords: type: array items: type: object properties: keyword: type: string minLength: 1 match_type: anyOf: - type: string enum: - broad - type: string enum: - phrase - type: string enum: - exact required: - keyword - match_type additionalProperties: {} additionalProperties: {} selectedAt: description: When the product was selected (ISO 8601) type: string groupId: description: Group ID where product was discovered type: string groupName: description: Name of the group type: string required: - productId - salesAgentId - selectedAt - groupId - groupName additionalProperties: false BudgetContextResponse: description: Budget allocation context type: object properties: sessionBudget: description: Total budget set for the session nullable: true type: number allocatedBudget: description: Budget allocated to selected products type: number remainingBudget: description: Remaining unallocated budget nullable: true type: number budgetWarning: description: Warning message if budget allocation has issues type: string required: - sessionBudget - allocatedBudget - remainingBudget additionalProperties: false 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 securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````