@adcp/client API Reference - v4.19.0
    Preparing search index...

    Interface CreateMediaBuyRequest

    Request parameters for creating a media buy. Supports two modes: (1) Manual mode - provide packages array with explicit line item configurations, or (2) Proposal mode - provide proposal_id and total_budget to execute a proposal from get_products. One of packages or proposal_id must be provided.

    interface CreateMediaBuyRequest {
        idempotency_key?: string;
        plan_id?: string;
        account: AccountReference;
        proposal_id?: string;
        total_budget?: { amount: number; currency: string };
        packages?: PackageRequest[];
        brand: BrandReference;
        invoice_recipient?: BusinessEntity;
        io_acceptance?: {
            io_id: string;
            accepted_at: string;
            signatory: string;
            signature_id?: string;
        };
        po_number?: string;
        start_time: string;
        end_time: string;
        push_notification_config?: PushNotificationConfig;
        reporting_webhook?: ReportingWebhook;
        artifact_webhook?: {
            url: string;
            token?: string;
            authentication: { schemes: AuthenticationScheme[]; credentials: string };
            delivery_mode: "realtime" | "batched";
            batch_frequency?: "hourly" | "daily";
            sampling_rate?: number;
        };
        context?: ContextObject;
        ext?: ExtensionObject;
    }
    Index

    Properties

    idempotency_key? plan_id? account proposal_id? total_budget? packages? brand invoice_recipient? io_acceptance? po_number? start_time end_time push_notification_config? reporting_webhook? artifact_webhook? context? ext?

    Properties

    idempotency_key?: string

    Client-generated unique key for this request. If a request with the same idempotency_key and account has already been processed, the seller returns the existing media buy rather than creating a duplicate. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.

    plan_id?: string

    Campaign governance plan identifier. Required when the account has governance_agents. The seller includes this in the committed check_governance request so the governance agent can validate against the correct plan.

    account: AccountReference
    proposal_id?: string

    ID of a proposal from get_products to execute. When provided with total_budget, the publisher converts the proposal's allocation percentages into packages automatically. Alternative to providing packages array.

    total_budget?: { amount: number; currency: string }

    Total budget for the media buy when executing a proposal. The publisher applies the proposal's allocation percentages to this amount to derive package budgets.

    Type Declaration

    • amount: number

      Total budget amount

    • currency: string

      ISO 4217 currency code

    packages?: PackageRequest[]

    Array of package configurations. Required when not using proposal_id. When executing a proposal, this can be omitted and packages will be derived from the proposal's allocations.

    brand: BrandReference
    invoice_recipient?: BusinessEntity
    io_acceptance?: {
        io_id: string;
        accepted_at: string;
        signatory: string;
        signature_id?: string;
    }

    Acceptance of an insertion order from a committed proposal. Required when the proposal's insertion_order has requires_signature: true. References the io_id from the proposal's insertion_order.

    Type Declaration

    • io_id: string

      The io_id from the proposal's insertion_order being accepted

    • accepted_at: string

      ISO 8601 timestamp when the IO was accepted

    • signatory: string

      Who accepted the IO — agent identifier or human name

    • Optionalsignature_id?: string

      Reference to the electronic signature from the signing service, when signing_url was used

    po_number?: string

    Purchase order number for tracking

    start_time: string
    end_time: string

    Campaign end date/time in ISO 8601 format

    push_notification_config?: PushNotificationConfig
    reporting_webhook?: ReportingWebhook
    artifact_webhook?: {
        url: string;
        token?: string;
        authentication: { schemes: AuthenticationScheme[]; credentials: string };
        delivery_mode: "realtime" | "batched";
        batch_frequency?: "hourly" | "daily";
        sampling_rate?: number;
    }

    Optional webhook configuration for content artifact delivery. Used by governance agents to validate content adjacency. Seller pushes artifacts to this endpoint; orchestrator forwards to governance agent for validation.

    Type Declaration

    • url: string

      Webhook endpoint URL for artifact delivery

    • Optionaltoken?: string

      Optional client-provided token for webhook validation. Echoed back in webhook payload to validate request authenticity.

    • authentication: { schemes: AuthenticationScheme[]; credentials: string }

      Authentication configuration for webhook delivery (A2A-compatible)

      • schemes: AuthenticationScheme[]

        Array of authentication schemes. Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for signature verification (recommended for production)

      • credentials: string

        Credentials for authentication. For Bearer: token sent in Authorization header. For HMAC-SHA256: shared secret used to generate signature. Minimum 32 characters. Exchanged out-of-band during onboarding.

    • delivery_mode: "realtime" | "batched"

      How artifacts are delivered. 'realtime' pushes artifacts as impressions occur. 'batched' aggregates artifacts and pushes periodically (see batch_frequency).

    • Optionalbatch_frequency?: "hourly" | "daily"

      For batched delivery, how often to push artifacts. Required when delivery_mode is 'batched'.

    • Optionalsampling_rate?: number

      Fraction of impressions to include (0-1). 1.0 = all impressions, 0.1 = 10% sample. Default: 1.0

    context?: ContextObject
    ext?: ExtensionObject

    Settings

    Member Visibility

    On This Page

    Properties