Prior authorization metrics for a payer
GET /v1/payers/{id}/prior-auth-metrics
GET https://api.healthcare.dev/v1/payers/{id}/prior-auth-metricsBuilder plan and up (Free: a few preview calls a month, then 403 plan-upgrade-required). The prior authorization metrics a payer posted for a year (default: the latest it posted), one report per reporting unit: percent of standard and expedited requests approved and denied, percent approved after appeal, percent approved after the review time was extended, and the mean and median time from request to decision (in hours; as_reported keeps the payer's own wording). Each metric carries the count and the total it is out of when the payer gives them, and what that total is (denominator_basis); a metric the payer doesn't give is null with a not_reported_reason, never estimated. Each report says how its values were read (derivation: source_stated when read directly from the posting, reviewed when a person checked them), links the posting (evidence) and the payer's list of items needing prior authorization when it gives one. A posting we couldn't read reliably yet is report_status: pending_review. Values are as the payer reported them in its annual public posting under the CMS Interoperability and Prior Authorization rule (CMS-0057-F). They are not audited by healthcare.dev or CMS, and payers count and round differently: compare with care and check the payer's posting (evidence).
Requires an API key: Authorization: Bearer hdev_live_.... See Authentication.
Path parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
id | string | yes | Payer id from GET /v1/payers | humana |
Query parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
year | integer | no | Calendar year the metrics cover (default: the latest posted) | 2025 |
unit | string | no | Only this reporting unit: its key or id (e.g. a contract H1036, FL-MEDICAID) | H1036 |
view | "compact" | "standard" | "full" | no | How much of each record to return (default full). compact: unit, year, report_status, standard, expedited (fewest tokens, for agents). standard: every field except payer_id, payer_name. full: every field. | compact |
fields | string | no | Comma-separated fields to return instead of a view. Valid fields: payer_id, payer_name, unit, year, report_status, standard, expedited, all_requests, items_requiring_pa_url, confidence, derivation, evidence, as_of. | unit,year,report_status |
Examples
curl
curl "https://api.healthcare.dev/v1/payers/humana/prior-auth-metrics" \
-H "Authorization: Bearer $HDEV_API_KEY"TypeScript
const res = await fetch("https://api.healthcare.dev/v1/payers/humana/prior-auth-metrics", {
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/payers/humana/prior-auth-metrics", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()Try it
Response
The payer's reports for the year
{
"data": {
"payer": {
"id": "string",
"name": "string"
},
"year": 1,
"years_available": [
1
],
"note": "string",
"reports": [
{
"payer_id": "string",
"payer_name": "string",
"unit": null,
"year": 1,
"report_status": "available",
"standard": {
"approved": null,
"denied": null,
"approved_after_appeal": null,
"approved_after_extension": null,
"mean_time": null,
"median_time": null
},
"expedited": {
"approved": null,
"denied": null,
"approved_after_appeal": null,
"approved_after_extension": null,
"mean_time": null,
"median_time": null
},
"all_requests": {
"approved_after_extension": null
},
"items_requiring_pa_url": "string",
"confidence": 0,
"derivation": null,
"evidence": [
null
],
"as_of": "2026-10-24T12:00:00Z"
}
]
},
"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/payers/humana/prior-auth-metrics",
"next": null
}
}Fields
| Field | Type | Always present | Description |
|---|---|---|---|
payer | object | yes | |
year | integer | null | yes | The year shown: year if given, else the latest with a posting; null with none |
years_available | integer[] | yes | Years with postings, newest first |
note | string | yes | How to read these values (show it with them) |
reports | PriorAuthMetricsReport[] | yes | One per reporting unit, by unit key |
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. |