{"openapi":"3.1.0","info":{"title":"License Proof API","version":"1.0.0","summary":"Verify professional licenses from authoritative public sources.","description":"License Proof queries official licensing-authority publications and returns a deterministic, evidence-backed license status. It never fabricates a license or infers a status the source does not support. Price: 0.018 USDC per charged verification via x402 on Base mainnet. Operated by Active Life Hub LLC; License Proof does not issue licenses."},"servers":[{"url":"https://licenseproof.online"}],"paths":{"/api/v1/verify":{"post":{"operationId":"verifyLicense","summary":"Verify a professional license","description":"Without PAYMENT-SIGNATURE: validates the request, resolves coverage and answers 402 with the x402 requirement, the price and the exact official source that would be queried (free, nothing stored). With PAYMENT-SIGNATURE and Idempotency-Key: queries the source live and returns the result. Only determinate results are settled; SOURCE_UNAVAILABLE and UNABLE_TO_VERIFY are never charged. Retrying with the same Idempotency-Key never charges twice.","parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64 x402 v2 payment payload (exact scheme, USDC)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"},"description":"Required with PAYMENT-SIGNATURE. Reuse it for retries."},{"name":"X-City-Referral","in":"header","required":false,"schema":{"type":"string","maxLength":4096},"description":"Optional America Agent City referral token (City Advantage: 20% off; body or query field city_referral also accepted). Send the same token on the 402 quote and the paid retry. Missing or invalid → normal price. https://americaagent.city/docs/city-advantage.md"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"Verification result (any of the result codes). Header PAYMENT-RESPONSE carries the settlement when charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"402":{"description":"Payment required (quote), or the payment was invalid/rejected. Header PAYMENT-REQUIRED carries the x402 requirement.","content":{"application/json":{"schema":{"type":"object","description":"With X-City-Referral: the City Advantage quote fields show the discount before payment.","properties":{"normal_price":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"Normal price (USDC)."},"city_discount":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"City Advantage discount (USDC)."},"city_price":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"Price charged (USDC)."},"city_advantage_applied":{"type":"boolean"},"city_referral_id":{"type":["string","null"],"description":"Referral id (jti)."},"city_discount_percent":{"type":["string","null"]},"city_advantage_reason":{"type":"string","description":"Why no discount applied (402 quote only; omitted when applied)."}}}}}},"409":{"description":"Idempotency conflict, in progress, or payment replay","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"422":{"description":"Unknown jurisdiction/profession or combination not covered (never charged)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"503":{"description":"Not configured or payment provider unavailable (nothing charged)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}}}},"/api/v1/verifications/{id}":{"get":{"operationId":"getVerification","summary":"Retrieve a stored verification and its evidence (free)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^lpv_[0-9a-f]{52}$"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer <the Idempotency-Key used for the paid request>"}],"responses":{"200":{"description":"Stored result (cache_status STORED, original checked_at)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"410":{"description":"Evidence retention elapsed","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}}}},"/api/v1/coverage":{"get":{"operationId":"getCoverage","summary":"Machine-readable coverage registry (free)","responses":{"200":{"description":"Coverage entries","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/pricing":{"get":{"operationId":"getPricing","summary":"Machine-readable price and cost basis (free)","responses":{"200":{"description":"Pricing","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/health":{"get":{"operationId":"getHealth","summary":"Liveness and configuration status (free)","responses":{"200":{"description":"OK"},"503":{"description":"Not configured"}}}}},"components":{"schemas":{"VerifyRequest":{"type":"object","additionalProperties":false,"required":["profession","jurisdiction"],"properties":{"name":{"type":"string","maxLength":200,"description":"Person or business name, any script. Required unless license_number is given."},"license_number":{"type":"string","maxLength":40,"description":"License/registration number as printed (separators optional)."},"profession":{"type":"string","description":"One of physician, physician_assistant, nurse, dentist, pharmacist, veterinarian, attorney, real_estate, accountant, architect, engineer, contractor, electrician, plumber, hvac (common aliases accepted, e.g. \"RN\", \"lawyer\", \"realtor\")."},"jurisdiction":{"type":"string","description":"ISO 3166-2 code (US-CO, CA-QC); US state codes and names are accepted."},"city":{"type":"string","maxLength":100,"description":"Optional tie-breaker between several matches."},"language":{"type":"string","description":"Optional BCP 47 preferred explanation language (explanations are English today; official values are never translated)."}}},"Verification":{"type":"object","required":["verification_id","result","summary","verification","evidence","payment"],"properties":{"verification_id":{"type":"string"},"result":{"type":"string","enum":["VERIFIED_ACTIVE","VERIFIED_INACTIVE","EXPIRED","SUSPENDED","REVOKED","RESTRICTED","NOT_FOUND","AMBIGUOUS","SOURCE_UNAVAILABLE","UNABLE_TO_VERIFY"]},"summary":{"type":"string"},"charged":{"type":"boolean"},"query":{"type":"object"},"subject":{"type":["object","null"],"description":"Holder as the source names it (Unicode preserved)."},"license":{"type":["object","null"],"properties":{"number":{"type":["string","null"]},"type":{"type":"string"},"original_status":{"type":["string","null"],"description":"Exact wording of the authority."},"original_status_reason":{"type":["string","null"]},"normalized_status":{"type":"string","enum":["ACTIVE","RESTRICTED","INACTIVE","EXPIRED","SUSPENDED","REVOKED","NOT_ISSUED","UNKNOWN"]},"status_basis":{"type":"string","enum":["SOURCE_STATUS","ACTIVE_LISTING","EXPIRATION_DATE"]},"expires_on":{"type":["string","null"],"format":"date"},"jurisdiction":{"type":"string"},"issuing_authority":{"type":"string"},"discipline":{"type":["object","null"]}}},"candidates":{"type":"array","items":{"type":"object"}},"match":{"type":"object"},"verification":{"type":"object","properties":{"checked_at":{"type":"string","format":"date-time"},"source_updated_at":{"type":["string","null"],"format":"date-time"},"cache_status":{"type":"string","enum":["LIVE","IDEMPOTENT_REPLAY","STORED"]},"freshness":{"type":"string"},"source_type":{"type":"string","enum":["OFFICIAL_REGISTRY"]},"method":{"type":"string"},"confidence":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"sources":{"type":"array","items":{"type":"object"}}}},"interpretation":{"type":"object"},"unknowns":{"type":"array","items":{"type":"string"}},"evidence":{"type":"object","description":"Verbatim source fields and a SHA-256 over the evidence package."},"limitations":{"type":"array","items":{"type":"string"}},"language":{"type":"object"},"payment":{"type":"object"},"normal_price":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"Normal price (USDC)."},"city_discount":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"City Advantage discount (USDC)."},"city_price":{"type":"string","pattern":"^\\d+\\.\\d+$","description":"Price charged (USDC)."},"city_advantage_applied":{"type":"boolean"},"city_referral_id":{"type":["string","null"],"description":"Referral id (jti)."},"city_discount_percent":{"type":["string","null"]},"city_advantage_reason":{"type":"string","description":"Why no discount applied (402 quote only; omitted when applied)."}}}}},"x-pricing":{"amount":"0.018","currency":"USDC","unit":"verification","version":"lp-cost-plus-2026-09-30-v1","city_advantage":{"percent":"20","applies_with":"valid America Agent City referral token in X-City-Referral","participant_id":"p_bh8yi7msbgcq3waj","docs":"https://americaagent.city/docs/city-advantage.md"}}}