Prior authorization requirement for a payer and code
GET /v1/prior-auth
GET https://api.healthcare.dev/v1/prior-authPreview: not available yet (503 dataset-unavailable until it is released). Pro plan and up (below Pro: a few preview calls a month, then 403 plan-upgrade-required). Whether a payer's public prior authorization (precertification) lists require prior authorization for a procedure code (CPT number or HCPCS Level II), per line of business (commercial, medicare_advantage, medicaid; line for one): required, not_required (for example, the payer removed the code from its list), unclear (the list mentions the code in a way our rules can't read reliably, or two of the payer's documents disagree: both are shown in conflicts), or not_listed (none of the payer's lists we hold names the code, which is not proof prior authorization isn't needed). Each answer carries confidence, derivation, evidence (the list and page) and as_of, the effective and end dates the list gives, conditions in plain words, and changes the list announces for later dates. Codes are served as numbers only, never with descriptions. Each account can look up a limited number of different payer and code pairs a day; repeats and failed lookups don't count (429 enumeration-limit past it, until 00:00 UTC). Reference data, not a prior authorization determination. Confirm with the payer.
Requires an API key: Authorization: Bearer hdev_live_.... See Authentication.
Query parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
payer | string | yes | Payer id (aetna, cigna, humana, ...) | cigna |
code | string | yes | CPT code number or HCPCS Level II code | 27447 |
line | "commercial" | "medicare_advantage" | "medicaid" | no | One line of business (default: every line the payer's lists cover) | commercial |
modifier | string | no | Billing modifier, for lists that name one | RT |
view | "compact" | "standard" | "full" | no | How much of each record to return (default full). compact: payer, code, modifier, disclaimer, requirements (fewest tokens, for agents). standard: every field. full: every field. | compact |
fields | string | no | Comma-separated fields to return instead of a view. Valid fields: payer, code, modifier, disclaimer, requirements, lines_available. | payer,code,modifier |
Examples
curl
curl "https://api.healthcare.dev/v1/prior-auth?payer=cigna&code=27447" \
-H "Authorization: Bearer $HDEV_API_KEY"TypeScript
const res = await fetch("https://api.healthcare.dev/v1/prior-auth?payer=cigna&code=27447", {
headers: { Authorization: `Bearer ${process.env.HDEV_API_KEY}` },
});
const { data, meta } = await res.json();Python
import os
import requests
res = requests.get("https://api.healthcare.dev/v1/prior-auth?payer=cigna&code=27447", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()Try it
Response
The payer's requirement for the code, per line of business
{
"data": {
"payer": {
"id": "string",
"name": "string"
},
"code": "string",
"modifier": "string",
"disclaimer": "Reference data, not a prior authorization determination. Confirm with the payer.",
"requirements": [
{
"line": null,
"prior_auth": {
"answer": null,
"confidence": null,
"derivation": null,
"evidence": null,
"as_of": null
},
"codes": [
null
],
"modifier": "string",
"effective_start": "2026-10-01",
"effective_end": "2026-10-01",
"conditions": [
null
],
"upcoming": [
null
],
"conflicts": [
null
],
"note": "string"
}
],
"lines_available": [
"commercial"
]
},
"meta": {
"source": "cms-icd10",
"data_version": "2026.1",
"retrieved_at": "2026-10-24T12:00:00Z",
"license": "Public domain (CMS). Reference data, not medical advice."
},
"links": {
"self": "/v1/prior-auth?payer=cigna&code=27447",
"next": null
}
}Fields
| Field | Type | Always present | Description |
|---|---|---|---|
payer | object | yes | |
code | string | yes | The code asked about, upper case |
modifier | string | null | yes | The modifier asked about, if any |
disclaimer | "Reference data, not a prior authorization determination. Confirm with the payer." | yes | |
requirements | PriorAuthRequirement[] | yes | One per line of business (only line when given), in a fixed order |
lines_available | PriorAuthLine[] | yes | Lines of business we hold this payer's lists for |
Errors
Errors are application/problem+json (RFC 9457). Branch on type, not on title. See Errors.
| Status | type | When |
|---|---|---|
| 400 | invalid-request | A parameter or the body failed validation; errors lists each field. |
| 401 | unauthorized | Missing, malformed or revoked API key. |
| 403 | plan-upgrade-required | The plan doesn't include this feature; required_plan names the plan that does. |
| 404 | not-found | No record with that id (retired records are still returned). |
| 429 | rate-limited / quota-exceeded | Too many requests per second (retry after Retry-After), or the monthly quota is used up. |
| 503 | dataset-unavailable / unavailable | The dataset has no published version yet, or the service is degraded. |