Skip to content
Registry StackDocsLatest
Search

Evaluate claims for one target

POST
/v1/evaluations
curl --request POST \
  --url https://example.com/v1/evaluations \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <X-Api-Key>' \
  --data '{ "claims": [ { "id": "example", "version": "example" } ], "disclosure": "example", "format": "example", "on_behalf_of": { "actor": { "assurance": "example", "id_hash": "example", "type": "example" }, "delegation_ref": "example" }, "purpose": "example", "relationship": { "attributes": {}, "type": "example" }, "requester": { "assurance": { "evidence": [ {} ], "issuer": "example", "level": "example", "level_scheme": "example", "method": "example", "verified_at": "2026-04-15T12:00:00Z" }, "attributes": {}, "id": "example", "identifiers": [ { "country": "example", "issuer": "example", "scheme": "example", "value": "example" } ], "profile": "example", "type": "example" }, "target": { "assurance": { "evidence": [ {} ], "issuer": "example", "level": "example", "level_scheme": "example", "method": "example", "verified_at": "2026-04-15T12:00:00Z" }, "attributes": {}, "id": "example", "identifiers": [ { "country": "example", "issuer": "example", "scheme": "example", "value": "example" } ], "profile": "example", "type": "example" } }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
claims
required
Array<object>

Claim reference. Wire requests may also use a plain string claim id.

object
id
required
string
version
string
disclosure
string
format
string
on_behalf_of

Frozen minimal actor/delegation envelope. Replaces the previous free-form object; free-form payloads are rejected. Simple deployments omit on_behalf_of entirely. Production-grade delegation (OAuth token exchange / RAR / CIBA) arrives post-1.0 as an additive profile that maps the actor onto OAuth act-claim semantics via the opaque delegation_ref; the shape does not bake in a single-actor assumption.

object
actor
required
object
assurance

Optional assurance level of the actor (for example an acr value).

string
id_hash
required

Keyed-hash identifier of the actor in hmac-sha256: format. Never a raw principal value.

string
type
required
string
delegation_ref

Opaque reference to an out-of-band delegation record. Not interpreted by the envelope; the indirection point through which a later OAuth profile resolves an actor chain.

string
purpose
string
relationship
object
attributes
object
key
additional properties
any
type
required
string
requester
object
assurance
object
evidence
Array<object>
object
key
additional properties
any
issuer
string
level
string
level_scheme
string
method
string
verified_at
string format: date-time
attributes
object
key
additional properties
any
id
string
identifiers
Array<object>
object
country
string
issuer
string
scheme
required
string
value
required
string
profile
string
type
required
string
target
object
assurance
object
evidence
Array<object>
object
key
additional properties
any
issuer
string
level
string
level_scheme
string
method
string
verified_at
string format: date-time
attributes
object
key
additional properties
any
id
string
identifiers
Array<object>
object
country
string
issuer
string
scheme
required
string
value
required
string
profile
string
type
required
string
Examplegenerated
{
  "claims": [
    {
      "id": "example",
      "version": "example"
    }
  ],
  "disclosure": "example",
  "format": "example",
  "on_behalf_of": {
    "actor": {
      "assurance": "example",
      "id_hash": "example",
      "type": "example"
    },
    "delegation_ref": "example"
  },
  "purpose": "example",
  "relationship": {
    "attributes": {},
    "type": "example"
  },
  "requester": {
    "assurance": {
      "evidence": [
        {}
      ],
      "issuer": "example",
      "level": "example",
      "level_scheme": "example",
      "method": "example",
      "verified_at": "2026-04-15T12:00:00Z"
    },
    "attributes": {},
    "id": "example",
    "identifiers": [
      {
        "country": "example",
        "issuer": "example",
        "scheme": "example",
        "value": "example"
      }
    ],
    "profile": "example",
    "type": "example"
  },
  "target": {
    "assurance": {
      "evidence": [
        {}
      ],
      "issuer": "example",
      "level": "example",
      "level_scheme": "example",
      "method": "example",
      "verified_at": "2026-04-15T12:00:00Z"
    },
    "attributes": {},
    "id": "example",
    "identifiers": [
      {
        "country": "example",
        "issuer": "example",
        "scheme": "example",
        "value": "example"
      }
    ],
    "profile": "example",
    "type": "example"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Claim evaluation result

Media typeapplication/json
object
results
required
Array<object>
object
claim_id
required
string
claim_version
required
string
disclosure
required
string
evaluation_id
required
string
expires_at
required
string | null format: date-time
format
required
string
issued_at
required
string format: date-time
matching
object
confidence
required

Policy-asserted confidence label configured on the source binding and method. This is returned verbatim for successful matches against that binding; it is not a measured quality score for the individual match.

string
method
required

Configured matching method for the source binding.

string
policy_id
required

Target-matching policy identifier for the source binding: the policy that governs how the request target is matched to a source record. Distinct from generated_by.policy_id in claim provenance, which names the evaluation policy under which the result was produced.

string
score

Reserved optional per-match score. Current configured-only matching usually omits this field.

number | null
provenance
required

Versioned claim provenance (registry-notary-claim-provenance/v1). PROV-mappable but not PROV-O. Requester-side identity (client, actor, subject) is deliberately absent; it lives in restricted audit only.

object
derived_from
required

Upstream provenance records this result was derived from. Always empty in v1; reserved for additive cross-evaluation linking.

Array<object>
object
generated_by
required
object
claim_id
required
string
claim_version
required
string
evaluation_id
required
string
policy_hash

Sha256: digest of the evaluation policy. Public in v1: a hash revealing no policy content, used to correlate the result with a policy evidence-pack.

string
policy_id

Evaluation policy identifier: the policy under which this result was produced. Distinct from matching.policy_id, which names the target-matching policy for a source binding. Present for flows evaluated under a named policy (e.g. self-attestation); omitted for machine-client flows with no evaluation policy.

string
policy_version
string
service_id
required

Identifier of the service that produced the result. Replaces the dropped computed_by field; the CCCEV renderer maps its provider agent from here.

string
type
required
string
Allowed values: claim_evaluation
schema_version
required
string
Allowed values: registry-notary-claim-provenance/v1
used
required
object
source_count
required
integer
source_runtimes
required

Minimized summaries for connectors that cross an external execution boundary (the source-adapter sidecar). The full assurance document stays in restricted audit.

Array<object>
object
assurance
required
object
expression_hashes_verified
required
boolean
pinned
required
boolean
runtime_verified
required
boolean
smoke_verified
required
boolean
config_hash
required

Sha256: digest of the runtime configuration.

string
kind
required

Source-adapter sidecar runtime.

string
Allowed values: source_adapter_sidecar
source_versions
required
object
key
additional properties
string
requester_ref
object
handle
required
string
identifier_schemes
Array<string>
profile
string
type
required
string
satisfied
required
boolean | null
subject_type
required
string
target_ref
required
object
handle
required
string
identifier_schemes
Array<string>
profile
string
type
string
value
required

Claim value. The runtime may return any JSON value.

object
Example
{
  "results": [
    {
      "claim_id": "farmer-under-4ha",
      "claim_version": "2026-05",
      "disclosure": "predicate",
      "evaluation_id": "01HX7Y5F2WAJ7ZP0Q4M5K9E8NC",
      "expires_at": "2026-05-25T12:00:00Z",
      "format": "application/vnd.registry-notary.claim-result+json",
      "issued_at": "2026-05-24T12:00:00Z",
      "matching": {
        "confidence": "high",
        "method": "identifier_exact",
        "policy_id": "national-id-exact-v1",
        "score": 1
      },
      "provenance": {
        "derived_from": [],
        "generated_by": {
          "claim_id": "person_is_alive",
          "claim_version": "1",
          "evaluation_id": "01HX7Y5F2WAJ7ZP0Q4M5K9E8NC",
          "policy_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
          "policy_id": "self-attestation",
          "policy_version": "v1",
          "service_id": "demo.registry-notary",
          "type": "claim_evaluation"
        },
        "schema_version": "registry-notary-claim-provenance/v1",
        "used": {
          "source_count": 1,
          "source_runtimes": [],
          "source_versions": {}
        }
      },
      "requester_ref": {
        "handle": "rnref:v1:example-requester-ref",
        "identifier_schemes": [
          "agency_id"
        ],
        "profile": "benefits",
        "type": "Agency"
      },
      "satisfied": true,
      "subject_type": "person",
      "target_ref": {
        "handle": "rnref:v1:example-target-ref",
        "identifier_schemes": [
          "national_id"
        ],
        "profile": "resident",
        "type": "Person"
      },
      "value": true
    }
  ]
}

400

Section titled “400”

Invalid request

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "request.invalid",
  "detail": "the evidence request is invalid",
  "status": 400,
  "title": "Invalid evidence request",
  "type": "https://docs.registry-notary.dev/problems/request/invalid"
}

401

Section titled “401”

Missing or invalid credential

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "auth.missing_credential",
  "detail": "missing authentication credential",
  "status": 401,
  "title": "Missing credential",
  "type": "https://docs.registry-notary.dev/problems/auth/missing_credential"
}

403

Section titled “403”

Not authorized for requested claim, purpose, disclosure, or format

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "auth.scope_denied",
  "detail": "missing required scope",
  "status": 403,
  "title": "Scope denied",
  "type": "https://docs.registry-notary.dev/problems/auth/scope_denied"
}

406

Section titled “406”

Requested format is not acceptable

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "format.unsupported",
  "detail": "the requested claim format is not supported",
  "status": 406,
  "title": "Claim format not supported",
  "type": "https://docs.registry-notary.dev/problems/format/unsupported"
}

413

Section titled “413”

Request body or batch is too large

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "request.too_large",
  "detail": "the request body or batch is too large",
  "status": 413,
  "title": "Request too large",
  "type": "https://docs.registry-notary.dev/problems/request/too_large"
}

429

Section titled “429”

Self-attestation request is rate limited

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "self_attestation.rate_limited",
  "detail": "self-attestation request is rate limited",
  "status": 429,
  "title": "Self-attestation rate limited",
  "type": "https://docs.registry-notary.dev/problems/self_attestation/rate_limited"
}

503

Section titled “503”

Source service is unavailable

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "source.unavailable",
  "detail": "the evidence source is unavailable",
  "status": 503,
  "title": "Source unavailable",
  "type": "https://docs.registry-notary.dev/problems/source/unavailable"
}