CD2H gitForager

TransparentHealth/pjson

Name: pjson

Owner: Transparent Health

Description: Provider JSON

Forked from: HHSIDEAlab/pjson

Created: 2017-02-20 14:30:09.0

Updated: 2016-03-03 22:41:22.0

Pushed: 2016-06-10 12:25:59.0

Homepage: null

Size: 108

Language: null

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

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': []}
>>>

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.