Version: 0.3.2 (ALPHA)
ProviderJSON is a JSON object format for representing US health care providers.
It is based on fields currently collected to receive or maintain a National Provider Identifier (or NPI). ProviderJSON is input and output format for Provider Enrollment APIs. ProviderJSON will also store HPID and OEID enumerations as well.
Core information is stored either at the top level or in the basic
object. basic
contains name, demographics, and related information. subsequent arrays of objects contain other information such as addresses and license information. Much of the information is optional. Here is a high-level pseudo-code example of a typical document:
{
"enumeration_type" : "NPI-1",
"number" : 1142832052,
"last_updated_epoch" : 1409675065,
"created_epoch" : 1409663451,
"basic" : {...},
"other_names" : [...],
"addresses" : [...],
"taxonomies" : [...],
"licenses" : [...],
"taxonomy_licenses" : [...],
"identifiers" : [...],
"affiliations" : [...],
.
.
.
}
- basic - First and last name, contact person etc.
- licenses - At least 1 license or certification for certain taxonomies.
- taxonomies - At least 1 is required. 1 is reqired to marked as primary.
- addresses - Exactly one mailing addrress. Exactly one primary practice location.
- taxonomy_licenses - When a taxonomy requires a license, this array maps the taxonomy, in the
taxonomies
array, to a specific license in thelicense
array.
- basic - Organization name, FEIN, authorized official, etc.
- taxonomies - At least 1 is required and 1 is reqired to marked as primary.
- addresses - Exactly one mailing addrress. Exactly one primary practice location.
An individual with an OEID, should NOT be eligible nor have an NPI-1.
- basic - First and last, contact person, etc.
- taxonomies - At least 1 is required and 1 is reqired to marked as primary.
- basic - HPID type, FEIN, Controlling CPH-HPID if type is a Sub-Health Plan SHP, organization name, authorized individual, etc.
The ProviderJSON object contains several top-level items.
The enumeration_type
acts a switch determining what is required and what is
not. The number
component contains a string of the enumeration number.
classification
is used when submitting this informartion via API to indicate
whether the request is for a new enumeration or a change request.
basic
is an object that contains basic demographic information (e.g. name,
contact person, etc.). addresses
contains an array of provider address objects.
taxonomies
is an array of taxonomy classification objects,licenses
contains
an array of license information. identifiers
contains an array of other
identifier objects. direct-addresses
contain an array of Direct email address objects.
Each of these main components are described in detail in the sections below.
Much of the information is optional or is only required in specific
circumstances. It is possibile to add additional infformation to this document
so long as the additional items do not confilict with the fields defined here.
It is the hope that other componets can be defined over time so that all provider
information can be represented here.
The enumeration_type
is required and shall be one of these four values.
- NPI-1 - An individual (human) provider.
- NPI-2 - An provider (legal entity) organization.
- OEID - An individual "other entitiy" provider (a human being not eligbile for an NPI-1).
- HPID - A health plan identifier (an organization).
The number
is the assigned enumeration number (e.g. an NPI). This integer
field should be left blank when submitting a new enumeration request, but
must be provided on change requests. Number is always length 10 where
the last number is a checkdigit according to the Luhn algorithm.
Please refer to the NPI final rule for more infromation.
The last_updated_epoch
is an integer of the Unix epoch for the last update
to the enumeration.
A Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number
of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT),
not counting leap seconds (in ISO8601: 1970-01-01T00:00:00Z).
The created_epoch
is an integer of the Unix epoch for the creation of the enumeration.
A Unx epoch (or Unix time or POSIX time or Unix timestamp) is the number
of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT),
not counting leap seconds (in ISO8601: 1970-01-01T00:00:00Z).
basic
contains an object ({}
) of basic demographic inforation that is not
repeated. The information is based on the NPI final rule, but includes some
optional information.
These are as follows:
Name | Max Length | Required | Notes |
name_prefix | 5 | N | Choices must be in ['Ms.', 'Mr.', 'Miss', 'Mrs.', 'Dr.', 'Prof.']. Required for NPI-1 |
first_name | 150 | N | Required for NPI-1 |
last_name | 150 | S | Required for NPI-1 |
middle_name | 150 | N | Applies only to NPI-1. |
name_suffix | 4 | N | Choices must be in ['Jr.', 'Sr.', 'I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX', 'X']. Applies only to NPI-1. |
credential | 50 | N | Applies only to NPI-1. |
sole_proprietor | 3 | N | Applies only to NPI-1. Choices must be in ['YES', 'NO']. . |
organizational_subpart | Boolean | S | Applies only to NPI-2. Choices are `true` or `false`. |
ssn | 9 | S | Required for NPI-1 if no itin is provided. |
ein | 9 | S | Required for NPI-2. |
itin | 9 | S | Required for NPI-1 if no ssn is provided. |
gender | 1 | S | Required for NPI-1. Choices must be in ['F', 'M']. |
date_of_birth | 10 | S | Required for NPI-1. Format must be YYYY-MM-DD. |
state_of_birth | 2 | S | Required for NPI-1. Choices must be in ['AL', 'AK', 'AZ', 'AR', 'CA', 'CO', 'CT', 'DE', 'DC', 'FL', 'GA', 'HI', 'ID', 'IL', 'IN', 'IA', 'KS', 'KY', 'LA', 'ME', 'MD', 'MA', 'MI', 'MN', 'MS', 'MO', 'MT', 'NE', 'NV', 'NH', 'NJ', 'NM', 'NY', 'NC', 'ND', 'OH', 'OK', 'OR', 'PA', 'RI', 'SC', 'SD', 'TN', 'TX', 'UT', 'VT', 'VA', 'WA', 'WV', 'WI', 'WY', 'AS', 'FM', 'GU', 'MH', 'MP', 'PR', 'PW', 'VI', 'ZZ']. Use ZZ if born outside the US or US territories. |
country_of_birth | 2 | S | Applies only to NPI-1. Choices must be in ['AF', 'AX', 'AL', 'DZ', 'AS', 'AD', 'AO', 'AI', 'AQ', 'AG', 'AR', 'AM', 'AW', 'AU', 'AT', 'AZ', 'BS', 'BH', 'BD', 'BB', 'BY', 'BE', 'BZ', 'BJ', 'BM', 'BT', 'BO', 'BQ', 'BA', 'BW', 'BV', 'BR', 'IO', 'BN', 'BG', 'BF', 'BI', 'KH', 'CM', 'CA', 'CV', 'KY', 'CF', 'TD', 'CL', 'CN', 'CX', 'CC', 'CO', 'KM', 'CG', 'CD', 'CK', 'CR', 'CI', 'HR', 'CU', 'CW', 'CY', 'CZ', 'DK', 'DJ', 'DM', 'DO', 'EC', 'EG', 'SV', 'GQ', 'ER', 'EE', 'ET', 'FK', 'FO', 'FJ', 'FI', 'FR', 'GF', 'PF', 'TF', 'GA', 'GM', 'GE', 'DE', 'GH', 'GI', 'GR', 'GL', 'GD', 'GP', 'GU', 'GT', 'GG', 'GN', 'GW', 'GY', 'HT', 'HM', 'VA', 'HN', 'HK', 'HU', 'IS', 'IN', 'ID', 'IR', 'IQ', 'IE', 'IM', 'IL', 'IT', 'JM', 'JP', 'JE', 'JO', 'KZ', 'KE', 'KI', 'KP', 'KR', 'KW', 'KG', 'LA', 'LV', 'LB', 'LS', 'LR', 'LY', 'LI', 'LT', 'LU', 'MO', 'MK', 'MG', 'MW', 'MY', 'MV', 'ML', 'MT', 'MH', 'MQ', 'MR', 'MU', 'YT', 'MX', 'FM', 'MD', 'MC', 'MN', 'ME', 'MS', 'MA', 'MZ', 'MM', 'NA', 'NR', 'NP', 'NL', 'NC', 'NZ', 'NI', 'NE', 'NG', 'NU', 'NF', 'MP', 'NO', 'OM', 'PK', 'PW', 'PS', 'PA', 'PG', 'PY', 'PE', 'PH', 'PN', 'PL', 'PT', 'PR', 'QA', 'RE', 'RO', 'RU', 'RW', 'BL', 'SH', 'KN', 'LC', 'MF', 'PM', 'VC', 'WS', 'SM', 'ST', 'SA', 'SN', 'RS', 'SC', 'SL', 'SG', 'SX', 'SK', 'SI', 'SB', 'SO', 'ZA', 'GS', 'SS', 'ES', 'LK', 'SD', 'SR', 'SJ', 'SZ', 'SE', 'CH', 'SY', 'TW', 'TJ', 'TZ', 'TH', 'TL', 'TG', 'TK', 'TO', 'TT', 'TN', 'TR', 'TM', 'TC', 'TV', 'UG', 'UA', 'AE', 'GB', 'US', 'UM', 'UY', 'UZ', 'VU', 'VE', 'VN', 'VG', 'VI', 'WF', 'EH', 'YE', 'ZM', 'ZW']. |
initial_enumeration_date | 10 | N | Must be in YYYY-MM-DD format. This value is system generated. Value is same as enumeration_date unless record has been deactivated and reactivated. |
enumeration_date | 10 | N | Must be in YYYY-MM-DD format. This value is system generated. |
last_updated | 10 | N | Must be in YYYY-MM-DD format. This value is system generated. |
date_of_death | 10 | N | Date of death. System generated from SSA. Must be in YYYY-MM-DD format. |
reactivation_date | 10 | N | Date of reactivation. Must be in YYYY-MM-DD format. |
mode | 1 | N | System generated. Choices must be in ['(W)eb', '(P)aper', '(E)FI', '(A)PI']. Should always be 'A' when using the API and 'W' when using the web interface. |
status | 1 | N | Choices must be in ['E(diting)', 'P(ending)', '(A)ctive', '(D)eactive', '(R)evoked']. System generated. |
contact_method | 1 | N | Defaults to email. Choices must be in ['(E)mail', '(M)ail']. |
deactivated_details | 1000 | N | Optional details concering deactivation. Deacesed etc. This information is for the Enuemrator only. |
deactivation_date | 10 | N | Deactivation Date. System generated. Format must be YYYY-MM-DD. |
deactivation_reason_code | 2 | N | Choices must be in ['', 'DT', 'DB', 'FR', 'OT']. System generated. |
deactivation_note | 1024 | N | Optional deactivation note. This information is for the Enuemrator only. |
deceased_notes | 1000 | N | Optional deceased notes. This information is for the Enuemrator only. |
parent_organization_ein | 9 | S | A parent organization tax id. Applies only to NPI-2. Required when subpart is true. |
parent_organization_legal_business_name | 300 | S | Applies only to NPI-2. A parent organization's legal business name. Required when subpart is true. |
reactivation_note | 1024 | N | Note on reactivation |
comments | 1024 | N | Used only by the enuemerator and cannot be submitted or returned in API results./td> |
authorized_official_credential | 20 | N | Applies only to NPI-2. |
authorized_official_email | 75 | N | Applies only to NPI-2. |
authorized_official_first_name | 150 | S | Required for NPI-2. |
authorized_official_last_name | 150 | S | Required for NPI-2. |
authorized_official_middle_name | 150 | N | Applies only to NPI-2. |
authorized_official_prefix | 10 | N | Choices must be in ['Ms.', 'Mr.', 'Miss', 'Mrs.', 'Dr.', 'Prof.']. Applies only to NPI-2. |
authorized_official_suffix | 4 | N | Choices must be in ['Jr.', 'Sr.', 'I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX', 'X']. Applies only to NPI-2. |
authorized_official_telephone_number | 10 | S | Required for NPI-2 only. |
authorized_official_telephone_extension | 10 | N | Applies for NPI-2 only. |
authorized_official_title_or_position | 150 | S | Required for NPI-2. |
contact_person_credential | 20 | N | Optional |
contact_person_email | 75 | Y | Required if the person has an email. |
contact_person_prefix | 5 | N | Choices must be in ['Ms.', 'Mr.', 'Miss', 'Mrs.', 'Dr.', 'Prof.']. Applies only to NPI-1. |
contact_person_first_name | 150 | Y | Required for NPI-1. |
contact_person_last_name | 150 | Y | Required. |
contact_person_middle_name | 150 | Y | Applies only to NPI-1. |
contact_person_suffix | 4 | N | Choices must be in ['Jr.', 'Sr.', 'I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX', 'X']. Applies only to NPI-1. |
contact_person_telephone_number | 20 | Y | Required for NPI-1 and NPI-2 if the contact person has a telephone number. |
contact_person_telephone_extension | 10 | N | |
contact_person_title_or_position | 150 | Y | |
website | 200 | N | A website url. |
facebook_handle | 100 | N | A facebook handle. |
twitter_handle | 100 | A twitter handle | A twitter handle |
public_email | 75 | N | |
gravatar_email | 200 | N | a gravatar email for displaying an avatar with a profile. |
driving_directions | 256 | N | |
bio_headline | 255 | N | |
hpid_type | 17 | S | Required where enumeration_type is HPID. Type must be in [CHP, SHP-COMPANY, SHP-ISSUER, SHP-PRODUCT, SHP-LINE-BUSINESS, SHP-OTHER] |
Name | Max Length | Required | Notes |
Type | 35 | N | System generated from "code" for readability. |
code | 1 | Y | Determines the type of other_name. Values must be in
("","Blank"),
("1","Former Name"),
("2","Professional Name"),
("3","Doing Business As"),
("4","Former Legal Business Name"),
("5","Other Name"). Codes "1" and "2"refer only to NPI-1. 4 refers only to NPI-2. 3 refers to NPI-1 where sole_proprietor=true and NPI-2. Blank ("") is not accepted in the API, but may be encountered in legacy data. |
prefix | 5 | N | Applies only to NPI-1. Must be in ['Ms.'Mr.','Miss','Mrs.','Dr.','Prof.'] |
suffix | 4 | N | Applies only to NPI-1. Must be in ['Jr.','Sr.','I','II', 'III','IV','V','VI','VII','VIII','IX','X'] |
credential | 50 | N | Refersonly to NPI-1. |
othertype | 50 | S | Required when code=5 (Other). |
organization_name | 150 | S | Required for NPI-2. |
first_name | 150 | S | Required for NPI-1 when code is 1 or 2. |
last_name | 150 | S | Required for NPI-1 when code is 1 or 2. |
middle_name | 150 | N | Applies only to NPI-1 and when code is 1 or 2. |
<tr>
<td>address_purpose</td>
<td>20</td>
<td>Y</td>
<td>Choices must be in ['LOCATION', 'MAILING', 'MEDREC-STORAGE', '1099',
'REVALIDATION', 'ADDITIONAL-LOCATION', 'REMITTANCE', 'ADDITIONAL-DOCUMENATION-REQUESTS']</td>
</tr>
<tr>
<td>address_type</td>
<td>12</td>
<td>Y</td>
<td>Choices must be in ['DOM', 'FGN', 'MIL']</td>
</tr>
<tr>
<td>override_address_standardization</td>
<td>Boolean</td>
<td>N</td>
<td>Instructs the API that the submitter is attesting to the
address' correctness despite it does not match the address standardization.</td>
</tr>
<tr>
<td>accept_address_standardization</td>
<td>Boolean</td>
<td>N</td>
<td>Instructs the API replace the submitted address with the standardized address. Use this feature with caution. Use the APIs validate feature to see the standardized address as a "dry run" before setting this flag.</td>
</tr>
<tr>
<td>address_1</td>
<td>200</td>
<td>Y</td>
<td>First line of the address</td>
</tr>
<tr>
<td>address_2</td>
<td>200</td>
<td>N</td>
<td>Second line of an address. Suite number apartment number etc.</td>
</tr>
<tr>
<td>city</td>
<td>200</td>
<td>Y</td>
<td>City</td>
</tr>
<tr>
<td>zip</td>
<td>10</td>
<td>S</td>
<td>Required for a domestic address. Format XXXXX-XXXX</td>
</tr>
<tr>
<td>country_code</td>
<td>2</td>
<td>S</td>
<td>Required if foreign address. Assumed US if not provided. Choices must be in ['AF', 'AX', 'AL', 'DZ', 'AS', 'AD', 'AO', 'AI',
'AQ', 'AG', 'AR', 'AM', 'AW', 'AU', 'AT', 'AZ', 'BS', 'BH', 'BD', 'BB',
'BY', 'BE', 'BZ', 'BJ', 'BM', 'BT', 'BO', 'BQ', 'BA', 'BW', 'BV', 'BR',
'IO', 'BN', 'BG', 'BF', 'BI', 'KH', 'CM', 'CA', 'CV', 'KY', 'CF', 'TD',
'CL', 'CN', 'CX', 'CC', 'CO', 'KM', 'CG', 'CD', 'CK', 'CR', 'CI', 'HR',
'CU', 'CW', 'CY', 'CZ', 'DK', 'DJ', 'DM', 'DO', 'EC', 'EG', 'SV', 'GQ',
'ER', 'EE', 'ET', 'FK', 'FO', 'FJ', 'FI', 'FR', 'GF', 'PF', 'TF', 'GA',
'GM', 'GE', 'DE', 'GH', 'GI', 'GR', 'GL', 'GD', 'GP', 'GU', 'GT', 'GG',
'GN', 'GW', 'GY', 'HT', 'HM', 'VA', 'HN', 'HK', 'HU', 'IS', 'IN', 'ID',
'IR', 'IQ', 'IE', 'IM', 'IL', 'IT', 'JM', 'JP', 'JE', 'JO', 'KZ', 'KE',
'KI', 'KP', 'KR', 'KW', 'KG', 'LA', 'LV', 'LB', 'LS', 'LR', 'LY', 'LI',
'LT', 'LU', 'MO', 'MK', 'MG', 'MW', 'MY', 'MV', 'ML', 'MT', 'MH', 'MQ',
'MR', 'MU', 'YT', 'MX', 'FM', 'MD', 'MC', 'MN', 'ME', 'MS', 'MA', 'MZ',
'MM', 'NA', 'NR', 'NP', 'NL', 'NC', 'NZ', 'NI', 'NE', 'NG', 'NU', 'NF',
'MP', 'NO', 'OM', 'PK', 'PW', 'PS', 'PA', 'PG', 'PY', 'PE', 'PH', 'PN',
'PL', 'PT', 'PR', 'QA', 'RE', 'RO', 'RU', 'RW', 'BL', 'SH', 'KN', 'LC',
'MF', 'PM', 'VC', 'WS', 'SM', 'ST', 'SA', 'SN', 'RS', 'SC', 'SL', 'SG',
'SX', 'SK', 'SI', 'SB', 'SO', 'ZA', 'GS', 'SS', 'ES', 'LK', 'SD', 'SR',
'SJ', 'SZ', 'SE', 'CH', 'SY', 'TW', 'TJ', 'TZ', 'TH', 'TL', 'TG', 'TK',
'TO', 'TT', 'TN', 'TR', 'TM', 'TC', 'TV', 'UG', 'UA', 'AE', 'GB', 'US',
'UM', 'UY', 'UZ', 'VU', 'VE', 'VN', 'VG', 'VI', 'WF', 'EH', 'YE', 'ZM',
'ZW']</td>
</tr>
<tr>
<td>driving_details</td>
<td>15</td>
<td>N</td>
<td>Optional infomation to help people find the location</td>
</tr>
<tr>
<td>foreign_fax_number</td>
<td>20</td>
<td>N</td>
<td>Foreign fax number</td>
</tr>
<tr>
<td>foreign_postal</td>
<td>12</td>
<td>S</td>
<td>Required if a foreign address</td>
</tr>
<tr>
<td>foreign_state</td>
<td>2</td>
<td>S</td>
<td>Required if country_code is not "US"</td>
</tr>
<tr>
<td>foreign_telephone_number</td>
<td>20</td>
<td>S</td>
<td>Required if country_code is not "US</td>
</tr>
<tr>
<td>hours_of_operation</td>
<td>255</td>
<td>N</td>
<td>Hours of operation for this location.</td>
</tr>
<tr>
<td>lat</td>
<td>20</td>
<td>N</td>
<td>Optional latitude</td>
</tr>
<tr>
<td>long</td>
<td>20</td>
<td>N</td>
<td>Optional longitude</td>
</tr>
<tr>
<td>telephone_number_extension</td>
<td>10</td>
<td>S</td>
<td>Required if an extension exists to reach the location </td>
</tr>
<tr>
<td>us_fax_number</td>
<td>12</td>
<td>N</td>
<td>Format xxx-xxx-xxxx</td>
</tr>
<tr>
<td>us_telephone_number</td>
<td>10</td>
<td>S</td>
<td>Reuired for domestic addresses. format xxx-xxx-xxxx</td>
</tr>
Name | Max Length | Required | Notes |
Note that some taxonomy codes require a license. Additionally some taxonomies are
for individuals while others are for organizations. This information can be found
in the taxonomy-license-crosswalk.csv
file within this repository.
Name | Max Length | Required | Notes |
code | 50 | Y | Choices for codes found at http://www.wpc-edi.com/taxonomy |
primary | Boolean | Y | `true` if this is the primary taxonomy and `false` otherwise. Only one taxonomy code in the array can be flagged with primary=true. |
Name | Max Length | Required | Notes |
number | 50 | Y | The unique number or identifier given to the license provided by the issuing organization. Required if codified version not given |
type | 3 | Y | The license type according to https://github.com/HHSIDEAlab/mlvs/blob/master/docs/USProviderLicenseTypesFeb2014.csv |
state | 2 | Y | State according to ISO 3166-2:US. |
status | 2 | Y | Defaults to UNKNOWN for bringing lagacy data forward. If suplied, the value must be in ["UNKNOWN","ACTIVE","ACTIVE_WITH_RESTRICTIONS", "EXPIRED", "REVOKED", "DECEASED"]. |
The taxonomy_licenses
arrary is designed to associate taxonomy codes with specific licenses within the provider document.
Name | Max Length | Required | Notes |
taxonomy_code | 20 | Y | A taxonomy code that must be present in the `taxonomies` array of the same document. |
license_code | 75 | Y | A license code that must be present in the `licenses` array of the same document. The license code must be in the format [STATE]-[PROVIDER_TYPE]-[LICENSE_NUMBER]. |
Name | Max Length | Required | Notes |
identifier | 20 | Y | The number or code issued by the issuing body. |
code | 2 | Y | Identifer Type code. Accetable values are ("", "Blank"),("01", "Other"),("02","Medicare UPIN"), ("04","Medicare ID Type Unspecified"),("05", "Medicaid"), ("06", "Medicare OSCAR/certification"), ("07", "Medicare NSC"), ("08", "MEDICARE PIN") |
state | 2 | Y | State according to ISO 3166-2:US. |
issuer | 150 | Y | The name of the issuing body. |
The affiliations array is the mean wy whicy Direct addresses, endpoints, and network affiliations are expressed. Below is simple example of a Direct addresss:
{
"enumeration_type": "NPI-1",
"number": "1111111111",
"basic": {
"first_name": "James",
"last_name": "Kirk",
.
.
},
.
.
"affiliations":[
{
"purpose_type": "HEALTH-INFORMATION-EXCHANGE",
"affiliation_data_type": "NPI-2",
"affiliation_id": "12334567890",
"endpoint_data_type": "DIRECT-EMAIL-ADDRESS",
"endpoint": "jtkirk@direct.example.com"
}
]
}
In this example, James Kirk with an NPI 111111111, has one Direct address from the Organization with the NPI-2 of 12334567890.
See affiliations.md for the full definition.
A validation library(Python) and command line tool for validating ProviderJSON
is has moved to the provider-data-tools
repository https://github.com/hhsidealab/provider-data-tools. The easiest way to install it is using pip
.
Open a terminal window and type:
sudo pip install pdt
Test it using the command line tool on Unixlike systems:
validate-pjson sample.json
On Windows it will be something like:
python c:\Python27\Scrips\validate-pjson sample.json
This will return a JSON object with arrays of errors and warnings. A clean record would look like this.
{
"errors": [],
"warnings": []
}
You can also use it in you own code like so:
python
>>> from pdt.pjson.validate_pjson import validate_pjson
>>> validate_pjson('{"number": "12345"}')
>>> {'errors': ['The JSON object does not contain an enumeration_type.'], 'warnings': []}
>>>