Verification API

Status and proof metadata. Never raw evidence.

Public endpoints are open with CORS. Private onboarding endpoints need the profile id and its access token, which only the applicant holds. Admin endpoints need NIL33 key.

Public

GET  https://nil33.com/api/v1/profiles/<name>.nil      # public fields only
GET  https://nil33.com/api/v1/verify/<name>.nil        # signed assertion (below)
POST https://nil33.com/api/v1/kya/namespace/resolve      {"name":"jane-smith"}
GET  https://nil33.com/.well-known/did.json              # did:web:nil33.com
GET  https://nil33.com/.well-known/nil33-verification.json   # public key, checks, statement
GET  https://nil33.com/api/ledger                        # endorsement ledger
GET  https://nil33.com/api/x402/verify/<CODE>             # 402-metered account verification (settlement unexercised)

Verification response

{
  "verified": true,
  "namespace": "maya-johnson.nil",
  "checks": ["identity", "role", "wallet", "agreement", "disclosure", "consent"],
  "issuedAt": "2026-09-08T00:00:00Z",
  "validUntil": "2027-09-08T00:00:00Z",
  "publicLedgerUrl": "https://nil33.com/@maya-johnson",
  "evidence": "private",
  "signature": "<JWS compact, ES256, kid nil33-kya-2026-09>"
}

The signature is a JWS over the canonical JSON of the assertion (sorted keys, no whitespace). Verify with the public JWK in /.well-known/nil33-verification.json. verified is true only when identity, role, consent, authority (or self-representation), an active agreement, and wallet control are all complete.

Private (applicant-held token)

POST /api/v1/kya/onboarding/start     → id + resume link
POST /api/v1/kya/consent              {id,t,privacy,identity_consent,ledger_consent,marketing_consent}
POST /api/v1/kya/identity/session     → vendor hand-off (503 until a vendor is connected)
POST /api/v1/kya/role-evidence        {id,t,url,note}
POST /api/v1/kya/authority/invite     {id,t,representation_status,rep_name,rep_email}
POST /api/v1/kya/wallet/claim         {id,t,address} then {id,t,address,signature}
POST /api/v1/kya/wallet/unlink
POST /api/v1/kya/namespace/request    {id,t,name}
POST /api/v1/kya/review/submit
POST /api/v1/kya/status · /export · /withdraw

Safeguards

No documents here

Government-ID checks run at a specialized vendor; NIL33 stores a reference and an outcome (vendor pending, F-30).

Access log

Every change writes an append-only event with actor and time; the applicant can export it.

Manual review

Minors, authority conflicts, school or team impersonation, public-figure claims, sanctions-risk flags, and disputed names always go to a person.

Re-verification

A review date is set on material change; when it passes, the assertion's validity ends and the profile shows "review due".

Self-service

Export, wallet unlink, correction request, consent withdrawal, deletion request (hello@nil33.com).

Statement

Verified by NIL33, not endorsed by a school, league, or governing body.