Data dictionary

Every field the API returns, with its type and meaning. The paths and types come from real responses for each schema in /openapi.json, so this page cannot fall behind the API.

.mdView as MarkdownUpdated 2026-10-30

Envelope

Every successful response has these top-level fields. data changes by endpoint.

Envelope fields
FIELD	DESCRIPTION
`request_id` string	Unique to this request. Also sent as the `X-Request-Id` header. Quote it when you contact support.
`data_as_of` date \| null	The date of the newest data behind this response.
`data` object	The answer. Its fields depend on the endpoint and are listed below.
`sources` object[]	The types of data behind the response, each with its date.
`sources[].type` string	The source type: `insurer_directory`, `plan_directory`, `provider_registry` or `plan_catalog`.
`sources[].description` string	The source type in plain words.
`sources[].as_of` date \| null	The date this type of data is current to.
`notes` string[]	Short notes to show next to the answer. Present on most endpoints.

Check

data of GET /v1/check.

Check fields
FIELD	DESCRIPTION
`npi` string	The NPI you checked.
`plan_id` string	The plan we checked. Marketplace ids are normalized to the 14-character plan id.
`input_plan_id` string	The plan id exactly as you sent it.
`market` string	`aca` for marketplace plans, `ma` for Medicare Advantage plans.
`plan_years_listed` integer[]	Plan years in which the directory lists the provider for this plan.
`in_network` true \| null	`true`: the directory lists the provider for this plan. `null`: no listing found in current directory data. It is never a statement that the provider is out of network.
`answer` string	`listed`, `not_found`, or `no_provider_network` for a prescription drug plan id (contract ids that start with S).
`explanation` string	One plain sentence that states the answer. Safe to show to users as it is.
`evidence` object[]	One entry for each listing we found. Empty when the answer is `not_found`.
`evidence[].plan_id` string	The plan of this listing.
`evidence[].plan_year` integer	The plan year of this listing.
`evidence[].network_tier` string	Marketplace plans: the tier the directory names, for example `PARTICIPATING` or `PREFERRED`. Several tiers are joined with commas.
`evidence[].source` object	Where this listing comes from.
`evidence[].source.type` string	`insurer_directory` for marketplace plans, `plan_directory` for Medicare Advantage plans.
`evidence[].source.as_of` date	The date we read that directory.
`evidence[].accepting_new_patients` boolean \| null	Medicare Advantage plans: whether the directory says the provider accepts new patients (`null` when it does not say).
`evidence[].provider_kind` string	Medicare Advantage plans: the kind of provider listed, for example `practitioner`.
`plan_year` integer \| null	The plan year this answer is about: the `year` you sent, else the newest year listed, else the newest plan year we hold.
`plan` object \| null	Plan details. `null` when we hold no details for this plan id.
`plan.plan_name` string	The plan name as the insurer publishes it.
`plan.issuer` object	Marketplace plans: the insurer.
`plan.issuer.id` string	The 5-digit insurer id (the first 5 characters of the plan id).
`plan.issuer.name` string	The insurer name.
`plan.state` string	Marketplace plans: the state the plan is sold in.
`plan.metal_level` string	Marketplace plans: Bronze, Expanded Bronze, Silver, Gold, Platinum or Catastrophic.
`plan.plan_type` string	HMO, PPO, EPO, POS and similar.
`plan.variant` string \| null	Marketplace plans: the 2-digit variant you sent (for example `01`), else `null`.
`plan.organization` string	Medicare Advantage plans: the organization that offers the plan.
`plan.service_area_states` string[]	Medicare Advantage plans: the states in the plan's service area.
`source` object	The source type of the answer and its date.
`source.type` string	`insurer_directory` or `plan_directory`.
`source.as_of` date \| null	The date we read the directory that gave this answer.
`as_of` date \| null	The date we read the directory that gave this answer (same as `source.as_of`).

Batch check

data of POST /v1/check/batch. Each item in results has the fields of a check, plus index.

Batch fields
FIELD	DESCRIPTION
`count` integer	The number of items you sent.
`summary` object	Counts of the answers in this batch.
`summary.listed` integer	Items answered `listed`.
`summary.not_found` integer	Items answered with `in_network: null`.
`summary.invalid` integer	Items that failed validation and carry an `error`.
`results` object[]	One result for each item, in the order you sent them.
`results[].index` integer	The position of the item in your `items` array, starting at 0.
`results[].npi` string	The NPI you checked.
`results[].plan_id` string	The plan we checked. Marketplace ids are normalized to the 14-character plan id.
`results[].input_plan_id` string	The plan id exactly as you sent it.
`results[].market` string	`aca` for marketplace plans, `ma` for Medicare Advantage plans.
`results[].plan_years_listed` integer[]	Plan years in which the directory lists the provider for this plan.
`results[].in_network` true \| null	`true`: the directory lists the provider for this plan. `null`: no listing found in current directory data. It is never a statement that the provider is out of network.
`results[].answer` string	`listed`, `not_found`, or `no_provider_network` for a prescription drug plan id (contract ids that start with S).
`results[].explanation` string	One plain sentence that states the answer. Safe to show to users as it is.
`results[].evidence` object[]	One entry for each listing we found. Empty when the answer is `not_found`.
`results[].evidence[].plan_id` string	The plan of this listing.
`results[].evidence[].plan_year` integer	The plan year of this listing.
`results[].evidence[].network_tier` string	Marketplace plans: the tier the directory names, for example `PARTICIPATING` or `PREFERRED`. Several tiers are joined with commas.
`results[].evidence[].source` object	Where this listing comes from.
`results[].evidence[].source.type` string	`insurer_directory` for marketplace plans, `plan_directory` for Medicare Advantage plans.
`results[].evidence[].source.as_of` date	The date we read that directory.
`results[].evidence[].accepting_new_patients` boolean \| null	Medicare Advantage plans: whether the directory says the provider accepts new patients (`null` when it does not say).
`results[].evidence[].provider_kind` string	Medicare Advantage plans: the kind of provider listed, for example `practitioner`.
`results[].plan_year` integer \| null	The plan year this answer is about: the `year` you sent, else the newest year listed, else the newest plan year we hold.
`results[].plan` object \| null	Plan details. `null` when we hold no details for this plan id.
`results[].plan.plan_name` string	The plan name as the insurer publishes it.
`results[].plan.issuer` object	Marketplace plans: the insurer.
`results[].plan.issuer.id` string	The 5-digit insurer id (the first 5 characters of the plan id).
`results[].plan.issuer.name` string	The insurer name.
`results[].plan.state` string	Marketplace plans: the state the plan is sold in.
`results[].plan.metal_level` string	Marketplace plans: Bronze, Expanded Bronze, Silver, Gold, Platinum or Catastrophic.
`results[].plan.plan_type` string	HMO, PPO, EPO, POS and similar.
`results[].plan.variant` string \| null	Marketplace plans: the 2-digit variant you sent (for example `01`), else `null`.
`results[].plan.organization` string	Medicare Advantage plans: the organization that offers the plan.
`results[].plan.service_area_states` string[]	Medicare Advantage plans: the states in the plan's service area.
`results[].source` object	The source type of the answer and its date.
`results[].source.type` string	`insurer_directory` or `plan_directory`.
`results[].source.as_of` date \| null	The date we read the directory that gave this answer.
`results[].as_of` date \| null	The date we read the directory that gave this answer (same as `source.as_of`).
`results[].error` object	Only on an item that failed validation. The other fields of a check are then absent.
`results[].error.type` string	The problem type, for example `invalid_npi`.
`results[].error.title` string	A short summary.
`results[].error.detail` string	What is wrong with this item.

Provider profile

data of GET /v1/providers/{npi}.

Provider fields
FIELD	DESCRIPTION
`npi` string	The NPI you asked for.
`profile_found` boolean	`true` when we hold identity details for this NPI. When `false`, only `npi`, `plan_summary` and `links` are present.
`name` object	The name as published, with a display form.
`name.first` string	First name.
`name.middle` string	Middle name.
`name.last` string	Last name.
`name.suffix` string \| null	Suffix, for example Jr.
`name.display` string	Name and credential ready to show, for example "Michael B. Williard, MD". We never add titles.
`credential` string	The credential as published, for example MD, DO, NP or PA.
`gender` string	`male`, `female`, or `null` when not published.
`status` string	`active` or `deactivated` in the national provider registry.
`specialties` object[]	Specialties, primary first.
`specialties[].name` string	The specialty name.
`specialties[].primary` boolean	`true` for the primary specialty.
`education` object	Training details, or `null` when not published.
`education.medical_school` string	The school named in the registry.
`education.graduation_year` integer	The graduation year.
`locations` object[]	Practice locations.
`locations[].address_line_1` string	Street address. `null` when the provider asked us to hide contact details.
`locations[].address_line_2` string \| null	Suite or second address line.
`locations[].city` string	City.
`locations[].state` string	2-letter state code.
`locations[].zip` string	5-digit ZIP code.
`locations[].phone` string \| null	Phone number, digits only. `null` when not published or hidden at the provider's request.
`locations[].latitude` number \| null	Latitude of the location, when known.
`locations[].longitude` number \| null	Longitude of the location, when known.
`locations[].group` object	The group practice at this location, or `null`.
`locations[].group.name` string	The group name.
`locations[].group.pac_id` string	The group identifier in the national registry.
`locations[].telehealth` boolean \| null	`true` when the registry marks telehealth at this location, else `null`.
`groups` object[]	Group practices the provider belongs to.
`groups[].name` string	The group name.
`groups[].pac_id` string	The group identifier in the national registry.
`groups[].members` integer	Number of providers in the group.
`affiliations` object[]	Facilities the provider is affiliated with.
`affiliations[].facility_type` string	For example Hospital or Home health agency.
`affiliations[].ccn` string	The facility's 6-character certification number.
`affiliations[].name` string \| null	Facility name, when we hold it.
`affiliations[].city` string \| null	Facility city.
`affiliations[].state` string \| null	Facility state.
`privacy` object	Privacy settings for this record.
`privacy.contact_masked` boolean	`true` when the provider asked us to hide street address and phone. Those fields are then `null`.
`plan_summary` object	Counts of the plans that list this provider. Get the plans from `links.plans`.
`plan_summary.aca` object	Marketplace plans.
`plan_summary.aca.plans` integer	Plan and plan-year pairs that list the provider.
`plan_summary.aca.issuers` integer	Insurers among those plans.
`plan_summary.aca.states` string[]	States of those plans.
`plan_summary.aca.plan_years` integer[]	Plan years with a listing.
`plan_summary.aca.as_of` date	The newest date we read a directory that lists the provider.
`plan_summary.ma` object	Medicare Advantage plans.
`plan_summary.ma.plans` integer	Plan and plan-year pairs that list the provider.
`plan_summary.ma.organizations` integer	Organizations among those plans.
`plan_summary.ma.plan_years` integer[]	Plan years with a listing.
`plan_summary.ma.accepting_new_patients_any` boolean	`true` when at least one directory says the provider accepts new patients, else `null`.
`plan_summary.ma.as_of` date	The newest date we read a directory that lists the provider.
`links` object	Related endpoints.
`links.plans` string	The path of the full plan list for this provider.

Plans that list a provider

data of GET /v1/providers/{npi}/plans.

Provider plan fields
FIELD	DESCRIPTION
`npi` string	The NPI you asked for.
`provider_states` string[]	States of the provider's practice locations.
`filters` object	The filters you sent (`null` when not sent).
`filters.market` string \| null	`aca`, `ma` or `null`.
`filters.state` string \| null	The state filter.
`filters.year` integer \| null	The plan year filter.
`total` integer	Plans that match the filters, across all pages.
`counts` object	The total, split by market.
`counts.aca` integer	Marketplace plans that match.
`counts.ma` integer	Medicare Advantage plans that match.
`offset` integer	The offset of this page.
`limit` integer	The page size.
`next_offset` integer \| null	The `offset` for the next page, or `null` on the last page.
`plans` object[]	The plans on this page: marketplace plans first, then Medicare Advantage plans.
`plans[].market` string	`aca` or `ma`.
`plans[].plan_id` string	The plan id.
`plans[].plan_year` integer	The plan year of this listing.
`plans[].plan_name` string \| null	The plan name, when we hold plan details.
`plans[].issuer` object	Marketplace plans: the insurer.
`plans[].issuer.id` string	The 5-digit insurer id.
`plans[].issuer.name` string \| null	The insurer name, when we hold it.
`plans[].state` string	Marketplace plans: the plan state.
`plans[].metal_level` string \| null	Marketplace plans: the metal level.
`plans[].plan_type` string \| null	HMO, PPO, EPO, POS and similar.
`plans[].network_tiers` string[]	Marketplace plans: the tiers the directory names for this provider.
`plans[].plan_details_available` boolean	`true` when plan name, metal level and plan type are included.
`plans[].source` object	Where this listing comes from.
`plans[].source.type` string	`insurer_directory` or `plan_directory`.
`plans[].source.as_of` date \| null	The date we read that directory.
`plans[].organization` string	Medicare Advantage plans: the organization that offers the plan.
`plans[].snp` object	Medicare Advantage plans: special needs plan details.
`plans[].snp.is_snp` boolean	`true` for a special needs plan.
`plans[].snp.type` string	The special needs plan type, as published.
`plans[].service_area_states` string[]	Medicare Advantage plans: states in the plan's service area.
`plans[].accepting_new_patients` boolean \| null	Medicare Advantage plans: whether the directory says the provider accepts new patients.
`plans[].provider_kind` string	Medicare Advantage plans: the kind of provider listed.
`plans[].taxonomy` string	Medicare Advantage plans: the provider taxonomy code listed with the network entry.
`plans[].provider_state_in_service_area` boolean \| null	Medicare Advantage plans: `true` when one of the provider's states is in the service area, `null` when either side is unknown.

Plan details

data of GET /v1/plans/{plan_id}. Marketplace and Medicare Advantage plans share some fields and add their own.

Plan fields
FIELD	DESCRIPTION
`market` string	`aca` or `ma`.
`plan_id` string	The normalized plan id.
`plan_year` integer	The plan year of these details: the `year` you sent, else the newest year we hold.
`plan_name` string	The plan name as published.
`issuer` object	Marketplace plans: the insurer.
`issuer.id` string	The 5-digit insurer id.
`issuer.name` string	The insurer name.
`state` string	Marketplace plans: the plan state.
`metal_level` string	Marketplace plans: the metal level.
`plan_type` string	HMO, PPO, EPO, POS and similar.
`markets` string[]	Marketplace plans: the markets the plan is sold in, for example Individual.
`network_id` string	Marketplace plans: the insurer's network id for this plan.
`variant_ids` string[]	Marketplace plans: every variant id of this plan.
`plan_details_available` boolean	`true` when plan name and plan details are included.
`listings` object	Whether we hold provider listings for this plan.
`listings.has_listings` boolean	`true` when we hold provider listings for this plan.
`listings.as_of` date	The date we read its directory.
`variant` string \| null	Marketplace plans: the variant you sent, else `null`.
`input_plan_id` string	The plan id exactly as you sent it.
`available_years` integer[]	Every plan year we hold for this plan.
`links` object	Related endpoints.
`links.providers` string	The path of the provider list for this plan.
`links.check` string	A check path for this plan. Put an NPI in place of `{npi}`.
`contract_id` string	Medicare Advantage plans: the contract id (the part before the first dash).
`contract_name` string	Medicare Advantage plans: the contract name as published.
`organization` string	Medicare Advantage plans: the organization that offers the plan.
`parent_organization` string	Medicare Advantage plans: the parent organization.
`category` string	Medicare Advantage plans: the plan category, for example MA-PD.
`snp` object	Medicare Advantage plans: special needs plan details.
`snp.is_snp` boolean	`true` for a special needs plan.
`snp.type` string	The special needs plan type, as published.
`service_area` object	Medicare Advantage plans: the service area.
`service_area.states` string[]	States in the service area.
`service_area.counties` integer	Number of counties in the service area.
`star_rating` number \| null	Medicare Advantage plans: the overall star rating published for the plan.
`monthly_premium` object	Medicare Advantage plans: the monthly premium range in US dollars.
`monthly_premium.min` integer	Lowest monthly premium.
`monthly_premium.max` integer	Highest monthly premium.

Providers in a plan

data of GET /v1/plans/{plan_id}/providers.

Plan provider fields
FIELD	DESCRIPTION
`plan_id` string	The plan id.
`plan_year` integer	The plan year of these listings.
`plan_name` string	The plan name.
`issuer` object	The insurer.
`issuer.id` string	The 5-digit insurer id.
`issuer.name` string	The insurer name.
`filters` object	The filters you sent (`null` when not sent).
`filters.state` string \| null	State filter.
`filters.zip` string \| null	ZIP filter.
`filters.radius` integer \| null	Radius in miles around `zip`.
`filters.specialty` string \| null	Specialty filter, in upper case.
`providers` object[]	Providers on this page, in directory order.
`providers[].npi` string	The NPI.
`providers[].name` string \| null	Display name with credential.
`providers[].credential` string \| null	The credential as published.
`providers[].primary_specialty` string \| null	The primary specialty.
`providers[].network_tiers` string[]	Tiers the directory names for this provider in this plan.
`providers[].locations` object[]	Up to 5 practice locations that match your filters.
`providers[].locations[].city` string	City.
`providers[].locations[].state` string	State.
`providers[].locations[].zip` string	ZIP code.
`providers[].locations[].distance_miles` number \| null	Miles from the `zip` you sent, when you sent `radius`. Else `null`.
`providers[].profile_found` boolean	`true` when we hold identity details for this NPI.
`page` object	Paging state. See Pagination.
`page.limit` integer	The page size you asked for.
`page.rows_scanned` integer	Listing rows read for this page.
`page.scanned_through` integer	Listing rows read so far, across pages.
`page.max_depth` integer	The most listing rows paging reads for one plan.
`page.next_cursor` string \| null	Pass it as `cursor` for the next page. `null` on the last page.
`source` object	The source type and date of these listings.
`source.type` string	Always `insurer_directory`.
`source.as_of` date	The date we read the directory.

Coverage

data of GET /v1/coverage.

Coverage fields
FIELD	DESCRIPTION
`filters` object	The filters you sent (`null` when not sent).
`filters.market` string \| null	`aca`, `ma` or `null`.
`filters.state` string	The state filter.
`filters.year` integer \| null	The plan year filter.
`markets` string[]	Markets with listings for these filters.
`summary` object	Totals by market, then by plan year.
`summary.{market}` object	`aca` or `ma`.
`summary.{market}.{year}` object	Totals for one plan year.
`summary.{market}.{year}.states` integer	States with listings.
`summary.{market}.{year}.insurers` integer	Insurers or organizations with listings.
`summary.{market}.{year}.plans` integer	Plans with listings.
`summary.{market}.{year}.as_of` date	The newest date we read a directory in this group.
`rows` object[]	One row for each market, state, insurer and plan year with listings.
`rows[].market` string	`aca` or `ma`.
`rows[].state` string	2-letter state code.
`rows[].insurer` string	The insurer or organization name.
`rows[].plan_year` integer	The plan year.
`rows[].plans` integer	Plans with listings in this row.
`rows[].as_of` date \| null	The date we read the directory for this row.

Status

data of GET /v1/status.

Status fields
FIELD	DESCRIPTION
`status` string	`ok`, `degraded` (answers still served), `busy` or `paused`. `busy` and `paused` come with HTTP 503.
`api_enabled` boolean	`false` while the API is paused for maintenance.
`version` string	The running API build.
`time` string	Server time, ISO 8601 UTC.
`checks` object	Health of the parts behind the API.
`checks.database` object	The database check.
`checks.database.ok` boolean	`true` when the database answered.
`checks.database.latency_ms` integer \| null	Time the database check took, in milliseconds.
`checks.cache` object	The cache check.
`checks.cache.ok` boolean	`true` when the cache answered.
`datasets` object[]	Every source type with the date it is current to.
`datasets[].type` string	The source type: `insurer_directory`, `plan_directory`, `provider_registry` or `plan_catalog`.
`datasets[].description` string	The source type in plain words.
`datasets[].as_of` date	The date this type of data is current to.

Problem

The body of every error. See Errors.

Problem fields
FIELD	DESCRIPTION
`type` string	Short problem type. Branch your code on this value. See Errors.
`title` string	A short, readable summary.
`status` integer	The HTTP status code.
`detail` string	What went wrong with this request, in one sentence.
`instance` string	The path you called.
`request_id` string	Unique to this request. Quote it to support.
`docs` string	A link to the matching entry on the errors page.
`current_plan` string	`plan_upgrade_required` only: the plan of the key you sent.
`required_plan` string	`plan_upgrade_required` only: the smallest plan that includes the endpoint.
`sample_npis` string[]	`demo_restricted` only: the NPIs the demo key answers for.

Docs / Reference / Data dictionaryNext: Versioning