Verifier API — PASSID

Canonical verification contract

POST /v1/verify

The verifier endpoint is deliberately narrow. It returns whether a credential is valid, whether the proof and signature verify, whether the credential is fresh and not revoked, and which claims are safe to rely on. It does not provide raw transaction feeds and it does not make approval decisions on your behalf.

⚡

Fast verification

Check proof validity, signature integrity, freshness, and revocation status in a single institution-facing request.

🧾

Verified claims

Receive portable financial claims such as income stability, cashflow discipline, payment reliability, fraud integrity, and sanctions status.

🛰

Audit metadata

Each verification returns an audit reference, timestamps, policy version, and model version for bank-grade traceability.

🏛

Institution decides

PASSID verifies. Your institution decides how to route the returned claims into its own policies, manual review, or decision engine.

POST /v1/verify

{
  "credential_id": "pid_7f3c9x2mab4k"
}

200 OK

{
  "valid": true,
  "verification_id": "vrf_01hzk3vw0kg9",
  "verified_at": "2026-03-17T14:02:11Z",
  "credential_status": "active",
  "credential_id": "pid_7f3c9x2mab4k",
  "issuer": "passid",
  "claims": {
    "income_stability": "high",
    "cashflow_discipline": "moderate",
    "payment_reliability": "strong",
    "fraud_integrity": "clear",
    "sanctions_clear": true,
    "stability_band": "A",
    "confidence": "high",
    "freshness_hours": 48
  },
  "proof": {
    "system": "groth16",
    "status": "verified"
  },
  "signature": {
    "algorithm": "ed25519",
    "status": "verified"
  },
  "revocation_status": "not_revoked",
  "expires_at": "2026-06-08T12:00:00Z",
  "policy_version": "verifier_policy_v1",
  "model_version": "passid_fsi_v1_0"
}

PASSID verifies credential validity, proof, freshness, and claims. Institutions decide how to use those claims.

verify endpoint

How passid-verifier fits into institution workflows.

The verifier accepts a PASSID presentation or credential reference, checks signature and proof state, validates freshness and revocation, and returns the credential claims the institution may choose to route into its own policies.

holder

Credential or presentation

User shares a PASSID credential object or a credential reference.

→

verify

passid-verifier

Checks proof, signature, freshness, revocation, and claim integrity.

→

institution

Policy + decision workflow

Institution routes verified claims into its own rules, review queue, or decision engine.

request options

Option A: full credential · Option B: reference-based

{
  "credential": {
    "credential_type": "financial_stability_v1",
    "credential_id": "pid_7f3c9x2mab4k",
    "issuer": "passid",
    "issued_at": "2026-06-01T12:00:00Z",
    "expires_at": "2026-06-08T12:00:00Z",
    "claims": {
      "income_stability": "high",
      "cashflow_discipline": "moderate",
      "payment_reliability": "strong"
    },
    "proof": {
      "system": "groth16",
      "status": "verified"
    },
    "signature": {
      "algorithm": "ed25519",
      "value": "base64_signature"
    }
  }
}

OR

{
  "credential_id": "pid_7f3c9x2mab4k"
}

field definitions

What institutions can rely on.

Returned fields

valid → overall verification result
verification_id → unique audit reference
credential_status → active / expired / revoked / invalid
claims → verified financial claims
proof.status → cryptographic proof verification
signature.status → issuer authenticity
revocation_status → credential lifecycle state
freshness_hours → recency of underlying data
policy_version → verifier rules used
model_version → PASSID model version

What this endpoint is not

Not a lend score API
Not a bureau file pull
Not a lending decision engine
Not an approval or decline endpoint
Not a raw transaction feed

Failure modes

Explicit errors for bank-grade integrations.

Verifier responses should be predictable in both success and failure states. PASSID returns structured reason codes so engineering, operations, and compliance teams can debug confidently.

✦

invalid_signature

Credential signature could not be verified against the issuer key.

⌛

credential_expired

The credential is cryptographically intact but outside its freshness or expiry window.

⛔

credential_revoked

The credential was revoked and should not be relied upon.

∿

invalid_proof

The proof could not be verified or does not satisfy the expected credential policy.

error example

Invalid signature

{
  "valid": false,
  "credential_status": "invalid",
  "reason_code": "invalid_signature",
  "message": "Credential signature could not be verified.",
  "verification_id": "vrf_01hzk..."
}

error examples

Expired, revoked, and invalid proof

{
  "valid": false,
  "credential_status": "expired",
  "reason_code": "credential_expired",
  "expires_at": "2026-06-08T12:00:00Z"
}

{
  "valid": false,
  "credential_status": "revoked",
  "reason_code": "credential_revoked"
}

{
  "valid": false,
  "credential_status": "invalid",
  "reason_code": "invalid_proof"
}