Provider Data Dictionary

Ideon's provider data schema, used for bulk files and the Provider Search endpoint

Ideon acquires, normalizes, and QAs data from hundreds of provider directory sources to produce the IdeonSelect dataset - a standardized provider directory delivering provider metadata and address-level participation for networks across ACA Medical, Large Group, Medicare Advantage, and Medicaid markets. This data is delivered in two primary methods: bulk files and the "Provider Search" endpoint (API docs). Both the files and API deliver a consistent schema for provider data and network participation, with only a handful of minor differences between the two. This data dictionary details this schema and provides important detail on available fields and values.

This page is organized into sections to cover all schema fields and nested data. Nested objects and arrays of nested objects are indicated in the Schema Key column with <> and links to the associated section defining the schema of the nested object data.

All sections are included on a single page to enable cmd+f searching based on schema keys or conventional terminology.

Provider Objects

JSON objects defining single providers, unique by NPI, are the highest-level structure for data in the bulk files (each provider object is a JSON Line) and the "Provider Search" endpoint (the providers array is a list of provider objects). This section lists the top-level fields in each provider object and references to all nested data.

Provider Names

The fields used for provider names are dependent on whether the provider is an individual or organization, as defined by the type field. If the provider's type is individual, then first, last, and middle names will be used along with suffixes, titles, and credentials. If the provider's type is organization, then the organization_name field will be used. All of the provider name strings are nullable - null is used when the provider's type does not support that name or data is not available for that specific field. An example for the latter scenario is if the individual provider does not have a middle name or suffix registered with NPPES, then middle_name and suffix will both be null.

Data Field	Schema Key	Type	Example Value	Description
Provider NPI	npi (in bulk files) id (in API)	integer	1326059643	The National Provider Identifier (NPI) of the provider, sourced from the NPPES Registry.
Associated Provider NPIs	npis	array	[ 1710374715, 1003956913 ]	The list of NPIs associated with a provider. For the majority of providers, the npis array will contain a single NPI that is consistent with the Provider NPI (npi or id) field. Both individual and organization providers can rarely have multiple NPIs associated with them, based on rollups to condense associated or same providers into single records. Most commonly, hospital provider NPIs are rolled up based on an external source for national hospital data. This serves to consolidate hospitals, which often have many NPIs registered, into single records. In these cases, the Provider NPI (npi or id) will be the primary NPI for the hospital; the npis array will contain all associated or "rolled up" NPIs.
Provider Type	type	enum	"individual"	The type of provider, with valid options of individual and organization.
Hospital Flag	hospital	boolean	true or false	Indicates whether or not the provider is a hospital. All NPIs identified as hospitals are sourced from an external national hospital dataset. This field is only available in bulk files. When using the "Provider Search" endpoint in Ideon's API, the search parameter type can be set to hospital to filter for hospital providers.
Organization Name	organization_name	string (nullable)	"BAYCARE MEDICAL GROUP INC"	The name of the provider, used when the provider's type is organization. All characters in the string will always be fully capitalized, with the exception of hospitals, which are considered a subset of organization providers. The organization name is sourced from the NPPES registry. For bulk file users building provider search integrations, we recommend searching for organizations by both the organization_name and the doing_business_as_name.
Doing Business As (DBA) Name	doing_business_as_name	string (nullable)		The commonly-used business name of the provider, populated only when the provider's type is organization. All characters in the string will always be fully capitalized. The DBA name is sourced from the NPPES registry. For bulk file users building provider search integrations, we recommend searching for organizations by both the organization_name and the doing_business_as_name. We recommend presenting the DBA name to end users, as it is typically a more commonly recognized name for the organization.
First Name	first_name	string (nullable)	"MANUELA"	The first name of the provider, used when the provider's type is individual. All characters in the string will always be fully capitalized.
Last Name	last_name	string (nullable)	"SALCEDO"	The last name of the provider, used when the provider's type is individual. All characters in the string will always be fully capitalized.
Middle Name	middle_name	string (nullable)	"MARIN"	The middle name of the provider, used when the provider's type is individual. All characters in the string will always be fully capitalized.
Gender	gender	enum	"F"	The gender of the provider. Valid values are M, F, U, X, or null. Gender is only null for organization providers.
Suffix	suffix	string (nullable)	"JR"	The provider's suffix, used when the provider's type is individual. All characters in the string will always be fully capitalized.
Title	title	string (nullable)	"DR."	The provider's title, used when the provider's type is individual. All characters in the string will always be fully capitalized.
Presentation Name	presentation_name	string (nullable)		The provider's concatenated full name, with titles, used when the provider's type is individual. All characters in the string will always be fully capitalized. The presentation_name concatenates all of title, first_name, middle_name, last_name, and suffix, as they are available.
Credentials	credentials	array	[ "MD" ]	The credentials of the provider, sourced from the NPPES registry. The credentials array will be empty if credentials for the provider are not available or if the credentials are not able to be standardized.
Networks	networks	<Array of Network Objects>		The networks array is a list of networks objects corresponding to each network the provider participates in. The Networks section details the fields and data contained in each networks object. In bulk files, the networks array is filtered to all networks the provider participates in that are included in the user's licensing. In the "Provider Search" endpoint, the networks array includes each unique network that was included in the search request.
NPI Address	npi_address	<Address Object>		The npi_address object is the primary address registered to the provider NPI, as sourced from the NPPES registry. The Addresses section details the fields and data contained in standard address objects.
NPI Specialties	npi_specialties	<Array of Specialty Objects>		The npi_specialties array is a list of specialty objects that are associated with the provider NPI, as sourced from the NPPES registry. One and only one specialty object in the npi_specialties array will be flagged as true with the primary field; this is the primary specialty of the provider, as designated by NPPES. The Specialties section details the fields and data contained in standard specialty objects.
Licenses	licenses	<Array of License Objects>		The licenses array contains all provider license data, as listed on the NPPES registry. If there are no licenses associated to a given provider, as can more typically be the case with organization providers, an empty array will be returned. The Licenses section details the data contained in each license object.

Networks

Each networks object, as found in the provider-level networks array, contains metadata and provider-level attributes for the associated network. Please note that provider-level attributes included within the network object are derived from the same source as the network itself. For example, the provider specialties included in the specialties array for each network corresponds to the specialties provided by the carrier directory source for that specific network.

Data Field	Schema Key	Type	Example Value	Description
Network ID	id	int	206410	The internal, Ideon-generated identifier for the network.
Network Name	name	string	"PRIME HEALTH SERVICES - PPO"	The name of the network. Network names are structured by Ideon's operations team to match carrier source data and presentation as closely as possible. For some carriers and networks, names may not exactly match what is seen on provider directories or health insurance cards due to inconsistencies across those various sources.
Network Tier	tier	string (nullable)	null	The tier name of the network; this field is currently unused and all values will be null.
Lines of Coverage	lines_of_coverage	array	[ "medical" ]	The lines of coverage, or product lines, the network services. Valid options are medical, medicare_advantage, and medicaid.
Markets	markets	array	[ "individual" ]	The markets the network services. Valid options are individual, small_group, and large_group.
Primary Care Physician Indicator	pcp	boolean	true, false, or null	Indicator of whether the provider is designated as a primary care physician in the carrier's source data for the specific network. The PCP indicator is true or false when the PCP status of the provider is explicitly given in the carrier's data. If it is not indicated, then PCP will be null. The PCP indicator is largely available for Medicare Advantage and Medicaid networks. The PCP indicator in the networks object will be flagged as true if PCP is true at any of the In-Network Addresses for the provider and given network.
Primary Care Physician ID	pcp_id	string (nullable)	"00933848"	The identifier for the primary care physician, specific to the carrier associated to the network the PCP ID is included for. PCP ID is largely available for directly sourced Medicare Advantage networks, but not networks in other major markets.
Carrier Name	carrier_name	string (nullable)	"Molina"	The name of the carrier associated to the given network. This will always be the first value from the carriers array.
Last Imported At	last_imported_at	string (nullable)	"2025-07-30T08:02:59.596639"	The ISO 8601 timestamp indicating when the data for the associated network was last acquired, QA'd, and published. We refresh most networks on a monthly basis and recommend using network data that is no more than 90 days old.
Network Data Source	source	string (nullable)	"carrier_direct"	Ideon's acquisition data source for the associated network. Valid options are carrier_direct, carrier_indirect, and cms. Both carrier_direct and carrier_indirect indicate the network is sourced from a carrier dataset; typically, either their provider files or an online provider directory. Network data sourced from standardized files in public repositories are labeled as cms.
Group Affiliations	group_affiliations	array	[ "COLORADO LUNA CARE PHYSICAL THERAPY LLC" ]	The list of group affiliations for the provider. Group affiliations are sourced from the carrier associated with the given network. The affiliation data is standardized according to names available in NPPES.
Hospital Affiliations	hospital_affiliations	array	[ "CHILDREN'S HOSPITAL COLORADO THERAPY CARE BROOMFIELD" ]	The list of hospital affiliations for the provider. Hospital affiliations are sourced from the carrier associated with the given network. The affiliation data is standardized according to names available in NPPES.
In-Network Addresses	addresses	<Array of Address Objects>		The addresses array is an array of in-network address objects, representing the addresses that the provider practices at and participates in the associated network. These "in-network addresses" are sourced from the carrier and match what that specific carrier represents as in-network addresses for the provider. The Addresses section details the fields and data contained in standard address objects.
Provider Specialties	specialties	<Array of Specialty Objects>		The specialties array is a list of specialty objects that are associated with the provider NPI and the specific network they are nested within. These "network specialties" are standardized according to data sourced from the carrier for the provider. The Specialties section details the fields and data contained in standard specialty objects.
Provider Languages	languages	<Array of Language Objects>		The languages array is a list of language objects, each representing a language spoken by the provider. Languages are sourced from the carrier and match what that specific carrier documents as supported languages. The Languages section details the data contained in language objects.
Carrier Brands	carriers	<Array of Carrier Objects>		The carriers array is a list of carrier objects. Each carrier object is a unique carrier brand name that is associated with the carrier who supports the network, and the list is alphebetized by carrier brand name. A network can have one or more brand names associated with it, dependent on the structure of the carrier entity and it's various subsidiaries. The Carriers section details the data contained within carrier objects.

Provider Licenses

Each provider license object, as found in the provider-level licenses array, contains the license data for the provider, as listed on the NPPES registry.

Data Field	Schema Key	Type	Example Value	Desciption
License State	state	string	"CO"	The state in which the associated provider license number is valid, sourced from the NPPES registry.
License Number	license_number	string	"35746"	The provider's license number, sourced from the NPPES registry.

Addresses

The schema for address objects is used in two places: the npi_address object and the list of in-network addresses, found in the addresses array in each networks object. All addresses are standardized and geocoded using 3rd party data.

There are some minor differences in data included in each address object depending on which level they are found in the schema.

• The npi_address objects contains address information, phone numbers, and fax numbers for the provider's primary address, as listed in the NPPES registry.

• The network addresses in the addresses array in each networks object can also contain provider-level attributes specific to that network and address, in addition to the address, phone, and fax data. These provider-level fields are identified in the table below and include pcp, pcp_id, accepting_new_patients, and external_id.

Data Field	Schema Key	Type	Example Value	Description
Address ID	id	string	"bce7602c-9bd5-36ee-9071-aaa7b8c705cf"	The internal, Ideon-generated identifier for the address. This identifier can be referenced as part of the Shop by Doc workflow to evaluate address-level network participation for quoted plans. The value is unique to the address.
Street Line 1	street_line_1	string	"3426 Lake Ave"	The first street line of the address.
Street Line 2	street_line_2	string (nullable)	"Ste 120"	The second street line of the address.
City	city	string	"Pueblo"	The name of the city of the address.
State	state	string	"CO"	The 2-character state code of the address.
ZIP Code	zip_code	string	"81004"	The ZIP code of the address.
Latitude	latitude	string	"38.21452"	The geocoded latitude of the address.
Longitude	longitude	string	"-104.62602"	The geocoded longitude of the address.
Phone Numbers	phone_numbers	<Array of Phone Number Objects>		The phone_numbers array is a list of phone number objects, each containing a phone number associated with the provider address location. The Phone and Fax Numbers section details the data contained within carrier objects.
Fax Numbers	fax_numbers	<Array of Fax Number Objects>		The fax_numbers array is a list of fax number objects, each containing a fax number associated with the provider address location. The Phone and Fax Numbers section details the data contained within carrier objects.
Primary Care Physician Indicator	pcp	boolean	true, false, or null	Indicator of whether the provider is designated as a primary care physician in the carrier's source data for the specific network. The PCP indicator is true or false when the PCP status of the provider is explicitly given in the carrier's data. If it is not indicated, then PCP will be null. The PCP indicator is largely available for Medicare Advantage and Medicaid networks.
Primary Care Physician ID	pcp_id	string (nullable)	"00933848"	The identifier for the primary care physician, specific to the carrier associated to the network the PCP ID is included for. PCP ID is largely available for directly sourced Medicare Advantage networks, but not networks in other major markets.
Carrier Address ID	external_id	string (nullable)	"620007274620"	The carrier's unique identifier for the provider address. This identifier is only available at the network-address level, and largely only populated for Medicare Advantage network-addresses for enrollment purposes.
Accepting New Patients Indicator	accepting_new_patients	boolean	true, false, or null	Indicator of whether the provider is accepting new patients at the given address. This identifier is only available at the network-address level. This value is only populated if made available by the source of the network, else the value will be null.

Specialties

The schema for specialty objects is used in two places: the npi_specialties array and the list of network specialties, found in the specialties array in each networks object. Specialties from all sources are standardized according to the NUCC Provider Taxonomy codes. Specialty objects in the npi_specialties array will additionally contain the primary boolean key, which denotes the CMS indicator for primary specialty, as listed on the NPPES Registry.

Data Field	Schema Key	Type	Example Value	Description
Specialty ID	id	string	"a1d60d2860"	The internal, Ideon-generated identifier for the specialty. This identifier can be referenced when filtering by specialty for provider search requests.
Specialty Name	name	string	"Surgery"	The name of the specialty, or specialty classification.
Sub-Specialty	sub_specialty	string (nullable)	"Plastic and Reconstructive Surgery"	The sub-specialty, or area of specialization for the specialty.
Taxonomy Code	code	string	"225100000X"	The 10-digit NUCC taxonomy code for the specialty.
Specialty Taxonomy Category	category	string	"Allopathic & Osteopathic Physicians"	The NUCC provider grouping, or high-level categorization, for the specialty.
Primary Specialty Indicator	primary	boolean	true or false	The CMS indicator of the provider's reported primary specialty as per NPPES Registry. The primary key is only included for specialties in the npi_specialties array.

Phone and Fax Numbers

Phone and fax numbers are structured as arrays of objects containing a single value, the phone or fax number string. The phone_numbers array contains an object for each phone number associated with the provider at the address. The fax_numbers array contains an object for each fax number associated with the provider at the address. Phone and fax numbers included in the npi_address object are sourced from the NPPES Registry, while phone and fax numbers included in networks[].addresses[] are specific to the carrier provider directory source for the network. Phone and fax numbers on the network level may be more reliable, as they are maintained and updated by carriers compared to the NPPES Registry.

Data Field	Schema Key	Type	Example Value	Description
Phone or Fax Number	number	string	"718-555-5555"	The phone or fax number of the provider, associated with the given address.

Languages

Language objects, as found in the languages array in each networks object, the languages spoken by the provider. Provider languages are specific to the provider directory source for the network. All languages are standardized using the ISO 639 series of codes.

Data Field	Schema Key	Type	Example Value	Description
Language ID	id	string	"bf130661-70e5-388a-b16a-6c083c05424e"	The internal, Ideon-generated identifier for the language.
Name	name	string	"Spanish"	The complete English name of the language.
ISO 639-2 Code	iso_639_2	string	"eng"	The three-letter language code standardized by ISO 639-2.
ISO 639-3 Code	iso_639_3	string	"spa"	The three-letter language code standardized by ISO 639-3.

Carriers

The carrier objects contain the carrier brand name and internal identifier for the carrier brand(s) associated with the network.

Data Field	Schema Key	Type	Example Value	Description
Carrier Brand ID	id	string	"0643a0f2-cfd0-48b6-974a-43edc1720ef1"	The internal, Ideon-generated identifier for the carrier brand. Carrier brand identifiers are consistent across Ideon's Quote and Select APIs.
Carrier Brand Name	name	string	"Aetna"	The brand or marketing name for the carrier.