Skip to content

Developer documentation

Licensy API

Standardized U.S. physician and physician assistant licensing data across all 50 states + DC, sourced from official public records. Build licensing workflows with three lines of code.

Authentication

The Licensy API uses bearer-token authentication. Pass your API key in the Authorization header with the Bearer prefix on every request.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys carry production-grade access. Keep them in environment variables — never commit them to source control or include them in client-side JavaScript shipped to browsers.

Developer preview

Try it in your AI client

Licensy speaks the Model Context Protocol (MCP), so any MCP-compatible AI tool can call it directly. Pick your client below — you'll be running real license lookups inside Claude / Cursor / VS Code in about 60 seconds.

What you need first: a Licensy account for your bearer token. Sign up at licensy.ai/signup.

To get your token: log into the dashboard, open Overview, and click the copy-to-clipboard button next to "API Key". This is a stable, long-lived token — paste it into Claude Desktop / Cursor configs and it stays valid for months, not hours.

Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config. Add the Licensy block:

{
  "mcpServers": {
    "licensy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.licensy.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

Restart Claude. You'll see a 🔌 plugin indicator at the bottom of the chat. Try: "Is Dr. Steven Winiarski's California license active? NPI 1700013174." Claude will call verify_license under the hood and quote the answer with the state board as source.

Cursor / VS Code (Claude integration)

Cursor and the VS Code Claude extension use the same mcpServers config shape. Open the MCP settings panel and paste the same JSON block above. The plugin will auto-connect on next launch.

Same config works for any MCP-compatible client — Zed, Cline, Continue.dev, and others. The transport is the standard Streamable HTTP MCP spec; no Licensy-specific shim required.

MCP Inspector (for developers)

Want to poke at the protocol surface directly? The official MCP Inspector gives you a browser UI for tools, resources, and prompts. No install needed:

npx @modelcontextprotocol/inspector https://mcp.licensy.ai/mcp

The Inspector opens at http://localhost:6274. In the auth panel, paste your Bearer token, then "Connect". You'll see the tools listed below, click any of them, fill the form, and watch the raw JSON-RPC round-trip.

Or skip MCP — just use the REST API

If you're not building an AI integration, the same tools are exposed as plain JSON HTTP endpoints. The Quickstart below shows the three-line Python / TypeScript / curl path.

API call limits depend on your plan and are shown in your dashboard usage meter. See pricing for plans.

Install

Both SDKs are on the public package registries — installable in one command, with TypeScript types and async/await on the JS side, and full typed responses + httpx under the hood on the Python side.

pip install licensy

Python 3.9+. Async client also available via AsyncLicensyClient.

npm install @licensyai/sdk

Node 18+ (uses built-in fetch). ESM + CJS both shipped; works in modern browsers.

Quickstart

Verify a physician's California license in three lines. Replacesk_live_...with your real API key from the dashboard.

Python
from licensy import LicensyClient

client = LicensyClient(api_key="sk_live_...")

result = client.verify_license(npi="1700013174", state="CA")
if result.license_active:
    print(f"Active through {result.expiration_date}")
else:
    print(f"Inactive: {result.status}")
TypeScript
import { LicensyClient } from '@licensyai/sdk'

const client = new LicensyClient({ apiKey: 'sk_live_...' })

const result = await client.verifyLicense({
  npi: '1700013174',
  state: 'CA',
})
if (result.licenseActive) {
  console.log(`Active through ${result.expirationDate}`)
} else {
  console.log(`Inactive: ${result.status}`)
}
curl
curl -X POST https://mcp.licensy.ai/api/v1/tools/verify_license \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"npi": "1700013174", "state": "CA"}'

Errors

The API returns standard HTTP status codes. Error bodies are JSON with a stable code and a human-readable message. Both SDKs map these to typed exceptions you can catch directly.

StatusExceptionMeaning
401AuthErrorAPI key missing, malformed, or revoked
403TierUpgradeRequiredTool requires a higher tier; required_tier field tells you which
404NotFoundErrorNo license exists for the (NPI, state) lookup
422ValidationErrorInput rejected; details says which field
429RateLimitErrorExceeded per-minute or per-day budget; Retry-After header tells you when to retry
5xxLicensyErrorUpstream issue on our side; retry with backoff

Rate limits

Rate limits apply per API key. The exact ceilings depend on your tier; see the pricing page for current numbers.

Every response includes rate-limit headers so you never have to guess where you stand:

HeaderMeaning
X-RateLimit-LimitTotal requests permitted in the current window
X-RateLimit-RemainingRequests you have left before the window resets
X-RateLimit-ResetUnix timestamp (seconds) when the window resets
Retry-AfterOn 429: seconds to wait before your next request will succeed

Both SDKs surface Retry-After via typed error fields: RateLimitError.retry_after_seconds (Python) / RateLimitError.retryAfterSeconds (TypeScript). Both also expose .limit_remaining / .limitRemaining on every successful response so you can throttle pre-emptively.

Recommended client behavior: retry on 429 with exponential backoff seeded by the Retry-After value. Never retry on 401/403/404/422 — those are permanent for that request.

Try it in Postman

Download collection ↓

One-click Postman v2.1 collection covering 21 endpoints across the playground, reports, /me, and public APIs. Set the apiKey variable to your credential_key and start hitting endpoints in 30 seconds. Always reflects the current production API — re-download anytime.

Prefer raw OpenAPI? openapi.json · Swagger UI: https://api.licensy.ai/docs · ReDoc: https://api.licensy.ai/redoc

Tool reference

Every tool is documented with its parameters, response shape, and code samples in Python, TypeScript, and curl.

verify_license

Free tier

Verify a single physician's license in a single state. Most common call shape.

Parameters

npistringoptional

10-digit NPI (preferred input).

statestringrequired

2-letter code ("CA") or full name ("California").

license_numberstringoptional

Use when NPI isn't known.

license_typestringoptional

Optional credential filter — MD, DO, PA, etc.

Response shape

{
  "status": "active",
  "state": "California",
  "expiration_date": "2027-09-30",
  "license_active": true,
  "license_number": "C12345",
  "board_source": "Medical Board of California",
  "last_refreshed_at": "2026-06-09T05:00:00Z"
}

Example call

result = client.verify_license(npi="1700013174", state="CA")
print(result.status, result.expiration_date)

list_physician_licenses

Free tier

Return every license Licensy has on file for one NPI — one entry per state.

Parameters

npistringrequired

The physician's 10-digit NPI.

include_inactivebooleanoptional

When true, also include expired/lapsed licenses. Default false.

Response shape

{
  "npi": "1700013174",
  "licenses": [
    {
      "state": "CA",
      "status": "active",
      "expiration_date": "2027-09-30",
      "license_active": true
    },
    {
      "state": "NY",
      "status": "active",
      "expiration_date": "2026-12-31",
      "license_active": true
    }
  ]
}

Example call

result = client.list_physician_licenses(npi="1700013174")
for license in result:
    print(license.state, license.status)
print(f"{result.active_count} active total")

get_license_status

Free tier

Return just the status word — the cheapest call. Useful for routing logic that needs a yes/no decision.

Parameters

npistringrequired

The physician's 10-digit NPI.

statestringrequired

2-letter code or full state name.

Response shape

{
  "status": "active"
}

Example call

status = client.get_license_status(npi="1700013174", state="CA")
# Returns "active", "expired", "suspended", "not_found", etc.

get_screenshot_url

Paid tier

Get a 15-minute signed URL to an evidence image of the board record, where available.

Parameters

npistringoptional

Identify the license by NPI + state.

statestringoptional

2-letter code or full state name.

license_idstringoptional

Alternative: pass the Licensy license_id directly.

Response shape

{
  "screenshot_url": "https://screenshots.licensy.ai/sig?...",
  "expires_at": "2026-06-09T22:15:00Z"
}

Example call

url = client.get_screenshot_url(npi="1700013174", state="CA")
# Download or embed within 15 minutes

bulk_verify

Paid tier

Verify many (NPI, state) pairs in one call. Returned in input order. Paid plans max 100/call, Enterprise max 1000/call.

Parameters

licensesarrayrequired

Array of { npi, state } pairs to verify.

Response shape

{
  "results": [
    {
      "status": "active",
      "state": "CA",
      "expiration_date": "2027-09-30",
      "license_active": true
    },
    {
      "status": "expired",
      "state": "NY",
      "expiration_date": "2025-12-31",
      "license_active": false
    }
  ]
}

Example call

results = client.bulk_verify([
    {"npi": "1700013174", "state": "CA"},
    {"npi": "1700013174", "state": "NY"},
])
for r in results:
    print(r.state, r.status)

search_disciplinary_actions

Paid tier

Find known disciplinary actions (suspension, revocation, surrender, probation, reprimand) against a physician.

Parameters

npistringoptional

Search by NPI.

namestringoptional

Or search by full name.

statestringoptional

Restrict results to a single state.

Response shape

{
  "actions": [
    {
      "state": "CA",
      "action_type": "suspension",
      "date": "2023-05-12",
      "source_url": "https://board.example/action/12345"
    }
  ]
}

Example call

actions = client.search_disciplinary_actions(npi="1700013174")
for a in actions:
    print(a.state, a.action_type, a.date)

get_license_history

Paid tier

Point-in-time license status lookup. Answer 'was Dr. X licensed in California on date Y?' for any date back to when we started capturing snapshots.

Parameters

npistringrequired

10-digit NPI.

statestringrequired

2-letter code or full state name.

as_of_datestring (YYYY-MM-DD)required

The date to query against.

Response shape

{
  "status": "active",
  "as_of_date": "2024-08-12",
  "coverage_start": "2026-06-05",
  "coverage_note": "Snapshot coverage starts 2026-06-05. Earlier dates fall back to issuance-date heuristic."
}

Example call

result = client.get_license_history(
    npi="1700013174",
    state="CA",
    as_of_date="2024-08-12",
)
print(result.status)

subscribe_to_changes

Paid tier

Subscribe a webhook URL to license-change events. We'll POST a signed JSON message to your URL within minutes of detecting any matching change.

Parameters

npisarray of stringrequired

NPIs to watch.

webhook_urlstringrequired

HTTPS endpoint we should POST events to.

eventsarray of stringoptional

Filter to specific event types. Empty/omitted = all events. Known events: status_change, expiration_warning_60d, new_disciplinary_action.

Response shape

{
  "subscription_id": "sub_xxxxxxxxxxx",
  "expires_at": "2027-06-09T00:00:00Z",
  "note": "HMAC signing secret (store this — it will not be shown again): wK3pX9... Verify each delivery via the X-Licensy-Signature header."
}

Example call

sub = client.subscribe_to_changes(
    npis=["1700013174", "1234567890"],
    webhook_url="https://your-app.com/webhooks/licensy",
)
# Store sub.note — it contains the HMAC signing secret

unsubscribe

Paid tier

Cancel an active subscription. Idempotent — calling it on a missing or already-cancelled subscription returns success.

Parameters

subscription_idstringrequired

The subscription_id returned from subscribe_to_changes.

Response shape

{
  "success": true
}

Example call

client.unsubscribe(subscription_id="sub_xxxxxxxxxxx")

Exclusions (OIG LEIE)

Returns the latest OIG LEIE exclusion result for one of your reports. Covers the OIG LEIE only. Doesn't include SAM.gov, state Medicaid lists or DEA.

GEThttps://api.licensy.ai/api/v2/reports/{report_id}/exclusions

Result states

excluded

Listed on the OIG LEIE (NPI match). (a listing in effect matched the NPI exactly, with no waiver)

ambiguous

Possible match on name only. Needs human review. (no evidence row has a listed NPI or a waiver)

Possible match. Needs human review. (an evidence row has a listed NPI or a waiver)

not_excluded

A matching LEIE record is no longer in effect (ended or reinstated). Needs human review. (a record matched but none is still in effect; the ended listing is in notes)

not_found

No match found in the OIG LEIE (<source date>). (the search ran on current data and no record matched)

source_unavailable

Exclusion check unavailable. Try again later. (reason is no_source, stale_source or lookup_failed)

latest: null

Exclusion check not yet run. (the MCP tool sends status not_screened instead)

status is one of the five values above; latest is null until a check has run. not_excluded and not_found are both completed checks: don't treat either as a failure, and don't merge them.

A source failure comes back as HTTP 200 with source_unavailable and a reason: no_source (no LEIE file loaded yet), stale_source (the last full file was loaded more than 40 days ago) or lookup_failed (the search itself failed). All three mean the same thing to a reader: no result. Treat a timeout, a network error or a 5xx the same way. Don't report source_unavailable or a null latest as not_found: no result came back.

Listing details (listed_name, listed_npi, exclusion_date, reinstatement_date, waiver_date) are on the items of evidence for excluded and ambiguous, and of notes for records that are no longer in effect. A check can have several rows in either list, and an excluded or ambiguous check can have notes too. Show every row, not just the first; evidence is already ordered with the strongest match first.

When you show a result, show where it came from:

Exclusion status checked against the HHS-OIG List of Excluded Individuals/Entities (LEIE), <source date>, checked <verified_at>.

<source date> is "file dated <date>" from source_file_date: the LEIE file's own date (YYYY-MM-DD). The key is always present on a check and on every evidence and notes row, and is null when the date is unknown. When it is null, use "retrieved <date>" from source_retrieved_at (when the file was last fetched from OIG) instead. When both are null, say "(date unavailable)"; don't derive a date from source_ingested_at (the load time) or a file name. A row's date can differ from the check's. <verified_at> is the time of the check. In the no-match line, "(date unavailable)" takes the place of "(<source date>)": one pair of parentheses, not two.

GET https://api.licensy.ai/api/v2/exclusions/status returns enabled. When it is false the feature is off and the report endpoint answers 404.

Result fields

source_file_datestring (YYYY-MM-DD), nullable

The LEIE file's own date.

source_retrieved_atstring (ISO-8601 UTC), nullable

The last successful fetch of the full LEIE file from OIG, whether the bytes changed or not.

stale_at_readboolean

True when GET/MCP/PDF overlaid source_unavailable / stale_source because source_retrieved_at is now more than 40 days old.

review_reasonstring, nullable

source_file_old or null. Does not change status.

Extra flag for a human reviewer; it never changes status. source_file_old: source_file_date is more than 75 days old (the search ran, against a file OIG has not replaced for that long). Evaluated when the check ran and again when it is read. Null otherwise, including when source_file_date is null (unknown is not old).

previous_statusstring, nullable

The overlaid response has stale_at_read=true, the stored status in previous_status.

Example call

curl https://api.licensy.ai/api/v2/reports/$REPORT_ID/exclusions \
  -H "Authorization: Bearer $LICENSY_API_KEY"

Response shape

{
  "report_id": "aaaa0001-0000-4000-8000-00000000000a",
  "provider": {
    "name": "Avery Quinn Placeholder",
    "npi": "1900000001"
  },
  "latest": {
    "status": "excluded",
    "reason": null,
    "review_reason": null,
    "previous_status": null,
    "confidence": 1,
    "requires_human_confirmation": false,
    "verified_at": "2026-11-10T18:01:00+00:00",
    "source_url": "https://exclusions.oig.hhs.gov/",
    "source_ingested_at": "2026-11-10T12:00:00+00:00",
    "source_file_date": "2026-11-09",
    "source_retrieved_at": "2026-11-10T15:00:00+00:00",
    "stale_at_read": false,
    "sources_screened": [
      "oig_leie"
    ],
    "evidence": [
      {
        "source": "oig_leie",
        "status": "excluded",
        "requires_human_confirmation": false,
        "listed_name": "AVERY QUINN PLACEHOLDER",
        "listed_npi": "1900000001",
        "listed_state": "CA",
        "exclusion_type": "1128b4",
        "exclusion_date": "2024-01-15",
        "reinstatement_date": null,
        "waiver_date": null,
        "waiver_state": null,
        "source_file_date": "2026-11-09",
        "source_retrieved_at": "2026-11-10T15:00:00+00:00",
        "verified_at": "2026-11-10T18:01:00+00:00",
        "source_url": "https://exclusions.oig.hhs.gov/"
      }
    ],
    "notes": [],
    "stale": false
  },
  "history": []
}

get_exclusion_status

MCP tool, read-only: the latest stored OIG LEIE exclusion result for a report. It never runs a new check. Call it with a JSON-RPC tools/call request to POST https://api.licensy.ai/api/v2/mcp. status is excluded, ambiguous, not_excluded, not_found or source_unavailable, with the same meanings as the REST endpoint above, or not_screened when no check has run. The result is flat: there is no latest wrapper. Covers the OIG LEIE only. Doesn't include SAM.gov, state Medicaid lists or DEA.

Parameters

report_idstringrequired

ID of one of your reports. This is the only argument; the tool does not take date_of_birth, and any extra argument is rejected.

get_exclusion_status result fields

source_file_datestring (YYYY-MM-DD), nullable

The LEIE file's own date.

source_retrieved_atstring (ISO-8601 UTC), nullable

The last successful fetch of the full LEIE file from OIG, whether the bytes changed or not.

stale_at_readboolean

True when GET/MCP/PDF overlaid source_unavailable / stale_source because source_retrieved_at is now more than 40 days old.

review_reasonstring, nullable

source_file_old or null. Does not change status.

Extra flag for a human reviewer; it never changes status. source_file_old: source_file_date is more than 75 days old (the search ran, against a file OIG has not replaced for that long). Evaluated when the check ran and again when it is read. Null otherwise, including when source_file_date is null (unknown is not old).

previous_statusstring, nullable

The overlaid response has stale_at_read=true, the stored status in previous_status.

Response shape

{
  "success": true,
  "request_id": "0123456789abcdef0123456789abcdef",
  "report_id": "aaaa0001-0000-4000-8000-00000000000a",
  "provider": {
    "name": "Avery Quinn Placeholder",
    "npi": "1900000001"
  },
  "status": "excluded",
  "reason": null,
  "review_reason": null,
  "previous_status": null,
  "confidence": 1,
  "requires_human_confirmation": false,
  "verified_at": "2026-11-10T18:01:00+00:00",
  "source_url": "https://exclusions.oig.hhs.gov/",
  "source_ingested_at": "2026-11-10T12:00:00+00:00",
  "source_file_date": "2026-11-09",
  "source_retrieved_at": "2026-11-10T15:00:00+00:00",
  "stale_at_read": false,
  "sources_screened": [
    "oig_leie"
  ],
  "evidence": [
    {
      "source": "oig_leie",
      "status": "excluded",
      "requires_human_confirmation": false,
      "listed_name": "AVERY QUINN PLACEHOLDER",
      "listed_npi": "1900000001",
      "listed_state": "CA",
      "exclusion_type": "1128b4",
      "exclusion_date": "2024-01-15",
      "reinstatement_date": null,
      "waiver_date": null,
      "waiver_state": null,
      "source_file_date": "2026-11-09",
      "source_retrieved_at": "2026-11-10T15:00:00+00:00",
      "verified_at": "2026-11-10T18:01:00+00:00",
      "source_url": "https://exclusions.oig.hhs.gov/"
    }
  ],
  "notes": [],
  "stale": false
}

Example call

import os, requests

resp = requests.post(
    "https://api.licensy.ai/api/v2/mcp",
    headers={"Authorization": "Bearer " + os.environ["LICENSY_API_KEY"]},
    json={"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_exclusion_status","arguments":{"report_id":"aaaa0001-0000-4000-8000-00000000000a"}}},
)
print(resp.json())

Webhook events

Once subscribed, your endpoint receives POST requests within minutes of detected license changes. Every delivery includes an HMAC-SHA256 signature you must verify before trusting the payload.

Event types

  • status_change — any change in the license's status field (e.g. Active → Expired, Active → Suspended)
  • expiration_warning_60d — the license is within 60 days of its expiration date
  • new_disciplinary_action — a new disciplinary action recorded against the physician (coming soon)

Sample payload

{
  "id": "a4f7e2c1-...",
  "event": "status_change",
  "occurred_at": "2026-06-09T05:30:00Z",
  "npi": "1700013174",
  "license": {
    "state": "California",
    "license_number": "C12345",
    "license_type": "MD",
    "status": "expired",
    "expired": "2026-06-08",
    "snapshotted_at": "2026-06-09T05:00:00Z"
  }
}

Signature verification

Every delivery includes an X-Licensy-Signature header in the format sha256=<hex>. Compute the expected signature from the raw request body using HMAC-SHA256 with your subscription's signing secret, then compare with a constant-time comparison.

Python (Flask)
import hmac, hashlib

@app.route('/webhooks/licensy', methods=['POST'])
def webhook():
    sig = request.headers.get('X-Licensy-Signature', '')
    expected = 'sha256=' + hmac.new(
        SIGNING_SECRET.encode(),
        request.get_data(),  # raw bytes — not request.json
        hashlib.sha256,
    ).hexdigest()
    if not hmac.compare_digest(expected, sig):
        return 'invalid signature', 401

    event = request.get_json()
    # ... handle event ...
    return '', 200
TypeScript (Express)
import crypto from 'crypto'

app.post('/webhooks/licensy',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-licensy-signature'] as string
    const expected = 'sha256=' + crypto
      .createHmac('sha256', SIGNING_SECRET)
      .update(req.body)  // raw Buffer
      .digest('hex')
    if (!crypto.timingSafeEqual(
      Buffer.from(sig), Buffer.from(expected)
    )) {
      return res.status(401).send('invalid signature')
    }
    const event = JSON.parse(req.body.toString())
    // ... handle event ...
    res.status(200).send()
  }
)

Generate a snippet with your signing secret pre-filled — paste it into your handler and you're done:

import hmac, hashlib
from flask import request

SIGNING_SECRET = "whsec_paste_your_signing_secret_here"  # from /subscriptions

@app.route('/webhooks/licensy', methods=['POST'])
def webhook():
    sig = request.headers.get('X-Licensy-Signature', '')
    expected = 'sha256=' + hmac.new(
        SIGNING_SECRET.encode(),
        request.get_data(),  # raw bytes — NOT request.json
        hashlib.sha256,
    ).hexdigest()
    if not hmac.compare_digest(expected, sig):
        return 'invalid signature', 401
    event = request.get_json()
    # ... handle event.id / event['event'] / event['license'] ...
    return '', 200

Playground

Paste your API key, pick a tool, fill the inputs, and see the result immediately. No Claude Desktop / Cursor setup needed. Grab your key from your settings page.

Embed a "Verified by Licensy" badge

Medical groups can drop a verification badge onto each physician's bio page in one line. The badge fetches the latest license status from /api/v2/public/badge/{npi} (public, no auth, cached 10 minutes) and links back to Licensy. No API key required.

<!-- Drop this anywhere on the page -->
<script src="https://www.licensy.ai/badge.js" data-npi="1700013174"></script>

<!-- Or, render into a specific target: -->
<span id="licensy-jane"></span>
<script src="https://www.licensy.ai/badge.js"
        data-npi="1700013174"
        data-target="#licensy-jane"></script>

Live preview:

Try 1700013174 (tracked) or any 10-digit number not in the system (you'll get the "not tracked" state).

Retry behavior

Your endpoint should return a 2xx status code within 30 seconds. Any other response or timeout triggers a retry on the following schedule:

  • Attempt 1: immediate
  • Attempt 2: after 5 minutes
  • Attempt 3: after 30 minutes
  • Attempt 4: after 4 hours
  • Attempt 5: after 24 hours

After the 5th failed attempt, the delivery is dead-lettered and you will not receive that event again. Use a stable response handler with proper idempotency — every delivery includes a unique id field you can deduplicate on.