API reference

Overview

All endpoints are mounted under /v1 and return JSON. There is no separate sandbox — every key works against the same live, versioned data CMS publishes.

Authentication

Every request — even against the free tier — needs a valid Sanctum API token in the Authorization header. A missing or invalid token returns 401.

curl https://medicalfeeschedules.com/v1/rates/99213 \
  -H "Authorization: Bearer sk_live_…"

Create an account to get a token.

Rate limits

The API is metered in cost-weighted units, not requests: a single-code (or single-ZIP) lookup costs 1 unit, and a bulk request costs one unit per code/ZIP in the batch — so a 500-code bulk call can't undercut the limit by counting as one request. Both a per-minute burst budget and a per-account daily quota apply, keyed to your account (all of an account's tokens share one quota). Every response carries the current budget in headers; exceeding either limit returns 429 with a Retry-After header.

Historical lookups

Releases are immutable and versioned by (schedule, year, quarter): A = Jan, B = Apr, C = Jul, D = Oct. Every rate and ZIP endpoint accepts either an explicit year+quarter pair or an as_of calendar date (mutually exclusive — supplying both is a 422). Omit both for the current release.

Citations & provenance

Every payable rate (and every resolved ZIP) carries a citations object naming the exact CMS file and row each number came from, plus the arithmetic it was plugged into — enough to defend a number on an appeal without re-deriving it yourself.

{
  "sources": {
    "rvu": {
      "dataset": "rvu",
      "label": "Physician relative value file (PPRRVU)",
      "release": "2026A",
      "cms_page_url": "https://www.cms.gov/medicare/payment/fee-schedules/physician",
      "file": "PPRRVU2026_Jan_nonQPP.csv",
      "row": 4118,
      "values": { "work_rvu": { "value": 1.30 }, "status_code": { "value": "A" } }
    },
    "gpci": {
      "dataset": "gpci",
      "label": "Geographic practice cost indices (GPCI)",
      "release": "2026A",
      "file": "GPCI2026.csv",
      "row": 33,
      "values": { "work_gpci": { "value": 1.045 } }
    }
  },
  "calculation": {
    "formula": "(work_rvu × work_gpci + pe_rvu × pe_gpci + mp_rvu × mp_gpci) × conversion_factor",
    "inputs": { "work_rvu": 1.30, "work_gpci": 1.045, "pe_rvu": 1.02, "pe_gpci": 1.10, "mp_rvu": 0.09, "mp_gpci": 0.98, "conversion_factor": 33.29 }
  }
}

Single rate lookup

Price one HCPCS/CPT code for a locality (or the national amount, if none is given) and setting.

curl "https://medicalfeeschedules.com/v1/rates/99213?locality=01182-18&setting=non_facility" \
  -H "Authorization: Bearer sk_live_…"

{
  "hcpcs": "99213",
  "modifier": null,
  "setting": "non_facility",
  "payable": true,
  "amount": 97.20,
  "gross_amount": 97.20,
  "status_code": "A",
  "sequestration_applied": false,
  "conversion_factor": 33.29,
  "qpp": false,
  "citations": { "sources": { "rvu": { … }, "gpci": { … } }, "calculation": { … } },
  "release": { "schedule": "pfs", "year": 2026, "quarter": "A", "revision": 1 },
  "locality": { "mac": "01182", "code": "18", "state": "CA", "name": "Los Angeles, CA" }
}

Bulk rate lookup

Price up to 500 codes in one request against a shared locality/setting/release context. A code that can't be priced doesn't fail the batch — it comes back with payable: false and a reason.

curl -X POST https://medicalfeeschedules.com/v1/rates/bulk \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"codes": ["99213", "99214-26"], "locality": "01182-18"}'

{
  "release": { "schedule": "pfs", "year": 2026, "quarter": "A", "revision": 1 },
  "locality": { "mac": "01182", "code": "18", "state": "CA", "name": "Los Angeles, CA" },
  "setting": "non_facility",
  "sequestration_requested": false,
  "count": 2,
  "results": [
    { "hcpcs": "99213", "modifier": null, "amount": 97.20, "payable": true, … },
    { "hcpcs": "99214", "modifier": "26", "amount": 135.61, "payable": true, … }
  ]
}

Claim check

Check the lines of one claim (one patient, one date of service) against the rules that only exist between lines: the multiple-procedure reduction (MPPR) ranks the surgical lines and pays 100%/50%/50%…, NCCI procedure-to-procedure (PTP) edits flag pairs that bundle (including whether a 59/X{EPSU} modifier bypasses the edit), and medically unlikely edits (MUE) check units per line or summed per date of service, per each code's adjudication indicator.

PTP and MUE verdicts are edit facts, not deductions — a flagged line keeps its computed amount and the flag says why a payer would deny it. Two releases answer a claim check and both are echoed: the PFS release that priced the lines and the NCCI release that supplied the edits. When no NCCI release covers the period, the edit sections are absent and a warning says so.

curl -X POST https://medicalfeeschedules.com/v1/claims/check \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"lines": [{"code": "27447"}, {"code": "27369", "modifier": "59", "units": 1}], "locality": "01182-18"}'

{
  "release": { "schedule": "pfs", "year": 2026, "quarter": "A", "revision": 1 },
  "ncci_release": { "schedule": "ncci", "year": 2026, "quarter": "A", "revision": 1 },
  "locality": { "mac": "01182", "code": "18", "state": "CA", "name": "Los Angeles, CA" },
  "setting": "non_facility",
  "sequestration_requested": false,
  "count": 2,
  "lines": [
    {
      "line": 0, "hcpcs": "27447", "modifier": null, "units": 1,
      "payable": true, "amount": 1391.42, "gross_amount": 1391.42,
      "rate": { "hcpcs": "27447", "amount": 1391.42, "payable": true, … },
      "mppr": { "rank": 1, "percentage_applied": 1.0, "adjusted_amount": 1391.42, "reduction_applied": false },
      "mue": { "within_limit": true, "limit": 1, "adjudication_indicator": 2, "units_counted": 1, … }
    },
    {
      "line": 1, "hcpcs": "27369", "modifier": "59", "units": 1,
      "payable": true, "amount": 103.55, "gross_amount": 103.55,
      "rate": { "hcpcs": "27369", "amount": 207.10, "gross_amount": 207.10, "payable": true, … },
      "mppr": { "rank": 2, "percentage_applied": 0.5, "base_allowed": 207.10, "adjusted_amount": 103.55, "reduction_applied": true },
      "mue": { … }
    }
  ],
  "ptp_edits": [
    {
      "column1": { "line": 0, "hcpcs": "27447" },
      "column2": { "line": 1, "hcpcs": "27369" },
      "modifier_indicator": "1",
      "bundled": true, "bypassable": true, "billable": true,
      "reason": "Modifier indicator 1: bypassed by modifier 59.",
      "citation": { "file": "ccipra-…csv", "row": 118204, … }
    }
  ]
}

Single ZIP → locality lookup

Resolve a ZIP code to its Medicare payment locality on its own, without also pricing a code — useful for populating a locality picker or validating an address book against the crosswalk. Accepts a bare 5-digit ZIP, a "ZIP+4" (90210-1234 or 902101234), or a separate plus4 parameter.

This differs from passing zip= to the rate endpoints: a rate lookup must reject an ambiguous ZIP outright, because silently picking a locality risks pricing at the wrong rate. This endpoint instead returns the dominant locality with ambiguous: true and a note — a useful answer on its own, honestly labeled.

curl https://medicalfeeschedules.com/v1/zip/90210 \
  -H "Authorization: Bearer sk_live_…"

{
  "status": "exact",
  "input_zip": "90210",
  "zip5": "90210",
  "plus4": null,
  "mac_code": "01182",
  "locality_code": "18",
  "locality": { "id": 1, "name": "Los Angeles, CA", "state": "CA" },
  "ambiguous": false,
  "crosswalk_release": { "year": 2026, "quarter": "A" },
  "reason": null,
  "citations": { "sources": { "zip_locality": { "file": "ZIP5_2026.csv", "row": 4, … } } }
}

Bulk ZIP → locality lookup

Resolve up to 500 ZIPs in one request against a shared crosswalk release. Every entry resolves independently and always comes back in results — an unresolvable ZIP doesn't fail the batch, it comes back with its own status and reason.

curl -X POST https://medicalfeeschedules.com/v1/zip/bulk \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"zips": ["90210", "35801", {"zip": "90211"}]}'

{
  "count": 3,
  "crosswalk_release": { "year": 2026, "quarter": "A" },
  "results": [
    { "status": "exact", "zip5": "90210", "mac_code": "01182", "locality_code": "18", … },
    { "status": "exact", "zip5": "35801", "mac_code": "10112", "locality_code": "00", … },
    { "status": "ambiguous", "zip5": "90211", "mac_code": "01182", "locality_code": "18", … }
  ]
}

Locality directory

Every Medicare payment locality currently defined. The locality field is the composite key the rate endpoints accept.

{
  "count": 112,
  "localities": [
    { "id": 1, "locality": "01182-18", "mac": "01182", "code": "18", "state": "CA", "name": "Los Angeles, CA" }
  ]
}

Release directory

Every (schedule, year, quarter) release published, newest first — including the zip_locality crosswalk releases the ZIP endpoints resolve against.

{
  "count": 6,
  "releases": [
    { "schedule": "pfs", "year": 2026, "quarter": "A", "published_at": "2026-01-01" },
    { "schedule": "zip_locality", "year": 2026, "quarter": "A", "published_at": "2026-01-01" }
  ]
}

Errors

Errors carry a client-safe error or reason string explaining what went wrong — never a bare status code.