Reference

API reference

Every endpoint below is generated from the same catalog the API serves — this page can’t drift from what’s actually deployed. Machine-readable versions: /api/openapi and /llms.txt.

Base URL

https://patientary.com/api/v1

Auth

Optional. Send `Authorization: Bearer ptn_live_…` for higher limits. Anonymous calls are rate-limited by IP.

Sources

CMS NPPES registry (providers, live) + the official CMS ICD-10-CM release + NUCC taxonomy.

Response envelope

Every successful response includes a request_id for tracing and a disclaimer. Free-tier responses also carry an attribution field (Pro and Scale drop it).

{
  "request_id": "req_9f3ac1d0",
  // ...endpoint-specific fields (npi / code / results / matches)...
  "disclaimer": "Patientary is an informational reference tool built on public data (CMS NPPES and the offi...",
  "attribution": "Data via patientary.com (free tier only)"
}

Errors

Structured, never silent

Every non-2xx response is JSON — never a fabricated fallback.

code	status	meaning
invalid_request	400	A required parameter is missing or malformed (e.g. a non-numeric NPI).
unauthorized	401	The Authorization header is missing a valid, unrevoked API key for an endpoint that requires one.
not_found	404	No record exists for the given NPI, ICD-10 code or taxonomy code.
rate_limited	429	You've exceeded your plan's per-minute burst rate or monthly call allotment.
not_configured	503	A required upstream credential isn't configured on our side. Returned instead of fabricated data — never a silent fallback.
upstream_unavailable / upstream_timeout	502 / 504	CMS NPPES or another upstream source didn't respond in time. Safe to retry with backoff.
internal	500	An unexpected server error. Safe to retry; contact support if it persists.

error response

{
  "request_id": "req_9f3ac1d1",
  "error": {
    "code": "not_found",
    "message": "No provider found for NPI 1999999999."
  }
}

Rate limits

By plan

Tier	Burst	Volume	Batch
Anonymous	6/min	100/day	Not available
Free	10/min	3,000/mo	Single lookups only
Pro	120/min	50,000/mo	Up to 100/call
Scale	600/min	500,000/mo	Up to 1000/call

Full plan details at /pricing.

Endpoints

Every route

GET

/api/v1/npi/{npi}

Look up a single provider by NPI number (live CMS NPPES data).

Param	In	Required	Description
npi	path	yes	10-digit National Provider Identifier.

curl https://patientary.com/api/v1/npi/1245319599

GET

/api/v1/npi

Search the NPPES registry by name, organization, taxonomy or location.

Param	In	Required	Description
first_name	query	no	Individual first name.
last_name	query	no	Individual last name.
organization	query	no	Organization name.
taxonomy	query	no	Provider taxonomy / specialty description.
city	query	no	City (pair with state).
state	query	no	Two-letter state code.
postal_code	query	no	5- or 9-digit ZIP.
limit	query	no	Max results (1–200, default 20).

curl "https://patientary.com/api/v1/npi?last_name=smith&state=CA&taxonomy=cardiology"

GET

/api/v1/icd10/{code}

Get one ICD-10-CM code with chapter, billable status, parent and children.

Param	In	Required	Description
code	path	yes	ICD-10-CM code, e.g. E11.9 (dot optional).
crosswalk	query	no	1 to include the full code family (Pro).

curl https://patientary.com/api/v1/icd10/E11.9

GET

/api/v1/icd10

Search ICD-10-CM by code prefix or clinical description.

Param	In	Required	Description
q	query	yes	A code (E11) or a description (type 2 diabetes).
billable	query	no	1 to return only billable (leaf) codes.
limit	query	no	Max results (1–100, default 20).

curl "https://patientary.com/api/v1/icd10?q=type%202%20diabetes&billable=1"

GET

/api/v1/taxonomy

Look up or search NUCC provider-taxonomy (specialty) codes.

Param	In	Required	Description
q	query	no	Specialty term, e.g. cardiology.
code	query	no	A taxonomy code, e.g. 207Q00000X.

curl "https://patientary.com/api/v1/taxonomy?q=family%20medicine"

POST

/api/v1/validate

Requires paid key for batch

Batch-validate NPIs and ICD-10 codes in one call (claim scrubbing).

Param	In	Required	Description
npis	body	no	Array of NPI numbers to validate.
icd10	body	no	Array of ICD-10 codes to validate.

curl -X POST https://patientary.com/api/v1/validate -H "Content-Type: application/json" -d '{"npis":["1245319599"],"icd10":["E11.9","Z00.00"]}'

Patientary is an informational reference tool built on public data (CMS NPPES and the official ICD-10-CM release). It is not medical, coding, legal or billing advice, and code assignment is the responsibility of a qualified professional. Always verify against the primary source before you bill or file.