Check one printed document number and check code

POST

/v1/public-check

const url = 'https://example.com/v1/public-check';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"checkCode":"example","documentNumber":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/public-check \
  --header 'Content-Type: application/json' \
  --data '{ "checkCode": "example", "documentNumber": "example" }'

Experimental, Version 1 alpha 1. The route takes no credential and reads registry data. It is served only when the active target authority activates a public check; otherwise every method on this path answers 404 exactly like an unknown route. The request carries one printed document number and one check code, and the service reads only the Content-Type header and the body. Evidence reads the record through the activated definition with its own Source credentials, compares the stored code in constant time, and answers with the activated status and printed fields only. Every miss, including an unknown number, an ambiguous or unresolved lookup, a missing fact, and a wrong code, answers one identical 404. The answer is not an Evidence response format and is never signed. The service applies no rate admission to this route; a deployment limits its rate at the proxy. Any origin may read every response, and the route never permits credentials.

Request Body^required

application/json

Evidence public check request Version 1 alpha 1

The body of POST /v1/public-check, sent as exactly application/json: one printed document number and the check code printed beside it. The contract is experimental. A body that fails this schema is refused before the Source is read and writes no audit record.

object

checkCode

required

The printed check code, 24 RFC 4648 base32 characters. ASCII letters are uppercased before comparison and nothing is stripped, so a value with spaces, hyphens, or padding is refused.

string

/^[A-Za-z2-7]{24}$/

documentNumber

required

The printed document number. The selector profile of the activated subject bounds it further; a value outside that profile is refused as an invalid selector before the Source is read.

string

>= 1 characters

Example ^generated

{
  "checkCode": "example",
  "documentNumber": "example"
}

Responses

200

The presented document number and check code match exactly one record

application/json

Evidence public check answer Version 1 alpha 1

The 200 body of POST /v1/public-check when the presented document number and check code match exactly one record. It carries only the status and the printed fields the active authority activated for the check, never another output of the definition. It is not an Evidence response format and is never signed. The contract is experimental.

object

fields

required

The members of the activated printed-fields output, a reviewed structured value.

object

observedAt

required

The time Evidence evaluated this check, in UTC truncated to the second.

string format: date-time

/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$/

schema

required

string

Allowed values: registry.evidence.public-check/v1alpha1

status

required

The value of the activated status output.

string

Allowed values: valid suspended revoked expired

Example

{
  "schema": "registry.evidence.public-check/v1alpha1",
  "status": "valid"
}

Headers

Access-Control-Allow-Origin

string

Allowed values: *

Any origin may read the response. Access-Control-Allow-Credentials is never sent.

Cache-Control

string

Allowed values: no-store

Evidence responses are never cacheable.

traceparent

string

/^00-(?!0{32}-)[0-9a-f]{32}-(?!0{16}-)[0-9a-f]{16}-[0-9a-f]{2}$/

W3C trace context the service mints for this request. An inbound traceparent is never read, and tracestate is never reflected.

400

Wrong content type, malformed or oversized body, malformed check code, or a document number outside the activated selector profile

application/problem+json

One of:

object
object

object

One of:

Evidence public problem Version 1

object

code

required

string

Allowed values: evidence.invalid-request

detail

required

string

Allowed values: the Evidence request is invalid

status

required

integer

Allowed values: 400

title

required

string

Allowed values: Evidence request is invalid

traceId

required

string

/^(?!0{32}$)[0-9a-f]{32}$/

type

required

string

Allowed values: https://id.registrystack.org/problems/registry-evidence/evidence/invalid-request

code

required

string

Allowed values: evidence.invalid-request

detail

required

string

Allowed values: the Evidence request is invalid

status

required

integer

Allowed values: 400

title

required

string

Allowed values: Evidence request is invalid

type

required

string

Allowed values: https://id.registrystack.org/problems/registry-evidence/evidence/invalid-request

Example

{
  "code": "evidence.invalid-request",
  "detail": "the Evidence request is invalid",
  "status": 400,
  "title": "Evidence request is invalid",
  "type": "https://id.registrystack.org/problems/registry-evidence/evidence/invalid-request"
}

Headers

Access-Control-Allow-Origin

string

Allowed values: *

Any origin may read the response. Access-Control-Allow-Credentials is never sent.

Cache-Control

string

Allowed values: no-store

Evidence responses are never cacheable.

traceparent

string

/^00-(?!0{32}-)[0-9a-f]{32}-(?!0{16}-)[0-9a-f]{16}-[0-9a-f]{2}$/

W3C trace context the service mints for this request. An inbound traceparent is never read, and tracestate is never reflected.

404

No record matches the presented pair. Every miss is one identical response. Without an activated public check the path is not served and answers as an unknown route instead.

application/problem+json

object

One of:

Evidence public problem Version 1

object

code

required

string

Allowed values: evidence.invalid-request

detail

required

string

Allowed values: the Evidence request is invalid

status

required

integer

Allowed values: 400

title

required

string

Allowed values: Evidence request is invalid

traceId

required

string

/^(?!0{32}$)[0-9a-f]{32}$/

type

required

string

Allowed values: https://id.registrystack.org/problems/registry-evidence/evidence/invalid-request

code

required

string

Allowed values: resource.not-found

detail

required

string

Allowed values: the requested resource was not found

status

required

integer

Allowed values: 404

title

required

string

Allowed values: Requested resource was not found

type

required

string

Allowed values: https://id.registrystack.org/problems/registry-evidence/resource/not-found

Example

{
  "code": "resource.not-found",
  "detail": "the requested resource was not found",
  "status": 404,
  "title": "Requested resource was not found",
  "type": "https://id.registrystack.org/problems/registry-evidence/resource/not-found"
}

Headers

Access-Control-Allow-Origin

string

Allowed values: *

Any origin may read the response. Access-Control-Allow-Credentials is never sent.

Cache-Control

string

Allowed values: no-store

Evidence responses are never cacheable.

traceparent

string

/^00-(?!0{32}-)[0-9a-f]{32}-(?!0{16}-)[0-9a-f]{16}-[0-9a-f]{2}$/

W3C trace context the service mints for this request. An inbound traceparent is never read, and tracestate is never reflected.

503

Admission, Source, evaluation, serialization, or audit failure; nothing is released

application/problem+json

One of:

object
object

object

One of:

Evidence public problem Version 1

object

code

required

string

Allowed values: evidence.invalid-request

detail

required

string

Allowed values: the Evidence request is invalid

status

required

integer

Allowed values: 400

title

required

string

Allowed values: Evidence request is invalid

traceId

required

string

/^(?!0{32}$)[0-9a-f]{32}$/

type

required

string

Allowed values: https://id.registrystack.org/problems/registry-evidence/evidence/invalid-request

code

required

string

Allowed values: source.unavailable

detail

required

string

Allowed values: the authoritative source is unavailable

status

required

integer

Allowed values: 503

title

required

string

Allowed values: Authoritative source is unavailable

type

required

string

Allowed values: https://id.registrystack.org/problems/registry-evidence/source/unavailable

Example

{
  "code": "source.unavailable",
  "detail": "the authoritative source is unavailable",
  "status": 503,
  "title": "Authoritative source is unavailable",
  "type": "https://id.registrystack.org/problems/registry-evidence/source/unavailable"
}

Headers

Access-Control-Allow-Origin

string

Allowed values: *

Any origin may read the response. Access-Control-Allow-Credentials is never sent.

Cache-Control

string

Allowed values: no-store

Evidence responses are never cacheable.

traceparent

string

/^00-(?!0{32}-)[0-9a-f]{32}-(?!0{16}-)[0-9a-f]{16}-[0-9a-f]{2}$/

W3C trace context the service mints for this request. An inbound traceparent is never read, and tracestate is never reflected.

Check one printed document number and check code

Request Bodyrequired

Example generated

Responses

200

Example

Headers

400

Example

Headers

404

Example

Headers

503

Example

Headers

Request Body^required

Example ^generated