Skip to content

Account: say how billing-identity facts were established, and let sellers publish what they need before sync_accounts #7700

Open

Description

@bokelley

The gap

A seller that receives sync_accounts has to decide whether to open a relationship
with the named operator and, for directly billed accounts, whether to extend credit.
AdCP already carries most of what that decision produces:

Need Existing surface
Who is invoiced billing
Legal name, tax ID, registration number, address, contacts, bank details billing_entity (core/business-entity.json)
Terms payment_terms (accept or reject, never silently remapped)
"We are reviewing - credit, legal" status: pending_approval + setup { url, message, expires_at }
The credit decision account.credit_limit
Ongoing headroom get_account_financials → credit.available_credit, payment_status

What it cannot carry is how any of the identity was established.
business-entity.json tells implementers to treat every field as untrusted input.
That is correct, but it leaves a seller unable to tell these apart:

  1. The operator typed a legal name and tax ID into a form.
  2. The buying agent charged a card in that company's name.
  3. The buying agent matched the registration number against the national company
    registry.
  4. The buying agent ran a full KYB check (beneficial owners, sanctions screening)
    on a stated date.
  5. The operator publishes the entity in its own brand.json.

Every seller re-runs its own check from scratch, usually through a setup.url
round trip, even when the buying agent has already done stronger work. And the
buyer only learns what a seller needs after sending the request and waiting in
pending_approval.

Proposal

Two additive, optional pieces.

1. evidence[] on business entities

An optional array on core/business-entity.json. It would also apply to the
proposed advertiser_entity (#5316) if that lands. Each item says which fields a
party checked, how, and when:

"evidence": [
  {
    "fields": ["legal_name", "registration_number", "address"],
    "method": "registry_matched",
    "verifier": "buyer-agent.example",
    "verified_at": "2026-09-20T14:02:00Z",
    "expires_at": "2027-09-20T00:00:00Z",
    "reference": "opaque-verifier-case-id"
  },
  {
    "fields": ["legal_name"],
    "method": "payment_instrument_verified",
    "verifier": "buyer-agent.example",
    "verified_at": "2026-09-18T09:00:00Z"
  }
]

method is an open, extensible vocabulary. Starting values:

Value What it establishes What it does not
self_declared The operator stated it Anything else
email_domain_verified A person controlling a mailbox at the operator's domain confirmed it That the domain owner is the legal entity named
payment_instrument_verified A payment instrument in this name was successfully charged or authorized Identity, ownership, or creditworthiness
registry_matched Name, number, and jurisdiction match an official company registry Who controls the company
brand_json_published The entity is declared in the operator's own brand.json That the brand.json publisher is who it claims (see #3926)
kyb_verified The verifier completed a know-your-business review (ownership, sanctions) on the date given Creditworthiness, or anything after verified_at
contract_executed A signed agreement with this entity exists The terms of that agreement

Normative points:

  • Evidence records what a verifier did, when. It is not a warranty. Whether a
    verifier stands behind it commercially is between the parties, outside AdCP.
  • An item from a verifier other than the calling agent is only as trustworthy as
    its signature. Unsigned items are statements by the caller about the caller's
    own work. A signed form (the RFC 9421 profile, verifier key resolved through its
    published JWKS) is an open question below.
  • Sellers apply their own policy. No method is required, and no combination
    "passes". This follows the aggregation-not-adjudication principle from RFC: Aggregated brand identity verification (LEI / trademark / VMC / Wikidata / SEC CIK) #3926.
  • evidence is request-side and seller-readable. Sellers MUST NOT echo another
    party's reference values to third parties.

2. Seller-published account-setup requirements

An optional account.setup_requirements block in get_adcp_capabilities, keyed by
billing party, so a buying agent can check before it asks:

"setup_requirements": {
  "operator": {
    "billing_entity_fields": ["legal_name", "tax_id", "address", "contacts"],
    "accepted_evidence": [["kyb_verified"], ["registry_matched", "payment_instrument_verified"]],
    "credit_application": "required_above",
    "credit_application_threshold": { "amount": 50000, "currency": "USD" },
    "payment_terms_offered": ["net_30", "net_60"]
  },
  "agent": {
    "billing_entity_fields": ["legal_name"]
  }
}

accepted_evidence is a list of alternatives. Each inner list is one acceptable
combination. It is advisory: the seller still decides in pending_approval.

And a machine-readable companion on the pending account, so the buying agent knows
what is missing rather than parsing setup.message:

"setup": {
  "url": "...",
  "message": "...",
  "expires_at": "...",
  "unmet": [
    { "kind": "billing_entity_field", "field": "tax_id" },
    { "kind": "evidence", "accepted": [["kyb_verified"]] },
    { "kind": "credit_application" }
  ]
}

Non-goals

  • No credit decisioning in the protocol. How much a seller lends is its own
    call. credit_limit and get_account_financials already carry the result.
  • No central verifier. AdCP defines how to state evidence. It does not certify
    verifiers.
  • Not authorization. Whether an agent may act for an operator at all is Demand-side acts-for authorization: how does an operator declare which agents may act for it? #6033,
    and it is checked before any of this. Evidence is about the invoiced entity, not
    the caller's authority.

Related

Open questions

  1. Signing. Do we require evidence from a third-party verifier to be signed by
    that verifier, or allow unsigned items with a clear "caller-asserted" meaning?
  2. Liability language. Is "a statement of what was done, not a warranty"
    enough, or does the WG want an explicit disclaimer field? This needs counsel
    review from at least one buying agent and one seller.
  3. Placement of requirements. Capability-level (one set per seller) or
    per-brand/per-operator? Capability-level is proposed for simplicity. Per-buyer
    variation shows up in setup.unmet.
  4. Evidence on responses. Should a seller be able to return evidence it
    gathered (for example "we verified your tax ID") on the account read model?

Interim use before 3.3

business-entity.json allows ext. Implementers can carry the evidence[] shape
under a vendor namespace in billing_entity.ext on 3.1 and 3.2 today. That gives
real traffic to learn from before the field is standardized.

Activity

  1. added
    rfcProtocol change — auto-adds to roadmap board
    schemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene
    needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendas
    media-buyIssue concerns the media-buy protocol domain
    on Sep 27, 2026
  2. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 27, 2026
  3. added this to the Spec Backlog milestone on Sep 27, 2026
  4. added
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 27, 2026
  5. bokelley commented on Sep 27, 2026

    @bokelley
    ContributorAuthor

    Design brief

    A schema sketch for WG review. No code yet. Main is in 3.2 RC, and this is new surface, so it targets 3.3 as the issue says.

    Answers to the open questions (proposed defaults)

    1. Signing. Unsigned only for now. An item whose verifier is not the calling agent is a statement by the caller about someone else's work. Sellers MUST NOT attribute it to the named verifier without their own confirmation. The signed form (RFC 9421 profile, verifier JWKS) is deferred to a follow-up. No field is reserved for it now, because an optional field can be added in a minor.
    2. Liability. No disclaimer field. Normative text only: evidence records what a verifier did and when, and it is not a warranty.
    3. Placement. Capability-level account.setup_requirements. Per-buyer variation shows up in setup.unmet.
    4. Evidence on responses. Not in this change. evidence is writeOnly, like bank. Sellers MUST NOT echo it in any response. Seller-returned evidence can be added later as a separate read-side field.

    Gating: one experimental feature id

    account.setup_evidence covers all three pieces: business-entity.evidence, the account.setup_requirements capability, and setup.unmet. Every new property carries x-status: experimental. Add an allOf conditional to get-adcp-capabilities-response.json: if account.setup_requirements is present, experimental_features MUST contain account.setup_evidence. This matches the existing measurement.core and protocol.principal conditionals.

    The gate matters for a wire-compatibility reason. business-entity.json is additionalProperties: false, so a 3.1 or 3.2 seller that validates strictly will reject an unknown evidence key. Buyers MUST send evidence only to sellers that list account.setup_evidence. For every other seller, use the billing_entity.ext interim path the issue already describes.

    1. evidence[] on business entities

    New core/business-entity-evidence.json. Both billing_entity and a future advertiser_entity (#5316) reuse this one definition.

    Field Type Notes
    fields array, minItems: 1, uniqueItems Closed enum of the top-level business-entity property names: legal_name, vat_id, tax_id, registration_number, address, contacts, bank. Every named field MUST be present in the same entity.
    method string New enums/business-entity-evidence-method.json, x-extensible: true, with the seven values from the issue. A seller that does not recognize a method MUST give the item no more weight than self_declared.
    verifier string Domain of the party that performed the check, using the same hostname pattern as operator.
    verified_at date-time Required.
    expires_at date-time Optional. Sellers SHOULD disregard expired items.
    reference string, maxLength 200 Opaque case id from the verifier. Sellers MUST NOT disclose it to third parties.
    ext ext

    Required: fields, method, verifier, verified_at. additionalProperties stays at the DR-0009 default.

    On core/business-entity.json, add evidence: an array of that item, maxItems: 10, writeOnly: true, x-status: experimental.

    Normative text for the schema description and the sync_accounts docs:

    Scope of carriers. business-entity.json is also inlined in media-buy, commercial-terms, and governance schemas. The property is meaningful on sync_accounts billing_entity and destination_billing_entity, and on advertiser_entity if #5316 lands. Other carriers MAY ignore it. Inlining it everywhere will grow the media-buy model-context budget and PARITY_COMPILE_LIMIT, as happened in #7697. Measure both in the PR. The alternative is a sibling billing_entity_evidence field on the sync_accounts entry, which avoids the growth but separates fields from the entity it refers to. Recommendation: keep it on the entity.

    2. account.setup_requirements in get_adcp_capabilities

    This is an object keyed by billing party. Use propertyNames with the billing-party.json values. Each value is:

    Field Type Notes
    billing_entity_fields array Same closed field enum as evidence.fields.
    accepted_evidence array of arrays of method Each inner array (minItems: 1) is one acceptable combination. The list is advisory.
    credit_application enum none | required | required_above
    credit_application_threshold { amount, currency } Required when credit_application is required_above (if/then).
    payment_terms_offered array of payment-terms.json Lets a buyer choose terms the seller will accept instead of discovering a rejection. The accept-or-reject behavior for payment_terms does not change.

    All of this is advisory. The seller still decides during pending_approval. A seller that omits the block tells the buyer nothing, and absence MUST NOT be read as "no requirements".

    3. setup.unmet

    An array on the setup object, discriminated by kind (with type before const, per the playbook):

    • { "kind": "billing_entity_field", "field": <field enum> }
    • { "kind": "evidence", "accepted": [[<method>, ...], ...] }
    • { "kind": "credit_application" }
    • { "kind": "agreement" }: this addition is not in the issue. setup.url already names "legal agreement" as a common step, and without this kind the buyer is back to parsing message.

    kind is extensible. A buyer that does not recognize a kind falls back to setup.message and setup.url. unmet supplements message and does not replace it, so message stays required.

    The setup object is currently defined inline twice, in core/account.json and account/sync-accounts-response.json. Extract it to core/account-setup.json so unmet is defined once, and use the extracted schema in both places. Leave the reduced setup in core/account-status-changed-webhook.json unchanged. That payload is an invalidation signal, and receivers get unmet by re-reading list_accounts.

    Files a PR would touch

    • Schemas: new core/business-entity-evidence.json, enums/business-entity-evidence-method.json, core/account-setup.json, and core/account-setup-requirement.json (the unmet item). Edit core/business-entity.json, core/account.json, account/sync-accounts-response.json, and protocol/get-adcp-capabilities-response.json (the setup_requirements property plus the experimental conditional). Update the schema examples in the same files.
    • Docs: docs/accounts/tasks/sync_accounts.mdx (request billing_entity row, response setup row, and a new "Billing identity evidence" section), docs/accounts/tasks/list_accounts.mdx (setup row), docs/protocol/get_adcp_capabilities.mdx (new #### account.setup_requirements), docs/building/by-layer/L2/accounts-and-agents.mdx (billing entity section), docs/accounts/provisioning-walkthrough.mdx (a preflight step: read requirements, then sync), and docs/reference/experimental-status.mdx (a new table row).
    • Changeset: minor, 3.3 line.
    • Gates: node tests/json-schema-validation.test.cjs --file on each edited doc, the model-context budget, PARITY_COMPILE_LIMIT, x-entity (no new ID-bearing fields cross storyboard steps, so none are expected), and npm run build:compliance -- --check.
    • No storyboard in the first cut. Everything is advisory, so there is no conformance MUST to grade yet.

    Still needs a WG or counsel call

    • Liability wording (open question 2) still needs review by counsel from at least one buying agent and one seller, as the issue says.
    • Whether payment_instrument_verified should let fields include bank. As written it can, since the charged instrument may be the bank account. The WG may prefer to limit it to legal_name.
    • Whether registry_matched and brand_json_published wait for RFC: Aggregated brand identity verification (LEI / trademark / VMC / Wikidata / SEC CIK) #3926's identifier types, or ship now as plain method values and get a structured registry sub-object later.
  6. bokelley commented on Nov 19, 2026

    @bokelley
    ContributorAuthor

    A concrete case for part 2 ("let sellers publish what they need before sync_accounts"), from production this week.

    A seller's agent refused 17 agent-billed account requests from 6 buyers. Each request carried payment_terms: "net_60", which AdCP allows. The agent answered with a code that isn't in the spec, UNSUPPORTED_ACCOUNT_FIELD, and named no field. The spec's own refusal for this case is PAYMENT_TERMS_NOT_SUPPORTED. With either answer, though, the buyer only learns which terms a seller accepts by sending a request and having it refused, because get_adcp_capabilities gives a seller no way to declare them.

    Proposal, additive and optional:

    • Declare accepted payment terms in capabilities. For example account.supported_payment_terms: ["net_30", "net_60", "prepay", ...], alongside supported_billing, so a buyer can choose terms the seller accepts before it sends sync_accounts.
    • Name the field on refusal. When a seller refuses an account request because of a field, the error should name it (field: "payment_terms"). PAYMENT_TERMS_NOT_SUPPORTED is the code for terms.
    • Conformance: a storyboard step that sends an account request with terms the seller hasn't declared, and expects PAYMENT_TERMS_NOT_SUPPORTED naming payment_terms, never an unlisted code.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.media-buyIssue concerns the media-buy protocol domainneeds-wg-reviewBlocked on a working-group decision — surface in WG meeting agendasrfcProtocol change — auto-adds to roadmap boardschemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygienespec / protocol

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions