AdCP 3.1.13 · Trusted Match
identity_match
identity_match is an operation in the Trusted Match area of AdCP 3.1.13, flagged x-status: experimental in its own schema. Sent by publisher to evaluate user eligibility for packages using an opaque identity token.
identity_match request fields
The required column reflects the top-level required array only. 4 of the 12 request fields carry a top-level required flag: type, request_id, seller_agent_url, identities. A top-level if, anyOf, oneOf or dependencies block can make an unmarked field mandatory in the mode being called, and a flat table cannot render
a rule that fires in one mode only. Those branches are visible in the request schema itself.
| Field | Type | Required | Description |
|---|---|---|---|
$schema | string | Optional schema URI for validation. | |
adcp_version | string | Release-precision AdCP version (VERSION.RELEASE, e.g. | |
adcp_major_version | integer | DEPRECATED in favor of adcp_version. | |
type | string | required | Message type discriminator for deserialization. |
protocol_version | string | TMP protocol version. | |
request_id | string | required | Unique request identifier. |
seller_agent_url | string | required | API endpoint URL of the seller agent issuing this request. |
identities | object[] | required | Identity tokens for the user, each tagged with its type. |
consent | object | Privacy consent signals. | |
package_ids | string[] | Optional. | |
country | string | ISO 3166-1 alpha-2 country code. | |
sealed_credentials | object[] | Optional HPKE-sealed credentials addressed to specific audiences — the network-as-RP ("issuer-as-RP"/Mechanism B) carrier. |
identity_match reads. 30 of the 64 registered operations are flagged x-mutates-state and its request schema is not one of them, so repeating the call is side-effect free. AdCP's release notes describe x-mutates-state as a non-normative tooling
hint that agents do not validate, so it is the registry's classification of the operation rather than
a contract, and it is the only machine-readable answer in the registry to whether an operation is
safe to retry.
identity_match response fields
The first 13 rows are the shared protocol envelope from core/version-envelope.json and core/protocol-envelope.json. Only 6 of the 19 rows below belong to identity_match itself, beginning with type, request_id and eligible_package_ids. 5 fields in the whole response are marked required: status, type, request_id, eligible_package_ids, serve_window_sec.
| 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). | |
type | string | required | Message type discriminator for deserialization. |
request_id | string | required | Echoed request identifier from the identity match request |
eligible_package_ids | string[] | required | Package IDs the user is eligible for. |
serve_window_sec | integer | required | Per-package single-shot fcap window, in seconds. |
tmpx | string | DEPRECATED in favor of tmpx_providers. | |
tmpx_providers | object | Router-populated: ordered TMPX chunk/value pairs grouped by the originating identity provider's `provider_id`. |
The shared protocol envelope
62 of AdCP's 64 registered operations carry every one of the 13 envelope fields. report_plan_outcome and check_governance compose core/version-envelope.json only, so they carry the version pair and none of the task fields.
status resolves to enums/task-status.json, which admits nine values:
submitted, working, input-required, completed, canceled, failed, rejected, auth-required,
unknown. The envelope marks it required on every response, and a synchronous call emits completed rather than omitting it. When it returns submitted or working instead, task_id is the
polling handle and
push_notification_config is the webhook the agent echoes back to confirm the callback.
Webhooks are A2A and REST only: MCP sends progress notifications and defines no webhook.
payload appears in the response field table typed object. core/protocol-envelope.json describes it as a documentary construct and states that it is not a required wire field. Body fields
are siblings of the envelope fields: on MCP at the root of the tool response, on A2A in task.artifacts[0].parts[].DataPart, on REST at the root of the JSON body. An accessor that reads response.payload finds
nothing there.
Field lists are not published over the wire
AdCP's integration guide, docs/protocol/calling-an-agent.mdx, states that its MCP
servers no longer publish per-tool parameter schemas: a tools/list call returns an empty
properties object for every tool, and the guide directs clients not to infer shape from it. A client
author reads the schema registry instead of the tool list.
Frequently asked
- What does identity_match do?
- Sent by publisher to evaluate user eligibility for packages using an opaque identity token.
- Which fields does a identity_match request require?
- 4 of the 12 request fields carry a top-level required flag: type, request_id, seller_agent_url, identities. AdCP also constrains requests with top-level if/then, anyOf, oneOf and dependencies blocks that no required array captures, so an unmarked field can still be mandatory in the mode being called.
- Which AdCP version do these identity_match field tables describe?
- AdCP 3.1.13, the current published release, last updated 2026-08-11. The documentation tree is versioned separately from the schema tree in the same repository, so a doc page and a schema file can describe the same field differently.