Licensy API

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.

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 all 9 tools, 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 9 tools are exposed as plain JSON HTTP endpoints. The Quickstart below shows the three-line Python / TypeScript / curl path.

Developer tier: 1,000 calls / month, all 50 states + DC, current license status. See pricing for paid-tier limits.

What can I build?

Four common Licensy workflows. The API and SDKs make each one trivial to compose.

# Hospital onboarding 200 physicians — verify their CA + NY licenses
for npi in roster_npis:
    licenses = client.list_physician_licenses(npi=npi)
    active = [l for l in licenses if l.license_active]
    flag_missing(npi, expected_states={"CA","NY"} - {l.state for l in active})

# One-time setup
client.subscribe_to_changes(
    npis=current_credentialed_physicians,
    webhook_url="https://your-app.com/webhooks/licensy",
)

# Then in your webhook handler:
def on_status_change(event):
    if event["event"] == "status_change":
        page_compliance_team(event["npi"], event["license"]["status"])
    elif event["event"] == "expiration_warning_60d":
        email_provider_to_renew(event["npi"])

# Quarterly retrospective audit
result = client.get_license_history(
    npi="1700013174", state="CA",
    as_of_date="2024-08-12",
)
if result.status != "active":
    flag_for_review(npi, billed_procedure_id, result)

# And a notarized screenshot of the source:
screenshot_url = client.get_screenshot_url(
    npi="1700013174", state="CA",
)
attach_to_audit_record(billed_procedure_id, screenshot_url)

// One config block in Claude Desktop:
{
  "mcpServers": {
    "licensy": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
               "https://mcp.licensy.ai/mcp",
               "--header", "Authorization: Bearer YOUR_KEY"]
    }
  }
}

// Then ask Claude in chat:
// "Verify Dr. Smith NPI 1700013174 across CA, NY, TX"
// Claude calls bulk_verify under the hood and quotes the answer.

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

npm install @licensyai/sdk

Quickstart

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

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}")

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 -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.

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:

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.

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.

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

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()
  }
)

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:

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.