NAV Navbar
Provider Directory API
version 2.0
cURL
  • Introduction
  • Direct Accounts
  • Errors
  • Introduction

    Welcome to MedAllies Health Provider Directory API documentation. You can use our RESTful API to access the Provider Directory hosted by MedAllies.

    The Provider Directory contains Direct Addresses and verified geographic addresses, in addition to other fields, for all HISPs participating in the DirectTrust Data Sharing Agreement.

    This API documentation provides examples of how to perform simple and complex searches based on attributes in the Provider Directory, and the returned JSON data structure for successful and unsuccessful queries.

    Please note the data obtained in our Provider Directory may be shared only within your organization and only with those individuals using a Direct Address provided by MedAllies. Otherwise the Provider Directory information may not be shared or sold.

    By using this API you are also agreeing to the terms of the latest version of the DirectTrust "Federated Services Agreement and Data Sharing Policy" found at Direct Trust.

    Please contact our Customer Support Center for any questions.

    Endpoints

    https://api.medalliesstage.com:9443/hpd/v2

    Authentication

    All external customers must authenticate via the OAuth2.

    If authentication is wrong, the result appears as follows:

    {   
      "status" : "ERROR",   
      "transactionId" : "e0c50f08-ef84-11e5-9fc9-f13f5099fd39",   
      "result" : "Incorrect username/password"
    }
    

    Response Format

    The Provider Directory API allows REST calls and returns a JSON structure.

    JSON responses contain 2 fields:

    • status: "OK" or "Error"
    • result: an array in JSON representation

    Direct Accounts

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?[Parameter]=[value]&[Parameter]=[value]

    Parameters

    Parameter Type Required Default Description
    & String no ‘ ’ If searching multiple parameters, the operator & must be used.
    npi String yes null NPI associated with the Direct address.
    last_name String yes null Last name associated with the Direct address. (Partial match is acceptable.)
    hc_specialization String yes null Specialization associated with the Direct address.(Partial match is acceptable.)
    organization_name String yes null Organization associated with the Direct address. (Partial match is acceptable.)
    practice_street1 String yes null Street associated with the Direct address.
    practice_city String yes null City associated with the Direct address.
    practice_state String yes null State associated with the Direct address.
    practice_zip Integer yes null A zipcode associated with the Direct address.
    direct_address String yes null Direct address associated with the Direct account.
    radius Integer yes null Proximity to the zipcode.
    first_name String no null First name associated with the Direct address.
    middle_name String no null Middle name associated with the Direct address.
    telephone_number String no null Telephone associated with the Direct address.

    View All Direct Accounts

    This endpoint returns all Direct accounts from the Provider Directory.

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd

    curl "https://api.medalliesstage.com:9443/hpd/v2/search_hpd"
    

    The above command returns JSON structured like this:

    {
       "status" : "OK",
       "result" : [
          {
             "practice_street1" : "7300 HANOVER DRIVE 201",
             "lat" : "38.9896946",
             "credentials" : "MD",
             "practice_state" : "MD",
             "last_name" : "Adelson",
             "npi" : "1700864501",
             "practice_zip" : "20770",
             "practice_city" : "GREENBELT",
             "organization_name" : "Arthritis and Pain Associates of P.G. County",
             "telephone_number" : "301-345-5600",
             "direct_address" : "jonathanadelson@apapgc.allscriptsdirect.net",
             "lng" : "-76.8807929",
             "hc_specialization" : "Rheumatologist",
             "first_name" : "Jonathan"
          }
       ]
    }
    

    View Direct Accounts by NPI.

    This endpoint returns a details of a Direct accounts using the NPI from the Provider directory.

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?npi=3013455600

    curl "https://api.medalliesstage.com:9443/hpd/v2/search_hpd?npi=3013455600"
    

    The above command returns JSON structured like this:

    {
       "status" : "OK",
       "result" : [
          {
             "practice_street1" : "7300 HANOVER DRIVE 201",
             "lat" : "38.9896946",
             "credentials" : "MD",
             "practice_state" : "MD",
             "last_name" : "Adelson",
             "npi" : "1700864501",
             "practice_zip" : "20770",
             "practice_city" : "GREENBELT",
             "organization_name" : "Arthritis and Pain Associates of P.G. County",
             "telephone_number" : "301-345-5600",
             "direct_address" : "jonathanadelson@apapgc.allscriptsdirect.net",
             "lng" : "-76.8807929",
             "hc_specialization" : "Rheumatologist",
             "first_name" : "Jonathan"
          }
       ]
    }
    

    View a Direct Account by first name

    This endpoint returns a details of Direct accounts containing name criteria from the Provider Directory.

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?first_name=John

    curl "https://api.medalliesstage.com:9443/hpd/v2/search_hpd?first_name=John"
    

    The above command returns JSON structured like this:

    {
       "status" : "OK",
       "result" : [
          {
             "practice_street1" : "7300 HANOVER DRIVE 201",
             "lat" : "38.9896946",
             "credentials" : "MD",
             "practice_state" : "MD",
             "last_name" : "Adelson",
             "npi" : "1700864501",
             "practice_zip" : "20770",
             "practice_city" : "GREENBELT",
             "organization_name" : "Arthritis and Pain Associates of P.G. County",
             "telephone_number" : "301-345-5600",
             "direct_address" : "jonathanadelson@apapgc.allscriptsdirect.net",
             "lng" : "-76.8807929",
             "hc_specialization" : "Rheumatologist",
             "first_name" : "Jonathan"
          }
       ]
    }
    

    View a Direct Account by last name

    This endpoint returns a details of Direct accounts containing name criteria from the Provider Directory.

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?last_name=Adelson

    curl "https://api.medalliesstage.com:9443/hpd/v2/search_hpd?last_name=Adelson"
    

    The above command returns JSON structured like this:

    {
       "status" : "OK",
       "result" : [
          {
             "practice_street1" : "7300 HANOVER DRIVE 201",
             "lat" : "38.9896946",
             "credentials" : "MD",
             "practice_state" : "MD",
             "last_name" : "Adelson",
             "npi" : "1700864501",
             "practice_zip" : "20770",
             "practice_city" : "GREENBELT",
             "organization_name" : "Arthritis and Pain Associates of P.G. County",
             "telephone_number" : "301-345-5600",
             "direct_address" : "jonathanadelson@apapgc.allscriptsdirect.net",
             "lng" : "-76.8807929",
             "hc_specialization" : "Rheumatologist",
             "first_name" : "Jonathan"
          }
       ]
    }
    

    View all Direct accounts with a Direct address

    This endpoint returns a details of all Direct accounts with a Direct address from the Provider Directory.

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?direct_address=jonathanadelson@apapgc.allscriptsdirect.net

    curl "https://api.medalliesstage.com:9443/hpd/v2/search_hpd?direct_address=jonathanadelson@apapgc.allscriptsdirect.net"
    

    The above command returns JSON structured like this:

    {
       "status" : "OK",
       "result" : [
          {
             "practice_street1" : "7300 HANOVER DRIVE 201",
             "lat" : "38.9896946",
             "credentials" : "MD",
             "practice_state" : "MD",
             "last_name" : "Adelson",
             "npi" : "1700864501",
             "practice_zip" : "20770",
             "practice_city" : "GREENBELT",
             "organization_name" : "Arthritis and Pain Associates of P.G. County",
             "telephone_number" : "301-345-5600",
             "direct_address" : "jonathanadelson@apapgc.allscriptsdirect.net",
             "lng" : "-76.8807929",
             "hc_specialization" : "Rheumatologist",
             "first_name" : "Jonathan"
          }
       ]
    }
    

    View all Direct Accounts in an organization

    This endpoint returns a details of all Direct accounts in an organization from the Provider Directory.

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?organization_name=Arthritis

    curl "https://api.medalliesstage.com:9443/hpd/v2/search_hpd?organization_name=Arthritis"
    

    The above command returns JSON structured like this:

    {
       "status" : "OK",
       "result" : [
          {
             "practice_street1" : "7300 HANOVER DRIVE 201",
             "lat" : "38.9896946",
             "credentials" : "MD",
             "practice_state" : "MD",
             "last_name" : "Adelson",
             "npi" : "1700864501",
             "practice_zip" : "20770",
             "practice_city" : "GREENBELT",
             "organization_name" : "Arthritis and Pain Associates of P.G. County",
             "telephone_number" : "301-345-5600",
             "direct_address" : "jonathanadelson@apapgc.allscriptsdirect.net",
             "lng" : "-76.8807929",
             "hc_specialization" : "Rheumatologist",
             "first_name" : "Jonathan"
          }
       ]
    }
    

    View all Direct Accounts on a street in a city of a State

    This endpoint returns a details of all Direct accounts on a street in a city of a state from the Provider Directory. Multiple database fields, with the filter criteria/values, can be specified in the URL, and the result is the logical "AND" of those fields.

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?practice_state=MD

    curl "https://api.medalliesstage.com:9443/hpd/v2/search_hpd?practice_state=MD"
    

    The above command returns JSON structured like this:

    {
       "status" : "OK",
       "result" : [
          {
             "practice_street1" : "7300 HANOVER DRIVE 201",
             "lat" : "38.9896946",
             "credentials" : "MD",
             "practice_state" : "MD",
             "last_name" : "Adelson",
             "npi" : "1700864501",
             "practice_zip" : "20770",
             "practice_city" : "GREENBELT",
             "organization_name" : "Arthritis and Pain Associates of P.G. County",
             "telephone_number" : "301-345-5600",
             "direct_address" : "jonathanadelson@apapgc.allscriptsdirect.net",
             "lng" : "-76.8807929",
             "hc_specialization" : "Rheumatologist",
             "first_name" : "Jonathan"
          }
       ]
    }
    

    View all Direct Accounts with a specialization.

    This end point returns a details of all Direct accounts with a specialization from the Provider Directory.

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?hc_specialization=Rheumatologist

    curl "https://api.medalliesstage.com:9443/hpd/v2/search_hpd?hc_specialization=Rheumatologist"
    

    The above command returns JSON structured like this:

    {
       "status" : "OK",
       "result" : [
          {
             "practice_street1" : "7300 HANOVER DRIVE 201",
             "lat" : "38.9896946",
             "credentials" : "MD",
             "practice_state" : "MD",
             "last_name" : "Adelson",
             "npi" : "1700864501",
             "practice_zip" : "20770",
             "practice_city" : "GREENBELT",
             "organization_name" : "Arthritis and Pain Associates of P.G. County",
             "telephone_number" : "301-345-5600",
             "direct_address" : "jonathanadelson@apapgc.allscriptsdirect.net",
             "lng" : "-76.8807929",
             "hc_specialization" : "Rheumatologist",
             "first_name" : "Jonathan"
          }
       ]
    }
    

    View all Direct Accounts within a radius of a zipcode

    This endpoint returns a details of all Direct accounts within a radius of a zipcode from the Provider Directory. The default radius is 5 miles.

    HTTP Request

    GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?practice_zip=20770 GET https://api.medalliesstage.com:9443/hpd/v2/search_hpd?practice_zip=20770&radius=10

    curl "https://api.medalliesstage.com:9443/hpd/v2/search_hpd?practice_zip=20770"
    

    The above command returns JSON structured like this:

    {
       "status" : "OK",
       "result" : [
          {
             "practice_street1" : "7300 HANOVER DRIVE 201",
             "lat" : "38.9896946",
             "credentials" : "MD",
             "practice_state" : "MD",
             "last_name" : "Adelson",
             "npi" : "1700864501",
             "practice_zip" : "20770",
             "practice_city" : "GREENBELT",
             "organization_name" : "Arthritis and Pain Associates of P.G. County",
             "telephone_number" : "301-345-5600",
             "direct_address" : "jonathanadelson@apapgc.allscriptsdirect.net",
             "lng" : "-76.8807929",
             "hc_specialization" : "Rheumatologist",
             "first_name" : "Jonathan"
          }
       ]
    }
    

    Errors

    Error Code Response Key Meaning
    200 OK The request has succeeded. The meaning of a success varies depending on the HTTP method:GET: The resource has been fetched and is transmitted in the message body.
    400 Required Params Missing Bad Request -- Your request is invalid.
    401 Authentication fail Unauthorized -- Invalid credentials
    403 Forbidden Client does not have access rights to the content so server is refusing to give proper response.
    404 Not Found The specified resource could not be found.
    422 Unknown Error There was a problem processing the request
    500 Internal Server Error There was an issue on our end. Try your request again.
    503 Service Unavailable The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.