API Reference

ClaimLens API

Programmatic access to AI-powered clinical code extraction. Available on Pro and Practice plans.

Authentication

All API requests require a Bearer token in the Authorization header. API keys use the cl_live_ prefix and can be generated from the Dashboard API tab.

Authorization: Bearer cl_live_your_api_key_here

Keep your API key secret. Do not expose it in client-side code or public repositories. If compromised, revoke it immediately from the Dashboard and generate a new one.

Endpoint

POSThttps://www.claimlens.app/api/v1/extract

Submit a clinical note for code extraction. Returns CPT, ICD-10, E/M, HCPCS codes, modifiers, and reimbursement estimates.

Request Body

Send a JSON body with the following fields:

Field	Type	Required	Description
`note`	`string`	required	The clinical note text to extract codes from. Supports SOAP notes, H&P, progress notes.
`payer`	`string`	optional	Payer type. One of: `medicare`, `medicaid`, `commercial`, `selfpay` (or `self_pay`). Defaults to `medicare`.
`patient_type`	`string`	optional	One of: `established`, `new`. Defaults to `established`.
`visit_type`	`string`	optional	One of: `office`, `telehealth`, `awv`, `well_child`, `behavioral`, `bh`, `nursing_facility`, `emergency_dept`, `ed`, `telehealth_bh`, `home`. Defaults to `office`.
`specialty`	`string`	optional	One of: `family_medicine`, `internal_medicine`, `pediatrics`, `behavioral_health`. Defaults to `family_medicine`.
`phi_scrub`	`boolean`	optional	Enable server-side PHI scrubbing before processing. Defaults to `true`.

Response Schema

Successful responses return HTTP 200 with the following JSON structure. Each code array contains objects with code, descriptor, justification, estimated_rvu, and billing_tier fields:

{
  "result": {
    "em_codes": [
      { "code": "99214", "descriptor": "Office visit, est, mod complexity",
         "justification": "Moderate MDM with Rx changes",
         "estimated_rvu": 1.92, "billing_tier": "billable" }
    ],
    "icd10_codes": [
      { "code": "E11.65", "descriptor": "T2DM with hyperglycemia",
         "justification": "A1C 8.3%", "billing_tier": "billable" },
      { "code": "I10", "descriptor": "Essential hypertension",
         "billing_tier": "billable" }
    ],
    "cpt_codes":    [],
    "hcpcs_codes":  [
      { "code": "G2211", "descriptor": "Complexity add-on",
         "estimated_rvu": 0.33, "billing_tier": "billable" }
    ],
    "quality_codes": [],
    "optimization_tips": ["Consider adding tobacco cessation code 99407"],
    "denial_risks": [
      { "code": "G2211", "risk_level": "Medium",
         "reason": "Requires longitudinal relationship documentation" }
    ]
  },
  "meta": {
    "model":        "claude-sonnet-4-6",
    "payer":        "medicare",
    "patient_type": "established",
    "visit_type":   "office",
    "specialty":    "family_medicine",
    "phi_scrubbed": true
  }
}

Code Examples

cURL

curl -X POST https://www.claimlens.app/api/v1/extract \
  -H "Authorization: Bearer cl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "CC: Follow-up HTN and DM type 2. BP 142/88...",
    "payer": "medicare",
    "patient_type": "established",
    "visit_type": "office",
    "specialty": "family_medicine",
    "phi_scrub": true
  }'

Python

import requests

response = requests.post(
    "https://www.claimlens.app/api/v1/extract",
    headers={{
        "Authorization": "Bearer cl_live_your_api_key",
        "Content-Type": "application/json"
    }},
    json={{
        "note": "CC: Follow-up HTN and DM type 2. BP 142/88...",
        "payer": "medicare",
        "patient_type": "established",
        "phi_scrub": True
    }}
)

data = response.json()
print(data["result"]["em_codes"])    # ["99214"]
print(data["result"]["icd10_codes"]) # ["E11.22", "I12.9", ...]

JavaScript (fetch)

const response = await fetch("https://www.claimlens.app/api/v1/extract", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  }},
  body: JSON.stringify({
    note: "CC: Follow-up HTN and DM type 2. BP 142/88...",
    payer: "medicare",
    patient_type: "established",
    phi_scrub: true
  }})
});

const data = await response.json();
console.log(data.result.em_codes);    // ["99214"]
console.log(data.result.icd10_codes); // ["E11.22", "I12.9", ...]

Rate Limits

API rate limits are enforced per calendar month based on your plan. The counter resets on the 1st of each month.

Plan	Monthly Limit
Pro	1,000 requests/month
Practice	5,000 requests/month

When your monthly limit is reached, the API returns 429 with a reset_at timestamp in the response body indicating when the counter resets.

Error Codes

All errors return a JSON body with error and message fields:

{
  "error":   "missing_note",
  "message": "The 'note' field is required"
}

HTTP	Error Code	Description
`400`	`missing_note`	The `note` field is missing or empty in the request body.
`400`	`note_too_long`	Note exceeds the 50,000 character limit.
`401`	—	Missing or invalid API key. Keys must use the `cl_live_` prefix.
`403`	—	API access requires a Pro or Practice plan. Upgrade at /pricing.
`429`	`rate_limit_exceeded`	Monthly API limit reached. Response includes `reset_at` timestamp. Pro: 1,000/month, Practice: 5,000/month.
`502`	`parse_error`	The AI model returned a response that could not be parsed. Retry the request.
`500`	`internal_error`	An unexpected server error occurred. If persistent, contact support@claimlens.app.

Ready to integrate?

Generate your API key from the Dashboard to get started.

Go to Dashboard