API documentation

REST/JSON. No account or API key: pay per verification with x402. Machine-readable: OpenAPI 3.1, llms.txt, coverage, pricing.

1. Ask (free)

POST https://licenseproof.online/api/v1/verify
Content-Type: application/json

{
  "name": "Jane Example",            // person or business, any script (optional if license_number)
  "license_number": "optional",      // as printed; separators optional
  "profession": "nurse",             // physician | physician_assistant | nurse | dentist | pharmacist | veterinarian | attorney | real_estate | accountant | architect | engineer | contractor | electrician | plumber | hvac
  "jurisdiction": "US-CO",           // ISO 3166-2; "CO", "Colorado", "Québec" accepted
  "city": "optional tie-breaker"
}

The request is validated and matched to coverage locally. An unsupported jurisdiction or profession returns 422 coverage_not_supported with what is covered. A covered request returns 402 with the x402 requirement (header PAYMENT-REQUIRED), the price (0.018 USDC) and the exact official source that will be queried. Nothing is stored and no registry is contacted.

2. Pay and verify

Resend the identical body with PAYMENT-SIGNATURE (base64 x402 v2 payload, exact scheme, USDC on Base mainnet) and an Idempotency-Key (16–128 characters of A–Z a–z 0–9 _ -). The authorization is verified, the source is queried live, and the payment is settled only for a determinate result. The settlement is returned in PAYMENT-RESPONSE.

{
  "verification_id": "lpv_…",
  "result": "VERIFIED_ACTIVE",
  "summary": "The official source lists this license as active.",
  "subject": { "name": "Jane Q Example", "entity_type": "individual", "city": "Denver", "region": "CO" },
  "license": {
    "number": "123456", "type": "Registered Nurse",
    "original_status": "Active", "normalized_status": "ACTIVE", "status_basis": "SOURCE_STATUS",
    "expires_on": "2027-09-30", "jurisdiction": "Colorado (US-CO)",
    "issuing_authority": "Colorado Department of Regulatory Agencies (DORA), …"
  },
  "match": { "method": "name", "name_match": "exact", "distinct_licenses_matched": 1 },
  "verification": {
    "checked_at": "…", "source_updated_at": "…", "cache_status": "LIVE",
    "source_type": "OFFICIAL_REGISTRY", "method": "OFFICIAL_OPEN_DATA_API_QUERY",
    "confidence": "HIGH", "sources": [{ "request_url": "https://data.colorado.gov/resource/…", … }]
  },
  "interpretation": { "explanation": "…", "caveats": [] },
  "unknowns": [],
  "evidence": { "records": [{ "source_fields": { … verbatim … } }], "evidence_sha256": "…" },
  "limitations": ["…"],
  "language": { "source_languages": ["en"], "output_language": "en", "original_values_preserved": true },
  "payment": { "charged": true, "status": "settled", "amount": "0.018", "transaction": "0x…" }
}

Retrying with the same key returns the stored result (cache_status IDEMPOTENT_REPLAY, original checked_at) and never charges again.
The same key with a different body → 409 idempotency_conflict. A payment authorization can be used once → 409 payment_replay.
If the result was not charged (SOURCE_UNAVAILABLE, UNABLE_TO_VERIFY) you may retry later with the same key; the unsettled authorization is released.

3. Retrieve later (free)

GET https://licenseproof.online/api/v1/verifications/{verification_id}
Authorization: Bearer <Idempotency-Key>

Returns the stored evidence package with cache_status: STORED. Evidence is kept 90 days; accounting fields are kept for financial records.

Results

`VERIFIED_ACTIVE`	The official source lists the license as active. Charged.
`VERIFIED_INACTIVE`	Listed, but not active (inactive, surrendered, retired, cancelled, deceased, delinquent registration…). Charged.
`EXPIRED`	Listed as expired or lapsed. Charged.
`SUSPENDED`	Listed as suspended. Charged.
`REVOKED`	Listed as revoked, disbarred or an equivalent removal. Charged.
`RESTRICTED`	Active with conditions, restrictions or probation. Charged.
`NOT_FOUND`	No matching record in the source. Not proof of never having been licensed. Charged.
`AMBIGUOUS`	Several licenses match; candidates are returned with their license numbers. Charged.
`SOURCE_UNAVAILABLE`	The official source could not be reached. Not charged.
`UNABLE_TO_VERIFY`	The source answered but the evidence does not support a status (unreadable response, application-only record, unknown status wording, or too many partial name matches). Not charged.

Reading a result

Verified facts: subject, license.number, license.type, license.original_status, dates, and evidence.records[].source_fields are the source’s own values, unmodified (Unicode preserved, never translated).
Interpretation: result, license.normalized_status, verification.confidence and interpretation are License Proof’s deterministic normalization.
Unknown: unknowns and limitations state what the evidence cannot establish.
status_basis: SOURCE_STATUS (authority publishes a status), ACTIVE_LISTING (authority publishes only active licenses) or EXPIRATION_DATE (no status published; derived from the expiry date, lower confidence).
Freshness: checked_at is when License Proof queried the source; source_updated_at is when the authority last refreshed its publication.

Errors

Every error is {"error":{"code","message","details?"}}. Codes: invalid_request, invalid_json, missing_identifier, name_too_broad, unknown_jurisdiction, unknown_profession, coverage_not_supported, payment_required, invalid_payment, payment_rejected, payment_expired, payment_wrong_*, idempotency_key_required, idempotency_conflict, payment_replay, in_progress, settlement_failed, rate_limited, not_configured, payment_provider_unavailable, service_unavailable.