Module adcp.types.domains.core.account

Classes

class Account (**data: Any)

Expand source code

class Account(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    account_id: Annotated[str, Field(description='Unique identifier for this account')]
    name: Annotated[
        str, Field(description="Human-readable account name (e.g., 'Acme', 'Acme c/o Pinnacle')")
    ]
    advertiser: Annotated[
        str | None, Field(description='The advertiser whose rates apply to this account')
    ] = None
    billing_proxy: Annotated[
        str | None,
        Field(
            description='Optional intermediary who receives invoices on behalf of the advertiser (e.g., agency)'
        ),
    ] = None
    status: Annotated[
        account_status.AccountStatus,
        Field(
            description='Account lifecycle status. See the Accounts Protocol overview for the operations matrix showing which tasks are permitted in each state.'
        ),
    ]
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(description='Brand reference identifying the advertiser'),
    ] = None
    operator: Annotated[
        str | None,
        Field(
            description="Domain of the entity operating this account. When the brand operates directly, this is the brand's domain.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    operator_unit: Annotated[
        operator_unit_1.OperatorUnit | None,
        Field(
            description='Operator-owned business unit, agency seat, or platform account associated with this advertiser account. The id round-trips from the natural key; name is mutable display metadata. This is distinct from account_id, which belongs to the seller/storefront namespace.'
        ),
    ] = None
    revision: Annotated[
        SchemaInt | None,
        Field(
            description='Monotonically increasing optimistic-concurrency token for this account. Incremented on every persisted settings change, identity-change request, and identity-change disposition; reads, dry runs, validation failures, and exact idempotency replays do not increment it. Pass the latest observed value in a sync_accounts settings-update entry to prevent lost updates.',
            ge=1,
        ),
    ] = None
    identity_change: Annotated[
        account_identity_change.AccountIdentityChange | None,
        Field(
            description='Pending or rejected operator-identity transition. While present, the top-level operator and operator_unit remain the current canonical identity. Re-read list_accounts until the request is applied (canonical fields change and this object disappears) or rejected.'
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            description="Immutable transaction currency when the seller's advertiser object is currency-bound. Media buys on this account MUST use this currency. Omit when the account selects currency independently per media buy.",
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    timezone: Annotated[
        str | None,
        Field(
            description='Immutable operational timezone for this account, expressed as UTC or an IANA timezone identifier. AdCP 3.2 sellers return it on every account. It is the default calendar-day boundary for account-scoped behavior unless a feature explicitly declares another timezone basis. For buyer-selected account_fixed provisioning it participates in the natural account key.',
            min_length=1,
        ),
    ] = None
    billing: Annotated[
        billing_party.BillingParty | None,
        Field(
            description="Who is invoiced on this account. See billing_entity for the invoiced party's business details."
        ),
    ] = None
    billing_entity: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description='Current canonical business entity for the party responsible for payment. Contains the legal name, tax IDs, and address needed for formal B2B invoicing. Corresponds to whoever billing points to (operator, agent, or advertiser). When this account appears in a response, bank details MUST be omitted and the request-only destination_billing_entity MUST NOT be exposed.'
        ),
    ] = None
    destination_billing_entity: Annotated[
        Any | None,
        Field(description='Request-only staging field. It MUST NOT appear in account read models.'),
    ] = None
    rate_card: Annotated[
        str | None, Field(description='Identifier for the rate card applied to this account')
    ] = None
    payment_terms: Annotated[
        payment_terms_1.PaymentTerms | None,
        Field(
            description='Payment terms agreed for this account. Binding for all invoices when the account is active.'
        ),
    ] = None
    credit_limit: Annotated[
        CreditLimit | None, Field(description='Maximum outstanding balance allowed')
    ] = None
    setup: Annotated[
        Setup | None,
        Field(
            description="Present when status is 'pending_approval'. Contains next steps for completing account activation."
        ),
    ] = None
    account_scope: account_scope_1.AccountScope | None = None
    governance_agents: Annotated[
        list[GovernanceAgent] | None,
        Field(
            description="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.",
            max_length=1,
            min_length=1,
        ),
    ] = None
    reporting_bucket: Annotated[
        ReportingBucket | None,
        Field(
            description="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)."
        ),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(
            description='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.'
        ),
    ] = None
    notification_configs: Annotated[
        list[notification_config.NotificationConfig] | None,
        Field(
            description='Account-level webhook subscriptions for creative lifecycle/assignment changes, indicators.changed, account status, durable account-change wake-ups, wholesale feed changes, and reporting.delivery_ready. Buyers manage entries via sync_accounts and verify persisted state on list_accounts. account.change_recorded wakes receivers to drain list_account_changes; reporting.delivery_ready is repaired through get_reporting_status; indicator and assignment payloads are invalidations repaired completely through get_media_buys; list_creatives may provide a bounded reverse projection. Distinct from per-resource push_notification_config. Entries are keyed by account-scoped subscriber_id; credentials are write-only.',
            max_length=16,
        ),
    ] = None
    reporting_delivery_configs: Annotated[
        list[reporting_delivery_config_state.ReportingDeliveryConfigurationState] | None,
        Field(
            description="Resolved durable reporting delivery configurations owned by the authenticated caller for this account. list_accounts MUST expose only the calling principal's set. State and seller-issued destination_ref are returned; credentials and bearer profiles MUST NOT appear. Any setup URL is a secret-free authenticated entry point, not a bearer credential.",
            max_length=16,
        ),
    ] = None
    webhook_activity: Annotated[
        list[webhook_activity_record.WebhookActivityRecord] | None,
        Field(
            description='Recent webhook delivery attempts scoped to this account when the caller requested webhook activity on list_accounts and the seller surfaces the log. Includes account-anchored notifications such as account.status_changed and MAY include other account-level fires relevant to this account. Three-state presence follows the shared webhook_activity[] contract: omitted means unsupported or not requested, [] means supported but no retained fires, non-empty lists recent attempts most-recent-first.',
            max_length=200,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• AccountWithAuthorization
• AccountResponse

Class variables

var account_id : str

var account_scope : AccountScope | None

var advertiser : str | None

var billing : BillingParty | None

var billing_entity : BusinessEntity | None

var billing_proxy : str | None

var brand : BrandReference | None

var credit_limit : CreditLimit | None

var currency : str | None

var destination_billing_entity : typing.Any | None

var ext : ExtensionObject | None

var governance_agents : list[GovernanceAgent] | None

var identity_change : AccountIdentityChange1 | AccountIdentityChange2 | None

var model_config

var name : str

var notification_configs : list[NotificationConfig] | None

var operator : str | None

var operator_unit : OperatorUnit | None

var payment_terms : PaymentTerms | None

var rate_card : str | None

var reporting_bucket : ReportingBucket | None

var reporting_delivery_configs : list[ReportingDeliveryConfigurationState] | None

var revision : int | None

var sandbox : bool | None

var setup : Setup | None

var status : AccountStatus

var timezone : str | None

var webhook_activity : list[WebhookActivityRecord] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Compression (*args, **kwds)

Expand source code

class Compression(StrEnum):
    gzip = 'gzip'
    none = 'none'

Enum where members are also (and must be) strings

Ancestors

• enum.StrEnum
• builtins.str
• enum.ReprEnum
• enum.Enum

Class variables

var gzip

var none

class CreditLimit (**data: Any)

Expand source code

class CreditLimit(AdCPBaseModel):
    amount: Annotated[StrictFloat, Field(ge=0.0)]
    currency: Annotated[str, Field(pattern='^[A-Z]{3}$')]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var amount : float

var currency : str

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Format (*args, **kwds)

Expand source code

class Format(StrEnum):
    jsonl = 'jsonl'
    csv = 'csv'
    parquet = 'parquet'
    avro = 'avro'
    orc = 'orc'

Enum where members are also (and must be) strings

Ancestors

• enum.StrEnum
• builtins.str
• enum.ReprEnum
• enum.Enum

Class variables

var avro

var csv

var jsonl

var orc

var parquet

class GovernanceAgent (**data: Any)

Expand source code

class GovernanceAgent(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    url: Annotated[AnyUrl, Field(description='Governance agent endpoint URL. Must use HTTPS.')]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

var url : pydantic.networks.AnyUrl

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingBucket (**data: Any)

Expand source code

class ReportingBucket(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    protocol: Annotated[
        cloud_storage_protocol.CloudStorageProtocol, Field(description='Cloud storage protocol')
    ]
    bucket: Annotated[
        str,
        Field(
            description='Bucket or container name',
            max_length=63,
            min_length=3,
            pattern='^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$',
        ),
    ]
    prefix: Annotated[
        str | None,
        Field(
            description='Path prefix within the bucket. Seller appends date-based partitioning beneath this prefix.',
            examples=['accounts/pinnacle/adcp', 'reporting/2024'],
            max_length=512,
            pattern='^[a-zA-Z0-9/_.-]+$',
        ),
    ] = None
    region: Annotated[
        str | None,
        Field(
            description='Cloud region for the bucket',
            examples=['us-east-1', 'europe-west1'],
            max_length=64,
            pattern='^[a-z0-9-]+$',
        ),
    ] = None
    format: Annotated[
        Format | None,
        Field(
            description='File format for delivered files. Parquet, Avro, and ORC use internal compression (the top-level compression field is ignored for these formats).'
        ),
    ] = Format.jsonl
    compression: Annotated[
        Compression | None, Field(description='Compression applied to delivered files')
    ] = Compression.gzip
    file_retention_days: Annotated[
        SchemaInt,
        Field(
            description='How long reporting files are retained in the bucket before deletion. Buyers must read files within this window. Minimum recommended: 14 days.',
            examples=[14, 30, 90],
            ge=1,
        ),
    ]
    setup_instructions: Annotated[
        AnyUrl | None,
        Field(
            description='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.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var bucket : str

var compression : Compression | None

var file_retention_days : int

var format : Format | None

var model_config

var prefix : str | None

var protocol : CloudStorageProtocol

var region : str | None

var setup_instructions : pydantic.networks.AnyUrl | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Setup (**data: Any)

Expand source code

class Setup(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[
        AnyUrl | None,
        Field(
            description='URL where the human can complete the required action (credit application, legal agreement, add funds).'
        ),
    ] = None
    message: Annotated[str, Field(description="Human-readable description of what's needed.")]
    expires_at: Annotated[
        AwareDatetime | None, Field(description='When this setup link expires.')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var expires_at : pydantic.types.AwareDatetime | None

var message : str

var model_config

var url : pydantic.networks.AnyUrl | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary