Verification

You name a policy. DiligenceID builds the OpenID4VP request, handles the presentation exchange, checks the issuer's trust and the credential's status, and returns a result. You never construct protocol parameters.

Start a verification

curl -sS -X POST "$BASE/v1/verifications" \
  -H "Authorization: ApiKey $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "policy": "verified-employee" }'

Scope: verification.execute.

{
  "data": {
    "id": "vs_...",
    "status": "pending",
    "presentationUrl": "openid4vp://...",
    "qrCodePayload": "openid4vp://...",
    "expiresAt": "2026-08-29T02:12:03.117Z"
  }
}

Render qrCodePayload as a QR code for a desktop flow, or use presentationUrl as a deep link on mobile.

Read the outcome

curl -sS "$BASE/v1/verifications/$VERIFICATION_ID" -H "Authorization: ApiKey $KEY"

Scope: verification.read.

On verified:

{
  "data": {
    "id": "vs_...",
    "status": "verified",
    "decision": "Accepted",
    "verifiedAt": "2026-08-29T01:44:11.002Z",
    "result": {
      "claims": { "employee_id": "4821" },
      "issuerDid": "did:web:issuer.example",
      "credentialStatus": "active",
      "linkedDomainValidated": true
    }
  }
}

Only the claims the policy asks for are disclosed.

Cancel

curl -sS -X POST "$BASE/v1/verifications/$VERIFICATION_ID/cancel" -H "Authorization: ApiKey $KEY"

Scope: verification.execute. Cancels a pending verification — for example when a user abandons a checkout.

Policies

A policy is configured by an administrator and defines what evidence is required, which issuers are acceptable, which claims are required, what statuses are acceptable and whether holder binding is required. You reference it by identifier. Policy management is administrative today and is not on /v1.

Prefer webhooks to polling

Subscribe to verification.completed rather than polling. See Webhooks.

What a verification does and does not tell you

A verified presentation tells you the credential was issued by a trusted issuer, satisfies the policy, and has the status shown. It does not, by itself, establish that the holder's real-world identity has been verified, nor that they hold authority to act for an organisation. Those are separate evidence questions — see Security.