# 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.

Source: https://inplan.io/docs/data-dictionary · Updated 2026-10-30

## Envelope

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

| Field | Type | 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`](https://inplan.io/docs/api/check).

| Field | Type | 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`](https://inplan.io/docs/api/check-batch). Each item in `results` has the fields of a check, plus `index`.

| Field | Type | 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}`](https://inplan.io/docs/api/providers).

| Field | Type | 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`](https://inplan.io/docs/api/provider-plans).

| Field | Type | 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}`](https://inplan.io/docs/api/plans). Marketplace and Medicare Advantage plans share some fields and add their own.

| Field | Type | 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`](https://inplan.io/docs/api/plan-providers).

| Field | Type | 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](https://inplan.io/docs/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`](https://inplan.io/docs/api/coverage).

| Field | Type | 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`](https://inplan.io/docs/api/status).

| Field | Type | 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](https://inplan.io/docs/errors).

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Short problem type. Branch your code on this value. See [Errors](https://inplan.io/docs/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. |