@adcp/sdk API Reference - v10.0.1
    Preparing search index...

    Interface Account

    Account billed for this media buy. Includes advertiser, billing proxy (if any), and rate card applied.

    interface Account {
        account_id: string;
        name: string;
        advertiser?: string;
        billing_proxy?: string;
        status: AccountStatus;
        brand?: BrandReference;
        operator?: string;
        billing?: BillingParty;
        billing_entity?: BusinessEntity;
        rate_card?: string;
        payment_terms?: PaymentTerms;
        credit_limit?: { amount: number; currency: string };
        setup?: { url?: string; message: string; expires_at?: string };
        account_scope?: AccountScope;
        governance_agents?: { url: string }[];
        reporting_bucket?: {
            protocol: CloudStorageProtocol;
            bucket: string;
            prefix?: string;
            region?: string;
            format?: "jsonl" | "csv" | "parquet" | "avro" | "orc";
            compression?: "gzip" | "none";
            file_retention_days: number;
            setup_instructions?: string;
        };
        sandbox?: boolean;
        notification_configs?: NotificationConfig[];
        ext?: ExtensionObject;
    }
    Index

    Properties

    account_id name advertiser? billing_proxy? status brand? operator? billing? billing_entity? rate_card? payment_terms? credit_limit? setup? account_scope? governance_agents? reporting_bucket? sandbox? notification_configs? ext?

    Properties

    account_id: string

    Unique identifier for this account

    name: string

    Human-readable account name (e.g., 'Acme', 'Acme c/o Pinnacle')

    advertiser?: string

    The advertiser whose rates apply to this account

    billing_proxy?: string

    Optional intermediary who receives invoices on behalf of the advertiser (e.g., agency)

    status: AccountStatus
    brand?: BrandReference
    operator?: string

    Domain of the entity operating this account. When the brand operates directly, this is the brand's domain.

    ^a-z0-9?(.a-z0-9?)*$

    billing?: BillingParty
    billing_entity?: BusinessEntity
    rate_card?: string

    Identifier for the rate card applied to this account

    payment_terms?: PaymentTerms
    credit_limit?: { amount: number; currency: string }

    Maximum outstanding balance allowed

    Type Declaration

    • amount: number

      0

    • currency: string

      ^[A-Z]{3}$

    setup?: { url?: string; message: string; expires_at?: string }

    Present when status is 'pending_approval'. Contains next steps for completing account activation.

    Type Declaration

    • Optionalurl?: string

      URL where the human can complete the required action (credit application, legal agreement, add funds).

    • message: string

      Human-readable description of what's needed.

    • Optionalexpires_at?: string

      When this setup link expires.

      date-time

    account_scope?: AccountScope
    governance_agents?: { url: string }[]

    Governance agent endpoint registered on this account. Exactly one entry per sync_governance's one-agent-per-account invariant. The array shape is preserved for wire compatibility with 3.0; maxItems: 1 is load-bearing and mirrors the singular governance_context on the protocol envelope. Authentication credentials are write-only and not included in responses — use sync_governance to set or update credentials.

    Type Declaration

    • url: string

      Governance agent endpoint URL. Must use HTTPS.

      ^https://

    reporting_bucket?: {
        protocol: CloudStorageProtocol;
        bucket: string;
        prefix?: string;
        region?: string;
        format?: "jsonl" | "csv" | "parquet" | "avro" | "orc";
        compression?: "gzip" | "none";
        file_retention_days: number;
        setup_instructions?: string;
    }

    Cloud storage bucket where the seller delivers offline reporting files for this account. Seller provisions a dedicated bucket or a per-account prefix within a shared bucket, and grants the buyer read access out-of-band. Access MUST be scoped at the IAM layer so each account can only read its own prefix — bucket-wide grants are non-compliant even with per-account prefixes. Seller MUST revoke access when the account's status transitions to inactive, suspended, or closed. See security considerations for offline delivery in docs/media-buy/media-buys/optimization-reporting. Only present when the seller supports offline delivery (reporting_delivery_methods includes 'offline' in capabilities).

    Type Declaration

    • protocol: CloudStorageProtocol
    • bucket: string

      Bucket or container name

      3

      63

      ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$

    • Optionalprefix?: string

      Path prefix within the bucket. Seller appends date-based partitioning beneath this prefix.

      512

      ^[a-zA-Z0-9/_.-]+$

    • Optionalregion?: string

      Cloud region for the bucket

      64

      ^[a-z0-9-]+$

    • Optionalformat?: "jsonl" | "csv" | "parquet" | "avro" | "orc"

      File format for delivered files. Parquet, Avro, and ORC use internal compression (the top-level compression field is ignored for these formats).

    • Optionalcompression?: "gzip" | "none"

      Compression applied to delivered files

    • file_retention_days: number

      How long reporting files are retained in the bucket before deletion. Buyers must read files within this window. Minimum recommended: 14 days.

      1

    • Optionalsetup_instructions?: string

      URL to documentation for configuring buyer read access to this bucket (IAM role, service account, etc.). Operator-facing documentation — buyer agents MUST NOT auto-fetch this URL; surface it to a human operator. If an implementation fetches it (for preview), apply webhook URL SSRF validation and do not pass the fetched content into an LLM context without indirect-prompt-injection guarding. See docs/media-buy/media-buys/optimization-reporting#security-considerations-for-offline-delivery.

      ^https://

    sandbox?: boolean

    When true, this is a sandbox account — no real platform calls, no real spend. For account-id namespaces, sandbox accounts are pre-existing test accounts on the platform discovered via list_accounts or supplied out-of-band. For buyer-declared accounts, sandbox is part of the natural key: the same brand/operator pair can have both a production and sandbox account.

    notification_configs?: NotificationConfig[]

    Account-level webhook subscriptions for notifications whose lifecycle outlives any single media buy (e.g., creative.status_changed, creative.purged, wholesale feed change payloads). This is an account-scoped delivery surface, not an account-object lifecycle event stream; account status changes are observed through list_accounts polling or the one-shot sync_accounts.push_notification_config async result channel. Distinct from push_notification_config on individual operations, which anchors at a per-resource scope. Buyers register and update entries via sync_accounts; sellers echo the applied state here on list_accounts reads so buyers can verify what's active. The set is keyed by account-scoped subscriber_id; re-registering the same subscriber_id replaces that subscriber's config. authentication.credentials is write-only — sellers MUST NOT echo legacy auth credentials in this response. When two or more entries register the same event_types, each receives an independent fire — see #3009 multi-subscriber composition.

    ext?: ExtensionObject

    Settings

    Member Visibility

    On This Page

    Properties