Provider Directory API

The Provider Directory API provides supplementary information about Practitioner resources.

Contents

About the Provider Directory
Provider Directory Endpoint
Exploring the Provider Directory
Provider Directory Resources
Query Operations
Query for an Individual Provider
Query for an Organization Provider

About the Provider Directory

Practitioners may be referenced by multiple FHIR resources. Practitioner resources may contain demographic information (such as name and address) when provided by a source system, but this data may be missing or inaccurate. When possible, HIEBus links individual providers to entries in the NPPES Registry. The Provider Directory lookup enables access to these additional practitioner details when available. You can also use the Provider Directory as a stand-alone repository for finding provider information.

Note
Where possible, HIEBus links individual providers (Entity Type 1) to NPPES entries based on name, address, or other demographics. Organization providers (CMS Entity Type 2) in source data are not linked by HIEBus to NPPES. Organization providers are often ambiguous or incorrect in source data, as they may be listed for tax or administrative reasons rather than a clinical connection. The NPPES does not provide relationships between individual providers and organizations or vice versa.

Provider Directory Endpoint

The endpoint for the Provider Directory (referred to below as YOUR_PROVIDER_DIRECTORY_ENDPOINT) is:

https://[YOUR_CAREEVOLUTION_URL]/api/fhir-providers

Note
This endpoint is not the same one used for other FHIR queries (e.g., /api/fhir). It only uses FHIR R4 resources, so there are not separate endpoints for each FHIR version.

For example, the provider directory endpoint for the FHIR test server is:

https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir-providers

Exploring the Provider Directory

A request explorer can also be used to test provider directory queries.

Log in to your account.
From your account home screen, select the “Documentation” link.
Under “Available Endpoints”, look for the “FHIR Providers” endpoint.
Select the “try it here” link.

Provider Directory Resources

Although separate from the regular FHIR endpoints, the Provider Directory API utilizes FHIR R4 Resources. A limited set of resources are supported; the two primary ones being:

Practitioner - for individual providers.
Organization - for organization providers.

Query Operations

You can submit read and search requests to the Provider Directory just as you would to other FHIR endpoints.

Note
Be sure to use the separate Provider Directory Endpoint, not the regular FHIR endpoint.

A limited set of search parameters are supported, described below.

Identifier-based queries to the Provider Directory always use the PROVIDER_DIRECTORY_ID, not the PRACTITIONER_ID. See provider identifiers for details.

Query for an Individual Provider

Queries for individual providers can be made using read/search operations with the Practitioner resource.

By ID

To read details for an individual provider, first identify the PROVIDER_DIRECTORY_ID in the Practitioner resource. See provider identifiers for details.

GET https://[YOUR_PROVIDER_DIRECTORY_ENDPOINT]/Practitioner/[PROVIDER_DIRECTORY_ID].

Note
The PROVIDER_DIRECTORY_ID is not the same as the PRACTITIONER_ID.

By NPI or Other Identifiers

To search for an individual provider by NPI, first identify the NPI in the Practitioner resource. See provider identifiers for details.

GET https://[YOUR_PROVIDER_DIRECTORY_ENDPOINT]/Practitioner?identifier=http://hl7.org/fhir/sid/us-npi|[NPI].

You can search by other identifiers (e.g., tax ID) by specifying the appropriate system URI and identifier.

By Name

To search for an individual provider by name:

GET https://[YOUR_PROVIDER_DIRECTORY_ENDPOINT]/Practitioner?name=[LAST_NAME]&given=[FIRST_NAME].

Example Response

The response will be an R4 Practitioner resource. For example:

{
    "fullUrl": "https://[YOUR_PROVIDER_DIRECTORY_ENDPOINT]/Practitioner/[PROVIDER_DIRECTORY_ID]",
    "resource": {
        "resourceType": "Practitioner",
        "id": "1601032",
        "identifier": [
            {
                "system": "http://hl7.org/fhir/sid/us-npi",
                "value": "1234"
            }
        ],
        "active": true,
        "name": [
            {
                "use": "official",
                "family": "Doctorsen",
                "given": [
                    "Ralph"
                ],
                "prefix": [
                    "DR."
                ]
            }
        ],
        "telecom": [
            {
                "system": "phone",
                "value": "888-555-1234"
            }
        ],
        "address": [
            {
                "type": "postal",
                "line": [
                    "123 Hospital Drive"
                ],
                "city": "Anywhere",
                "state": "NY",
                "postalCode": "12345",
                "country": "US"
            }
        ],
        "gender": "male",
        "qualification": [
            {
                "identifier": [
                    {
                        "value": "11111"
                    }
                ],
                "code": {
                    "coding": [
                        {
                            "system": "http://nucc.org/provider-taxonomy",
                            "code": "2084N0400X",
                            "display": "Neurology"
                        }
                    ],
                    "text": "Neurology"
                },
                "issuer": {
                    "display": "NY"
                }
            }
        ]
    },
    ...
}

Query for an Organization Provider

Even though organization providers are not automatically linked to Practitioner resources by HIEBus, you can still use the Provider Directory to find information about these providers from the NPPES Registry. This is done using read/search operations with the Organization resource.

Tip
Because organization providers are not automatically linked to Practitioner resources, you cannot look up an organization with a PROVIDER_DIRECTORY_ID.

By NPI or Other Identifiers

To search for an individual provider by NPI, first identify the NPI in the Practitioner resource. See provider identifiers for details.

GET https://[YOUR_PROVIDER_DIRECTORY_ENDPOINT]/Organization?identifier=http://hl7.org/fhir/sid/us-npi|[NPI].
You can search by other identifiers (e.g., tax ID) by specifying the appropriate system URI and identifier. For example, to search by TIN:

GET https://[YOUR_PROVIDER_DIRECTORY_ENDPOINT]/Organization?identifier=urn:oid:2.16.840.1.113883.4.4|[TIN].

By Name or Address

You can also search for organization providers by name and address using the Organization resource search parameters. For example:

GET https://[YOUR_PROVIDER_DIRECTORY_ENDPOINT]/Organization?name=[PROVIDER_NAME]&address=[PROVIDER_ADDRESS]&address-city=[PROVIDER_CITY]&address-state=[PROVIDER_STATE]&address-postalcode=[PROVIDER_ZIP].

Each field is optional, but may increase the specificity of the results when specified.

Example Response

The response will be an R4 Organization resource. For example:

{
    "fullUrl": "[YOUR_PROVIDER_DIRECTORY_ENDPOINT]/Organization/[PROVIDER_DIRECTORY_ID]",
    "resource": {
        "resourceType": "Organization",
        "id": "[PROVIDER_DIRECTORY_ID]",
        "identifier": [
            {
                "system": "http://hl7.org/fhir/sid/us-npi",
                "value": "1234"
            }
        ],
        "active": true,
        "name": "Doctor Group LLP",
        "alias": [
            "DOCTOR INSTITUTE"
        ],
        "telecom": [
            {
                "system": "phone",
                "value": "888-555-1234"
            }
        ],
        "address": [
            {
                "type": "physical",
                "line": [
                    "123 Hospital St",
                    "SUITE 101"
                ],
                "city": "Anywhere",
                "state": "NY",
                "postalCode": "12345",
                "country": "US"
            }
        ],
    },
    ...
}