AdCP 3.1.13 · Negotiation layer

AdCP Accounts

AdCP Accounts is a schema group of the Ad Context Protocol holding 5 of the 64 operations in release 3.1.13, covering account provisioning, governance endpoint assignment, usage reporting and billing state.

The account group establishes and reads a buyer's identity on a seller or vendor platform. sync_accounts provisions buyer-declared accounts or updates settings on existing ones, sync_governance attaches governance agent endpoints to specific accounts, list_accounts returns the accounts an authenticated agent can operate on, report_usage sends consumption data after delivery, and get_account_financials returns spend summaries, credit balances, payment status and invoice history for operator-billed accounts.

account/ is one of the four schema groups the release's bundled/ directory omits; the schema registry page lists the 23 operations that ship without a bundle.

What the 5 accounts operations do

Accounts — 5 operations
Operation	Request fields	Response fields	What it does
`get_account_financials`	6	13	get_account_financials returns spend summaries, credit balances, payment status, and invoice history for operator-billed AdCP accounts.
`list_accounts`	8	17	list_accounts returns all advertiser accounts an authenticated agent can operate on an AdCP vendor agent.
`report_usage`	7	17	report_usage sends consumption data to AdCP vendor agents after campaign delivery — impressions served, signals queried, governance checks run — so vendors can track revenue and verify billing.
`sync_accounts`	9	13	sync_accounts provisions buyer-declared accounts or updates settings on existing accounts with an AdCP seller agent.
`sync_governance`	6	13	sync_governance syncs governance agent endpoints to specific accounts.

`get_account_financials`

get_account_financials returns spend summaries, credit balances, payment status, and invoice history for operator-billed AdCP accounts.

get_account_financials request — 6 fields, 1 required
Field	Type	Required	Description
`adcp_version`	string		Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer		DEPRECATED in favor of adcp_version (release-precision string).
`account`	account-ref	required	Account to query financials for.
`period`	date-range		Date range for the spend summary.
`context`	context		Opaque correlation data that is echoed unchanged in responses.
`ext`	ext		Extension object for platform-specific, vendor-namespaced parameters.

get_account_financials response — 13 fields, 1 required
Field	Type	Required	Description
`adcp_version`	string		Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer		DEPRECATED in favor of adcp_version (release-precision string).
`context_id`	string		Session/conversation identifier for tracking related operations across multiple task invocations.
`context`	context		Per-request opaque caller-supplied correlation object echoed unchanged in the response.
`task_id`	string		Unique identifier for tracking asynchronous operations.
`status`	task-status	required	Current task execution state. One of: submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown.
`message`	string		Human-readable summary of the task result.
`timestamp`	string		ISO 8601 timestamp when the response was generated.
`replayed`	boolean		Set to true when this response was returned from the idempotency cache rather than from a fresh execution.
`adcp_error`	error		Transport-envelope error signal for fatal task failures.
`push_notification_config`	push-notification-config		Push notification configuration for async task updates (A2A and REST protocols).
`governance_context`	string		Governance context token issued by the account's governance agent during check_governance.
`payload`	object		Conceptual grouping for the task-specific response data defined by individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json).

get_account_financials — Example (javascript) — source

import { testAgent } from "@adcp/sdk/testing";

const result = await testAgent.getAccountFinancials({
  account: { account_id: "acc_acme_001" },
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

if ("errors" in result.data && result.data.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(result.data.errors)}`);
}

const { spend, credit, payment_status } = result.data;
console.log(`Spent: $${spend?.total_spend} this period`);

if (credit) {
  console.log(`Available credit: $${credit.available_credit} of $${credit.credit_limit}`);
}

if (payment_status === "past_due") {
  console.log("Warning: payment is past due — campaigns may be paused");
}

`list_accounts`

list_accounts returns all advertiser accounts an authenticated agent can operate on an AdCP vendor agent.

list_accounts request — 8 fields, 0 required
Field	Type	Description
`adcp_version`	string	Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer	DEPRECATED in favor of adcp_version (release-precision string).
`account`	account-ref	Optional exact account filter.
`status`	string	Filter accounts by status. One of: active, pending_approval, rejected, payment_required, suspended, closed.
`pagination`	pagination-request	Standard cursor-based pagination parameters for list operations
`sandbox`	boolean	Filter by sandbox status.
`context`	context	Opaque correlation data that is echoed unchanged in responses.
`ext`	ext	Extension object for platform-specific, vendor-namespaced parameters.

list_accounts response — 17 fields, 2 required
Field	Type	Required	Description
`adcp_version`	string		Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer		DEPRECATED in favor of adcp_version (release-precision string).
`context_id`	string		Session/conversation identifier for tracking related operations across multiple task invocations.
`context`	context		Opaque correlation data that is echoed unchanged in responses.
`task_id`	string		Unique identifier for tracking asynchronous operations.
`status`	task-status	required	Current task execution state. One of: submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown.
`message`	string		Human-readable summary of the task result.
`timestamp`	string		ISO 8601 timestamp when the response was generated.
`replayed`	boolean		Set to true when this response was returned from the idempotency cache rather than from a fresh execution.
`adcp_error`	error		Transport-envelope error signal for fatal task failures.
`push_notification_config`	push-notification-config		Push notification configuration for async task updates (A2A and REST protocols).
`governance_context`	string		Governance context token issued by the account's governance agent during check_governance.
`payload`	object		Conceptual grouping for the task-specific response data defined by individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json).
`accounts`	account-with-authorization[]	required	Array of accounts accessible to the authenticated agent.
`errors`	error[]		Task-specific errors and warnings
`pagination`	pagination-response		Standard cursor-based pagination metadata for list responses
`ext`	ext		Extension object for platform-specific, vendor-namespaced parameters.

list_accounts — Example (javascript) — source

import { testAgent } from "@adcp/sdk/testing";
import { ListAccountsResponseSchema } from "@adcp/sdk";

const result = await testAgent.listAccounts({});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = ListAccountsResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

for (const account of validated.accounts) {
  console.log(`${account.account_id}: ${account.name} (${account.status})`);
}

`report_usage`

report_usage sends consumption data to AdCP vendor agents after campaign delivery — impressions served, signals queried, governance checks run — so vendors can track revenue and verify billing.

report_usage request — 7 fields, 3 required
Field	Type	Required	Description
`adcp_version`	string		Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer		DEPRECATED in favor of adcp_version (release-precision string).
`idempotency_key`	string	required	Client-generated unique key for this request.
`reporting_period`	datetime-range	required	The time range covered by this usage report.
`usage`	object[]	required	One or more usage records.
`context`	context		Opaque correlation data that is echoed unchanged in responses.
`ext`	ext		Extension object for platform-specific, vendor-namespaced parameters.

report_usage response — 17 fields, 2 required
Field	Type	Required	Description
`adcp_version`	string		Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer		DEPRECATED in favor of adcp_version (release-precision string).
`context_id`	string		Session/conversation identifier for tracking related operations across multiple task invocations.
`context`	context		Opaque correlation data that is echoed unchanged in responses.
`task_id`	string		Unique identifier for tracking asynchronous operations.
`status`	task-status	required	Current task execution state. One of: submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown.
`message`	string		Human-readable summary of the task result.
`timestamp`	string		ISO 8601 timestamp when the response was generated.
`replayed`	boolean		Set to true when this response was returned from the idempotency cache rather than from a fresh execution.
`adcp_error`	error		Transport-envelope error signal for fatal task failures.
`push_notification_config`	push-notification-config		Push notification configuration for async task updates (A2A and REST protocols).
`governance_context`	string		Governance context token issued by the account's governance agent during check_governance.
`payload`	object		Conceptual grouping for the task-specific response data defined by individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json).
`accepted`	integer	required	Number of usage records successfully stored.
`errors`	error[]		Validation errors for individual records.
`sandbox`	boolean		When true, the account is a sandbox account and no billing occurred.
`ext`	ext		Extension object for platform-specific, vendor-namespaced parameters.

report_usage — Example (json) — source

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "reporting_period": {
    "start": "2025-03-01T00:00:00Z",
    "end": "2025-03-31T23:59:59Z"
  },
  "usage": [
    {
      "account": { "account_id": "acct_pinnacle_signals" },
      "signal_agent_segment_id": "luxury_auto_intenders",
      "pricing_option_id": "po_lux_auto_cpm",
      "impressions": 4200000,
      "media_spend": 21000.00,
      "vendor_cost": 2100.00,
      "currency": "USD"
    }
  ]
}

`sync_accounts`

sync_accounts provisions buyer-declared accounts or updates settings on existing accounts with an AdCP seller agent.

sync_accounts request — 9 fields, 2 required
Field	Type	Required	Description
`adcp_version`	string		Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer		DEPRECATED in favor of adcp_version (release-precision string).
`idempotency_key`	string	required	Client-generated unique key for at-most-once execution.
`accounts`	object[]	required	Per-account sync entries.
`delete_missing`	boolean		When true, accounts previously synced by this agent but not included in this request will be deactivated.
`dry_run`	boolean		When true, preview what would change without applying.
`push_notification_config`	push-notification-config		Webhook for async notifications when account status changes (e.g., pending_approval transitions to active).
`context`	context		Opaque correlation data that is echoed unchanged in responses.
`ext`	ext		Extension object for platform-specific, vendor-namespaced parameters.

sync_accounts response — 13 fields, 1 required
Field	Type	Required	Description
`adcp_version`	string		Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer		DEPRECATED in favor of adcp_version (release-precision string).
`context_id`	string		Session/conversation identifier for tracking related operations across multiple task invocations.
`context`	context		Per-request opaque caller-supplied correlation object echoed unchanged in the response.
`task_id`	string		Unique identifier for tracking asynchronous operations.
`status`	task-status	required	Current task execution state. One of: submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown.
`message`	string		Human-readable summary of the task result.
`timestamp`	string		ISO 8601 timestamp when the response was generated.
`replayed`	boolean		Set to true when this response was returned from the idempotency cache rather than from a fresh execution.
`adcp_error`	error		Transport-envelope error signal for fatal task failures.
`push_notification_config`	push-notification-config		Push notification configuration for async task updates (A2A and REST protocols).
`governance_context`	string		Governance context token issued by the account's governance agent during check_governance.
`payload`	object		Conceptual grouping for the task-specific response data defined by individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json).

sync_accounts — Example (javascript) — source

import { testAgent } from "@adcp/sdk/testing";
import { SyncAccountsResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncAccounts({
  accounts: [
    {
      brand: { domain: "acme-corp.com" },
      operator: "acme-corp.com",
      billing: "operator",
    },
  ],
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncAccountsResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

for (const account of validated.accounts) {
  console.log(`${account.brand.domain}: ${account.status}`);
  if (account.status === "pending_approval" && account.setup?.url) {
    console.log(`  Complete setup at: ${account.setup.url}`);
  }
}

`sync_governance`

sync_governance syncs governance agent endpoints to specific accounts.

sync_governance request — 6 fields, 2 required
Field	Type	Required	Description
`adcp_version`	string		Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer		DEPRECATED in favor of adcp_version (release-precision string).
`idempotency_key`	string	required	Client-generated unique key for at-most-once execution.
`accounts`	object[]	required	Per-account governance agent configuration.
`context`	context		Opaque correlation data that is echoed unchanged in responses.
`ext`	ext		Extension object for platform-specific, vendor-namespaced parameters.

sync_governance response — 13 fields, 1 required
Field	Type	Required	Description
`adcp_version`	string		Release-precision AdCP version (VERSION.RELEASE, e.g.
`adcp_major_version`	integer		DEPRECATED in favor of adcp_version (release-precision string).
`context_id`	string		Session/conversation identifier for tracking related operations across multiple task invocations.
`context`	context		Per-request opaque caller-supplied correlation object echoed unchanged in the response.
`task_id`	string		Unique identifier for tracking asynchronous operations.
`status`	task-status	required	Current task execution state. One of: submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown.
`message`	string		Human-readable summary of the task result.
`timestamp`	string		ISO 8601 timestamp when the response was generated.
`replayed`	boolean		Set to true when this response was returned from the idempotency cache rather than from a fresh execution.
`adcp_error`	error		Transport-envelope error signal for fatal task failures.
`push_notification_config`	push-notification-config		Push notification configuration for async task updates (A2A and REST protocols).
`governance_context`	string		Governance context token issued by the account's governance agent during check_governance.
`payload`	object		Conceptual grouping for the task-specific response data defined by individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json).

sync_governance — Example (javascript) — source

import { testAgent } from "@adcp/sdk/testing";
import { SyncGovernanceResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncGovernance({
  accounts: [
    {
      account: { account_id: "acct-social-001" },
      governance_agents: [
        {
          url: "https://governance.pinnacle-media.com",
          authentication: {
            schemes: ["Bearer"],
            credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          }
        }
      ]
    }
  ]
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncGovernanceResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

for (const entry of validated.accounts) {
  if (entry.status === "synced") {
    console.log(`${JSON.stringify(entry.account)}: ${entry.governance_agents.length} agent registered`);
  } else {
    console.log(`${JSON.stringify(entry.account)}: failed — ${JSON.stringify(entry.errors)}`);
  }
}

The other 9 AdCP areas

Media Buy — 11 operations
Creative — 8 operations
Signals — 2 operations
Protocol — 3 operations
Brand Protocol — 6 operations
Governance — 22 operations
Sponsored Intelligence — 4 operations
Trusted Match — 2 operations
Compliance — 1 operation

AdCP Accounts

What the 5 accounts operations do

get_account_financials

list_accounts

report_usage

sync_accounts

sync_governance