Provider Directory API

The Provider Directory API provides supplementary information about Practitioner resources.

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.

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

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.

1. Log in to your account.
2. From your account home screen, select the “Documentation” link.
3. Under “Available Endpoints”, look for the “FHIR Providers” endpoint.
4. 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.

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].

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.

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"
            }
        ],
    },
    ...
}