Repository navigation
Description
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:
- The operator typed a legal name and tax ID into a form.
- The buying agent charged a card in that company's name.
- The buying agent matched the registration number against the national company
registry. - The buying agent ran a full KYB check (beneficial owners, sanctions screening)
on a stated date. - 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. evidenceis request-side and seller-readable. Sellers MUST NOT echo another
party'sreferencevalues 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_limitandget_account_financialsalready 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
- Account: advertiser legal-entity identifier distinct from the invoiced party (KYC / e-invoicing) #5316 - advertiser legal entity distinct from the invoiced party.
evidence[]
should attach to both entities with one definition. - Demand-side acts-for authorization: how does an operator declare which agents may act for it? #6033 - demand-side acts-for authorization. That check comes first, and this
comes after it. - RFC: Aggregated brand identity verification (LEI / trademark / VMC / Wikidata / SEC CIK) #3926 - brand identity verification over public registries.
registry_matched
andbrand_json_publishedshould reuse its identifier types once it lands. - Account-level financial visibility: get_account_financials tool #1189 -
get_account_financials, where the credit outcome already lives.
Open questions
- 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? - 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. - 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 insetup.unmet. - 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.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsNo status
Activity
bokelley commentedon Sep 27, 2026
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)
verifieris 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.account.setup_requirements. Per-buyer variation shows up insetup.unmet.evidenceiswriteOnly, likebank. 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_evidencecovers all three pieces:business-entity.evidence, theaccount.setup_requirementscapability, andsetup.unmet. Every new property carriesx-status: experimental. Add anallOfconditional toget-adcp-capabilities-response.json: ifaccount.setup_requirementsis present,experimental_featuresMUST containaccount.setup_evidence. This matches the existingmeasurement.coreandprotocol.principalconditionals.The gate matters for a wire-compatibility reason.
business-entity.jsonisadditionalProperties: false, so a 3.1 or 3.2 seller that validates strictly will reject an unknownevidencekey. Buyers MUST sendevidenceonly to sellers that listaccount.setup_evidence. For every other seller, use thebilling_entity.extinterim path the issue already describes.1.
evidence[]on business entitiesNew
core/business-entity-evidence.json. Bothbilling_entityand a futureadvertiser_entity(#5316) reuse this one definition.fieldsminItems: 1,uniqueItemsbusiness-entityproperty names:legal_name,vat_id,tax_id,registration_number,address,contacts,bank. Every named field MUST be present in the same entity.methodenums/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 thanself_declared.verifieroperator.verified_atexpires_atreferenceextRequired:
fields,method,verifier,verified_at.additionalPropertiesstays at the DR-0009 default.On
core/business-entity.json, addevidence: an array of that item,maxItems: 10,writeOnly: true,x-status: experimental.Normative text for the schema description and the
sync_accountsdocs:sync_accountschanges a named field, earlier evidence for that field no longer applies. The buyer resends evidence for the new value.Scope of carriers.
business-entity.jsonis also inlined in media-buy, commercial-terms, and governance schemas. The property is meaningful onsync_accountsbilling_entityanddestination_billing_entity, and onadvertiser_entityif #5316 lands. Other carriers MAY ignore it. Inlining it everywhere will grow the media-buy model-context budget andPARITY_COMPILE_LIMIT, as happened in #7697. Measure both in the PR. The alternative is a siblingbilling_entity_evidencefield on thesync_accountsentry, which avoids the growth but separatesfieldsfrom the entity it refers to. Recommendation: keep it on the entity.2.
account.setup_requirementsinget_adcp_capabilitiesThis is an object keyed by billing party. Use
propertyNameswith thebilling-party.jsonvalues. Each value is:billing_entity_fieldsevidence.fields.accepted_evidenceminItems: 1) is one acceptable combination. The list is advisory.credit_applicationnone|required|required_abovecredit_application_threshold{ amount, currency }credit_applicationisrequired_above(if/then).payment_terms_offeredpayment-terms.jsonpayment_termsdoes 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.unmetAn array on the
setupobject, discriminated bykind(withtypebeforeconst, 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.urlalready names "legal agreement" as a common step, and without this kind the buyer is back to parsingmessage.kindis extensible. A buyer that does not recognize akindfalls back tosetup.messageandsetup.url.unmetsupplementsmessageand does not replace it, somessagestays required.The
setupobject is currently defined inline twice, incore/account.jsonandaccount/sync-accounts-response.json. Extract it tocore/account-setup.jsonsounmetis defined once, and use the extracted schema in both places. Leave the reducedsetupincore/account-status-changed-webhook.jsonunchanged. That payload is an invalidation signal, and receivers getunmetby re-readinglist_accounts.Files a PR would touch
core/business-entity-evidence.json,enums/business-entity-evidence-method.json,core/account-setup.json, andcore/account-setup-requirement.json(theunmetitem). Editcore/business-entity.json,core/account.json,account/sync-accounts-response.json, andprotocol/get-adcp-capabilities-response.json(thesetup_requirementsproperty plus the experimental conditional). Update the schema examples in the same files.docs/accounts/tasks/sync_accounts.mdx(requestbilling_entityrow, responsesetuprow, and a new "Billing identity evidence" section),docs/accounts/tasks/list_accounts.mdx(setuprow),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), anddocs/reference/experimental-status.mdx(a new table row).minor, 3.3 line.node tests/json-schema-validation.test.cjs --fileon each edited doc, the model-context budget,PARITY_COMPILE_LIMIT,x-entity(no new ID-bearing fields cross storyboard steps, so none are expected), andnpm run build:compliance -- --check.Still needs a WG or counsel call
payment_instrument_verifiedshould letfieldsincludebank. As written it can, since the charged instrument may be the bank account. The WG may prefer to limit it tolegal_name.registry_matchedandbrand_json_publishedwait 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 structuredregistrysub-object later.bokelley commentedon Nov 19, 2026
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 isPAYMENT_TERMS_NOT_SUPPORTED. With either answer, though, the buyer only learns which terms a seller accepts by sending a request and having it refused, becauseget_adcp_capabilitiesgives a seller no way to declare them.Proposal, additive and optional:
account.supported_payment_terms: ["net_30", "net_60", "prepay", ...], alongsidesupported_billing, so a buyer can choose terms the seller accepts before it sendssync_accounts.field: "payment_terms").PAYMENT_TERMS_NOT_SUPPORTEDis the code for terms.PAYMENT_TERMS_NOT_SUPPORTEDnamingpayment_terms, never an unlisted code.