ProviderJSON ============ Version: _0.3.2 (ALPHA)_ ProviderJSON Format Definition ============================== 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" : [...], . . . } Requirement Summary for National Plan Identifer Type I Individual (NPI-1) ------------------------------------------------------------------ * 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 the `license` array. Requirement Summary for National Plan Identifer Type II Entity (NPI-2) --------------------------------------------------------------- * 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. Requirement Summary for Other Entitiy Identifier (OEID) ------------------------------------------------ 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. Requirement Summary for a Health Plan Identifier (HPID) ------------------------------------------------ * basic - HPID type, FEIN, Controlling CPH-HPID if type is a Sub-Health Plan SHP, organization name, authorized individual, etc. Top-Level Object ================ 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. Enumeration Type ---------------- 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). Number ------ 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. Last Updated Epoch ------------------- 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). Created Epoch ------------- 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 (basic object) ==================== `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]
Other Names (other_names) =========================
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.
Addresses (addresses) =====================
Name Max Length Required Notes
address_purpose 20 Y Choices must be in ['LOCATION', 'MAILING', 'MEDREC-STORAGE', '1099', 'REVALIDATION', 'ADDITIONAL-LOCATION', 'REMITTANCE', 'ADDITIONAL-DOCUMENATION-REQUESTS']
address_type 12 Y Choices must be in ['DOM', 'FGN', 'MIL']
override_address_standardization Boolean N Instructs the API that the submitter is attesting to the address' correctness despite it does not match the address standardization.
accept_address_standardization Boolean N 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.
address_1 200 Y First line of the address
address_2 200 N Second line of an address. Suite number apartment number etc.
city 200 Y City
zip 10 S Required for a domestic address. Format XXXXX-XXXX
country_code 2 S 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']
driving_details 15 N Optional infomation to help people find the location
foreign_fax_number 20 N Foreign fax number
foreign_postal 12 S Required if a foreign address
foreign_state 2 S Required if country_code is not "US"
foreign_telephone_number 20 S Required if country_code is not "US
hours_of_operation 255 N Hours of operation for this location.
lat 20 N Optional latitude
long 20 N Optional longitude
telephone_number_extension 10 S Required if an extension exists to reach the location
us_fax_number 12 N Format xxx-xxx-xxxx
us_telephone_number 10 S Reuired for domestic addresses. format xxx-xxx-xxxx
Taxonomies (taxonomies) ======================= 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.
Licenses (licenses) ===================
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"].
Taxonomy Licenses (taxonomy_licenses) ===================================== 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].
Identifiers (identifiers) =========================
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.
Affiliations (affiliations) ========================== The affiliations array is the mean by which 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. Quick Installation of Reference Implementation ============================================== 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': []} >>>