licenscheck

API docs

The licenscheck API

One base URL, JSON everywhere, no SDK needed.

https://api.licenscheck.com

The full reference, generated from the API itself, is at api.licenscheck.com/docs (try requests in the browser) and api.licenscheck.com/redoc.

Authentication

Most endpoints need no key. The verdict and the link graph need one, sent as a Bearer token:

Authorization: Bearer lc_live_…

Keys are shown once when issued; we store only a hash of each. To get one, email support@licenscheck.com. A wrong or revoked key is refused with a 401 on every endpoint, even the free ones, so you notice a problem right away.

Endpoints

EndpointKeyWhat it returns
GET /licenses?q=NoSearch by name, DBA or license number (3-100 characters). Optional state (FL, CA, WA), limit (1-100, default 20), offset. A state alone can't list licenses.
GET /licenses/{id}NoOne license's board record: status, dates, bond, address, phone, principal, and delisted_at if the board stopped listing it.
GET /licenses/{id}/classificationsNoEvery trade classification held under the license (CA licenses often hold several).
GET /licenses/{id}/continuing-educationNoContinuing-education courses completed, most recent first (FL).
GET /licenses/{id}/link-summaryNoHow many other licenses, in how many states, are linked to the same contractor. Counts only.
GET /licenses/{id}/verdictYesClear, Review or Risk, with each check behind it.
GET /licenses/{id}/graphYesEvery linked license, its match confidence and evidence, and unconfirmed possible matches.
GET /statsNoHow many licenses are on file.

A license's id doesn't change when the board data refreshes, so it's safe to store.

Examples

Search

curl "https://api.licenscheck.com/licenses?q=southern%20folger&state=CA"

Verify a license

curl -H "Authorization: Bearer $LICENSCHECK_KEY" \
  https://api.licenscheck.com/licenses/3a5cdcae-1af7-5c92-89d2-46fc2e0722af/verdict
{
  "license_id": "3a5cdcae-1af7-5c92-89d2-46fc2e0722af",
  "level": "risk",
  "word": "Risk found",
  "summary": "Active in California, but a linked Washington license is suspended.",
  "checks": [
    {"label": "Board status", "outcome": "pass", "text": "Active as reported by the CA board.", "segments": […]},
    {"label": "Expiration", "outcome": "pass", "text": "Valid through Jul 31, 2028 (in 1.8 yr).", "segments": […]},
    {"label": "Surety bond", "outcome": "pass", "text": "$25,000 bond on file (#100504856).", "segments": […]},
    {"label": "Linked licenses", "outcome": "fail", "text": "Suspended in Washington: SOUTHERN FOLGER CONTRNG INC. 1 linked license in WA.", "segments": […]},
    {"label": "Licensing history", "outcome": "info", "text": "First issued Jul 13, 2020 (6.2 yr ago).", "segments": […]}
  ]
}

level is clear, review or risk. Any failed check makes it Risk; otherwise any warning makes it Review. Each check's outcome is pass, warn, fail or info; text is plain text, and segments is the same text with the words to emphasize marked. An unconfirmed possible match can raise a verdict to Review, never to Risk.

Rate limits

CallerPer minutePer day (UTC)
No key (per IP address)601,000
API key30050,000

Over a limit, the API answers 429 with a Retry-After header saying how many seconds to wait. Refused requests don't count against you.

Errors

StatusMeaning
401The endpoint needs a key, or the key sent is wrong or revoked.
404No license has that id.
422A parameter is invalid, e.g. a search term under 3 characters or an unknown state. The body says which.
429Rate limit reached; retry after Retry-After seconds.

About the data