{"openapi":"3.1.1","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"VerifiedNode public evidence API","version":"1.2.0","description":"Public candidate search and source-attributed evidence. No API key or payment is required. A source observation is not a profile refresh or an eligibility decision. Preserve unknown/stale evidence and use authority links for current status. Lookups do not purchase, claim profiles or publish documents."},"servers":[{"url":"https://www.verifiednode.com"}],"externalDocs":{"url":"https://www.verifiednode.com/developers","description":"MCP, CLI and evidence interpretation"},"security":[],"paths":{"/api/public/businesses":{"get":{"operationId":"lookup_business","summary":"Search candidates or read one exact public profile","description":"Use query with optional state, city and limit for search, OR state, city and slug for one profile. Do not combine modes. Unknown parameters return 400. Profile credentials include an authority-qualified recordIdentity and sourceKey provenance; compare authorityId, jurisdiction, kind and exact number together. Server and edge caches each revalidate on a five-minute interval; responses are not real-time. Neither a profile update timestamp nor a source snapshot establishes fresh credential evidence. Search is bounded, not an exhaustive registry export. This server-to-server API does not permit foreign browser Origin headers.","parameters":[{"name":"query","in":"query","required":false,"description":"Required for search. Omit when using the exact-profile mode.","schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"state","in":"query","required":false,"description":"State slug. Optional for search; required with city and slug for an exact profile.","schema":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"city","in":"query","required":false,"description":"City slug. Optional for search; required with state and slug for an exact profile.","schema":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"limit","in":"query","required":false,"description":"Search result cap, from 1 to 20. Defaults to 10. Not allowed in exact-profile mode.","schema":{"default":10,"type":"integer","minimum":1,"maximum":20}},{"name":"slug","in":"query","required":false,"description":"Presence selects exact-profile mode. Requires state and city; query and limit are then invalid. Use a slug returned by search.","schema":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"responses":{"200":{"description":"Candidate search or exact profile, according to the query mode.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BusinessSearch"},{"$ref":"#/components/schemas/BusinessProfile"}]}}}},"400":{"description":"Invalid query parameters or mixed lookup modes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Foreign browser Origin header is not permitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile. This does not establish license status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-instance burst guard; retry after the indicated delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Delay in seconds before retrying.","schema":{"type":"string","pattern":"^[0-9]+$"}}}},"503":{"description":"Lookup temporarily unavailable. Retry with bounded backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/sources":{"get":{"operationId":"list_sources","summary":"Read source coverage, file observations and limitations","description":"No parameters. Every source key maps to a stable issuing-board authorityId; healthAvailable=false means health retrieval is unavailable, not that a source has no licenses. Profile projection status is separate from a completed source-file observation. Source-reported dates may have day precision only.","responses":{"200":{"description":"Public source ledger, including explicit unknown health.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceLedger"}}}}}}}},"components":{"schemas":{"BusinessSearch":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schemaVersion":{"type":"string","const":"1.1"},"evidenceNote":{"type":"string"},"truncated":{"type":"boolean"},"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"slug":{"type":"string"},"profileUrl":{"type":"string"},"evidenceUrl":{"type":"string"}},"required":["name","state","city","slug","profileUrl","evidenceUrl"],"additionalProperties":false}}},"required":["schemaVersion","evidenceNote","truncated","results"],"additionalProperties":false},"BusinessProfile":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schemaVersion":{"type":"string","const":"1.2"},"evidenceNote":{"type":"string"},"name":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"category":{"type":"string"},"website":{"type":"string"},"phone":{"type":"string"},"address":{"type":"string"},"rating":{"type":"number"},"reviewCount":{"type":"number"},"credentials":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["license","bond","insurance","workers_comp","certification"]},"status":{"type":"string","enum":["active","expired","suspended","revoked","exempt","unknown"]},"evidenceLevel":{"type":"string","enum":["registry_confirmed","document_matched","document_only","self_declared"]},"jurisdiction":{"type":"string"},"number":{"type":"string"},"classifications":{"type":"array","items":{"type":"string"}},"issuedAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"number"},{"type":"null"}]},"amount":{"anyOf":[{"type":"number"},{"type":"null"}]},"carrier":{"anyOf":[{"type":"string"},{"type":"null"}]},"confirmedAt":{"type":"number"},"authorityName":{"anyOf":[{"type":"string"},{"type":"null"}]},"authorityShortName":{"anyOf":[{"type":"string"},{"type":"null"}]},"authorityLookupUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"recordIdentity":{"type":"object","properties":{"authorityId":{"anyOf":[{"type":"string"},{"type":"null"}]},"jurisdiction":{"type":"string"},"kind":{"type":"string","enum":["license","bond","insurance","workers_comp","certification"]},"number":{"type":"string"}},"required":["authorityId","jurisdiction","kind","number"],"additionalProperties":false},"sourceNote":{"type":"string"},"freshness":{"type":"object","properties":{"state":{"type":"string","enum":["unknown","stale","not_attested"]},"timestampBasis":{"type":"string","const":"legacy_confirmation"},"lastRecordedConfirmationAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"staleAfter":{"anyOf":[{"type":"string"},{"type":"null"}]},"evaluatedAt":{"type":"string"},"maxAgeDays":{"type":"number"},"sourcePublishedAt":{"type":"null"},"snapshotId":{"type":"null"},"note":{"type":"string"}},"required":["state","timestampBasis","lastRecordedConfirmationAt","staleAfter","evaluatedAt","maxAgeDays","sourcePublishedAt","snapshotId","note"],"additionalProperties":false}},"required":["kind","status","evidenceLevel","jurisdiction","number","classifications","issuedAt","expiresAt","amount","carrier","confirmedAt","authorityName","authorityShortName","authorityLookupUrl","sourceKey","recordIdentity","freshness"],"additionalProperties":false}},"credentialWindow":{"type":"object","properties":{"returned":{"type":"number"},"limit":{"type":"number"},"total":{"anyOf":[{"type":"number"},{"type":"null"}]},"truncated":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["returned","limit","total","truncated"],"additionalProperties":false},"sourceRefreshStatus":{"type":"string","const":"not_attested"},"updatedAt":{"type":"string"},"profileUrl":{"type":"string"},"evidenceUrl":{"type":"string"},"ownerActionUrl":{"type":"string"},"ownerAction":{"type":"string"}},"required":["schemaVersion","evidenceNote","name","state","city","credentials","credentialWindow","sourceRefreshStatus","updatedAt","profileUrl","evidenceUrl","ownerActionUrl","ownerAction"],"additionalProperties":false},"SourceLedger":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schemaVersion":{"type":"string","const":"1.2"},"evaluatedAt":{"type":"string"},"healthAvailable":{"type":"boolean"},"evidenceNote":{"type":"string"},"documentationUrl":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"authorityId":{"type":"string"},"jurisdiction":{"type":"string"},"authority":{"type":"string"},"authorityLookupUrl":{"type":"string"},"configuredSourceUrl":{"type":"string"},"credentialKinds":{"type":"array","items":{"type":"string"}},"adapterAvailable":{"type":"boolean"},"configuredCadence":{"type":"string","enum":["daily","weekly","monthly"]},"refreshStatus":{"type":"string","const":"not_attested"},"lastCompletedSnapshotAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"snapshotStatus":{"type":"string","enum":["unknown","observed","overdue","failed"]},"sourceObservation":{"anyOf":[{"type":"object","properties":{"snapshotId":{"type":"string"},"observedAt":{"type":"string"},"sourceReportedUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceReportedDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"staleAfter":{"type":"string"},"records":{"type":"number"},"transport":{"type":"string","enum":["https","chromium","browserbase"]}},"required":["snapshotId","observedAt","sourceReportedUpdatedAt","sourceReportedDate","staleAfter","records","transport"],"additionalProperties":false},{"type":"null"}]},"lastMetadataCheck":{"anyOf":[{"type":"object","properties":{"checkedAt":{"type":"string"},"outcome":{"type":"string","enum":["checked","failed"]},"sourceChangeIndicated":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"sourceReportedDate":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["checkedAt","outcome","sourceChangeIndicated","sourceReportedDate"],"additionalProperties":false},{"type":"null"}]},"profileProjectionStatus":{"type":"string","const":"not_connected"},"scope":{"type":"string"},"limitation":{"type":"string"},"documentationUrl":{"type":"string"}},"required":["key","authorityId","jurisdiction","authority","authorityLookupUrl","configuredSourceUrl","credentialKinds","adapterAvailable","configuredCadence","refreshStatus","lastCompletedSnapshotAt","snapshotStatus","sourceObservation","lastMetadataCheck","profileProjectionStatus","scope","limitation","documentationUrl"],"additionalProperties":false}}},"required":["schemaVersion","evaluatedAt","healthAvailable","evidenceNote","documentationUrl","sources"],"additionalProperties":false},"Error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{"type":"array","items":{}}},"required":["error"],"additionalProperties":false}}}}