NAV Navbar
Provider Directory API
version 2.1.0
cURL
  • Introduction
  • API Overview
  • Directory Search
  • Sort
  • Pagination
  • Response statuses
  • Introduction

    Welcome to the documentation of our RESTful Provider Directory API 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 Aggregated Directory.

    Through this documentation, you will learn to perform simple and complex searches based on attributes in the Provider Directory:

    • View Direct Accounts by NPI
    • View Direct Accounts by Last Name
    • View Direct Accounts by First Name
    • View Direct Accounts with a Direct Address
    • View Direct Accounts in an Organization
    • View Direct Accounts on a Street in a City of a State
    • View Direct Accounts with a Specialty
    • View Direct Accounts within a Radius of a Zip Code
    • View Direct Accounts with sort
    • View Direct Accounts with pagination

    This API documentation also shows examples of 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 https://www.directtrust.org/about-policies/.

    Please contact our Customer support center for any questions.

    API Overview

    Description

    This section describes the endpoints, the authentication method to access the API and the API response format.

    Endpoints

    GET https://api-hostname/providerdirectory/v2/

    Authentication

    To access the API, a valid Bearer Token provided by MedAllies is required. This static token is associated to your MedAllies Direct Community account.

    Example token:

    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.pF3q46_CLIyP_1QZPpeccbs-hC4n9YW2VMBjKrSO6Wg

    If the token is invalid or it cannot be authenticated, the result will be:

    {
        "error": "Unauthorized",
        "status": 401
    }
    

    If you do not have a valid API token or a MedAllies Direct Community account, please contact MedAllies Support Team by opening a request through the MedAllies Direct Community Portal: https://medallies.force.com/community/s/. If you do not have a Community account, please submit your request via our Direct Solution contact form.

    Response Format

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

    That outermost "layer" of the JSON structure contains 3 fields:

    • status: either "OK" or "Error"
    • providers: typically an array in JSON representation
    • totalCount: the total number of providers returned by the query

    Directory Search

    This section describes the search capabilities and defines the parameters required to return Direct accounts from the Provider Directory that match the search criteria.

    HTTP Request Format

    GET https://api-hostname/providerdirectory/v2/providers?[Parameter]=[value]&[Parameter]=[value]

    API Parameters

    Parameter Type Required Default Description Search strategy
    & String no If searching multiple parameters, the operator & must be used. n/a
    offset Integer no 0 An optional value indicating the offset of the first returned resource. n/a
    limit Integer no 10 An optional value indicating the maximum number of resource items to return for a single request. n/a
    sort_by String no prov_npi An optional value indicating the sort by value criteria. n/a
    sort_order String no ascending An optional value indicating the sort order criteria. n/a
    serv_direct_addr String no null Direct address associated with the Direct account. (Partial match is acceptable.) Contains
    prov_npi String no null NPI associated with the Direct address. Starts with
    prov_first_name String no null First name associated with the Direct address. Starts with
    prov_mid_name String no null Middle name associated with the Direct address. Starts with
    prov_last_name String no null Last name associated with the Direct address. Starts with
    prov_spec_text String no null Specialization associated with the Direct address.(Partial match is acceptable.) Contains
    org_name String no null Organization associated with the Direct address. (Partial match is acceptable.) Contains
    org_addr_1 String no null Street associated with the Direct address. (Partial match is acceptable.) Contains
    org_city String no null City associated with the Direct address. Starts with
    org_state String no null State associated with the Direct address. Starts with
    org_zip Integer no null A zipcode associated with the Direct address. Starts with
    org_phone String no null Telephone associated with the Direct address. Starts with
    radius Integer no null Proximity to the zipcode. Within

    View Direct Accounts by NPI

    Description

    This endpoint returns details for Direct accounts using the NPI from the Provider Directory.

    HTTP Request

    GET https://api-hostname/providerdirectory/v2/providers/prov_npi/1134566631

    curl "https://api-hostname/providerdirectory/v2/providers/prov_npi/1134566631"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 244431,
                "prov_npi": "1134566631",
                "prov_first_name": "Mitchell",
                "prov_last_name": "Birt",
                "prov_mid_name": "",
                "serv_direct_addr": "mbirt@direct.cmh.edu",
                "prov_suffix": "",
                "org_name": "Children's Mercy Hospital",
                "prov_spec_text": "Orthopaedic Surgery",
                "org_addr_1": "2401 Gillham Rd",
                "org_city": "Kansas City",
                "org_state": "MO",
                "org_zip": "64108-4619",
                "org_phone": "",
                "lat": 39.08373,
                "lng": -94.57733
            }
        ],
        "status": "OK"
    }
    

    View Direct Account by Last Name

    Description

    This endpoint returns details for Direct accounts containing last name criteria from the Provider Directory.

    HTTP Request

    GET https://api-hostname/providerdirectory/v2/providers?prov_last_name=Adelson

    curl "https://api-hostname/providerdirectory/v2/providers?prov_last_name=Adelson"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 26740,
                "prov_npi": "1356428239",
                "prov_first_name": "ANDREW",
                "prov_last_name": "ADELSON",
                "prov_mid_name": "",
                "serv_direct_addr": "andrew.adelson.1@15650.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "Caridad Centerv15650",
                "prov_spec_text": "",
                "org_addr_1": "8645 W. BOYNTON BEACH BLVD",
                "org_city": "BOYNTON BEACH",
                "org_state": "FL",
                "org_zip": "33472-4415",
                "org_phone": "(561) 737-6336",
                "lat": 26.52783,
                "lng": -80.18442
            }
        ],
        "status": "OK",
        "totalCount": "1123"
    }
    

    View Direct Account by First Name

    Description

    This endpoint returns details for Direct accounts containing first name criteria from the Provider Directory.

    HTTP Request

    GET https://api-hostname/providerdirectory/v2/providers?prov_first_name=John

    curl "https://api-hostname/providerdirectory/v2/providers?prov_first_name=John"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 66,
                "prov_npi": "1376571893",
                "prov_first_name": "JOHN",
                "prov_last_name": "BRODNAN",
                "prov_mid_name": "",
                "serv_direct_addr": "john.brodnan.1@15594.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "SMG - Centralv15594",
                "prov_spec_text": "",
                "org_addr_1": "103 Longwood Avenue",
                "org_city": "ROCKLEDGE",
                "org_state": "FL",
                "org_zip": "32955-2827",
                "org_phone": "(321) 631-5677",
                "lat": 28.33429,
                "lng": -80.72278
            },
        ],
        "status": "OK",
        "totalCount": "434435"
    }
    

    View Direct Accounts with a Direct Address

    Description

    This endpoint returns details for Direct accounts with a Direct Address from the Provider Directory.

    HTTP Request

    GET https://api-hostname/providerdirectory/v2/providers?serv_direct_addr=karen.ojeda.2@7773.direct.athenahealth.com

    curl "https://api-hostname/providerdirectory/v2/providers?serv_direct_addr=karen.ojeda.2@7773.direct.athenahealth.com"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 3,
                "prov_npi": "1205350816",
                "prov_first_name": "KAREN",
                "prov_last_name": "OJEDA",
                "prov_mid_name": "",
                "serv_direct_addr": "karen.ojeda.2@7773.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "Unified Women's Health of NCv7773",
                "prov_spec_text": "",
                "org_addr_1": "4414 LAKE BOONE TRAIL",
                "org_city": "RALEIGH",
                "org_state": "NC",
                "org_zip": "27607-7513",
                "org_phone": "(919) 351-8253",
                "lat": 35.81555,
                "lng": -78.70397
            }
        ],
        "status": "OK",
        "totalCount": "343"
    }
    

    View Direct Accounts in an Organization

    Description

    This endpoint returns details for Direct accounts in an organization from the Provider Directory.

    HTTP Request

    GET https://api-hostname/providerdirectory/v2/providers?org_name=Arthritis

    curl "https://api-hostname/providerdirectory/v2/providers?org_name=Arthritis"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 16486,
                "prov_npi": "1588891030",
                "prov_first_name": "SARAH",
                "prov_last_name": "FISHER",
                "prov_mid_name": "",
                "serv_direct_addr": "sarah.fisher.1@11478.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "Arthritis & Osteoporosis Centerv11478",
                "prov_spec_text": "",
                "org_addr_1": "1350 MIDDLEFORD RD STE 502",
                "org_city": "SEAFORD",
                "org_state": "DE",
                "org_zip": "19973-3664",
                "org_phone": "(302) 628-8300",
                "lat": 38.64703,
                "lng": -75.59863
            },
        ],
        "status": "OK",
        "totalCount": "121"
    }
    

    View Direct Accounts on a Street in a City of a State

    Description

    This end point returns details for 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-hostname/providerdirectory/v2/providers?org_state=MD

    curl "https://api-hostname/providerdirectory/v2/providers?org_state=MD"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 155,
                "prov_npi": "1609071190",
                "prov_first_name": "ZHAOMING",
                "prov_last_name": "CHEN",
                "prov_mid_name": "",
                "serv_direct_addr": "zhaoming.chen.1@10777.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "Ascension - Baltimorev10777",
                "prov_spec_text": "",
                "org_addr_1": "3407 Wilkens Avenue",
                "org_city": "BALTIMORE",
                "org_state": "MD",
                "org_zip": "21229-5073",
                "org_phone": "(667) 234-8444",
                "lat": 39.27282,
                "lng": -76.67417
            },
        ],
        "status": "OK",
        "totalCount": "4234"
    }
    

    View Direct Accounts with a Specialty

    Description

    This endpoint returns details for Direct accounts with a specialty from the Provider Directory.

    HTTP Request

    GET https://api-hostname/providerdirectory/v2/providers?prov_spec_text=Orthopedic

    curl "https://api-hostname/providerdirectory/v2/providers?prov_spec_text=Orthopedic"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 111061,
                "prov_npi": "1679607105",
                "prov_first_name": "LEON",
                "prov_last_name": "KLEMPNER",
                "prov_mid_name": "",
                "serv_direct_addr": "leon.klempner@direct.stonybrookmedicine.edu",
                "prov_suffix": "",
                "org_name": "Stony Brook Clinical Practice Management",
                "prov_spec_text": "2.16.840.1.113883.6.101:NUCC:1223X0400X:Dentist Orthodontics and Dentofacial Orthopedics",
                "org_addr_1": "37 Research Way",
                "org_city": "Setauket",
                "org_state": "NY",
                "org_zip": "11733",
                "org_phone": "",
                "lat": 40.90513,
                "lng": -73.08693
            },
        ],
        "status": "OK",
        "totalCount": "42524"
    }
    

    View Direct Accounts within a Radius of a ZIP Code

    Description

    This endpoint returns detail for Direct accounts within a radius of a ZIP code from the Provider Directory.

    HTTP Request

    GET https://api-hostname/providerdirectory/v2/providers?org_zip=12524&radius=5

    curl "https://api-hostname/providerdirectory/v2/providers?org_zip=12524&radius=5"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 96680,
                "prov_npi": "1386731776",
                "prov_first_name": "DAMON",
                "prov_last_name": "DELBELLO",
                "prov_mid_name": "",
                "serv_direct_addr": "damon.delbello.3@8980.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "WMC Advanced Physician Servicesv8980",
                "prov_spec_text": "",
                "org_addr_1": "200 Westage Business Center",
                "org_city": "FISHKILL",
                "org_state": "NY",
                "org_zip": "12524-2264",
                "org_phone": "(845) 896-4178",
                "lat": 41.52722,
                "lng": -73.89676
            },
        ],
        "status": "OK",
        "totalCount": "134"
    }
    

    Sort

    Description

    This endpoint returns detail for Direct accounts based on the sort_order and sort_by parameters. To have your results sorted on a particular property, add a sort_by parameter with the name of the property you want to sort the results on and sort_by parameter to control the direction of the sort (ascending or descending). By default, the Direct Accounts are sorted by the prov_npi field in ascending order.

    HTTP Request

    GET https://api-hostname/providerdirectory/v2/providers?org_zip=12524&radius=5&sort_by=prov_npi&sort_order=ascending

    Parameter Type Required Default value Description
    sort_by String no prov_npi any parameter(Ex: prov_npi,org_city, etc.) An optional value indicating the sort by value criteria.
    sort_order String no ascending ascending or descending An optional value indicating the sort order criteria.
    curl "https://api-hostname/providerdirectory/v2/providers?org_zip=12524&radius=5&sort_by=prov_npi&sort_order=ascending"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 292764,
                "prov_npi": "1386731776",
                "prov_first_name": "DAMON",
                "prov_last_name": "DELBELLO",
                "prov_mid_name": "",
                "serv_direct_addr": "damon.delbello.3@8980.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "WMC Advanced Physician Servicesv8980",
                "prov_spec_text": "",
                "org_addr_1": "200 Westage Business Center",
                "org_city": "FISHKILL",
                "org_state": "NY",
                "org_zip": "12524-2264",
                "org_phone": "(845) 896-3212",
                "lat": 41.52722,
                "lng": -73.89676
            },
            {
                "id": 2927631,
                "prov_npi": "1386731777",
                "prov_first_name": "john",
                "prov_last_name": "Fan",
                "prov_mid_name": "T",
                "serv_direct_addr": "john.Fan.3@8980.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "WMC Advanced Physician",
                "prov_spec_text": "",
                "org_addr_1": "500 Westage Business Center",
                "org_city": "FISHKILL",
                "org_state": "NY",
                "org_zip": "12524-2264",
                "org_phone": "(845) 896-1234",
                "lat": 41.52722,
                "lng": -73.89676
            },
        ],
        "status": "OK",
        "totalCount": "134"
    }
    

    Pagination

    Description

    All API endpoints that return a list of Direct Accounts (e.g. View Direct Accounts by First Name) enforce pagination in order to limit the size of their responses except (View Direct Accounts by NPI). These API endpoints are paginated using the offset and limit query parameters. Initially, only a certain number of results will be returned at a time. The default is 10. You can override this by passing a limit parameter to set the maximum number of results, but cannot exceed 1000. Specifying a number for offset sets the starting point for the result set, allowing you to fetch subsequent resources that are not in the initial set of results.

    HTTP Request

    GET https://api-hostname/providerdirectory/v2/providers?org_zip=12524&radius=5&soffset=10&limit=100

    Parameter Type Required Default Description
    offset Integer no 0 An optional value indicating the offset of the first returned resource.
    limit Integer no 10 An optional value indicating the maximum number of resource items to return for a single request.
    curl "https://api-hostname/providerdirectory/v2/providers?org_zip=12524&radius=5&sort_by=prov_npi&soffset=10&limit=100"
      -H 'Authorization: Bearer eywwfadfkkxsklzcklaieiiqw311JIUzI1NiJ9.eyJpYXQiOjE2MD'
    

    The above command returns JSON structured like this:

    {
        "providers": [
            {
                "id": 292764,
                "prov_npi": "1386731776",
                "prov_first_name": "DAMON",
                "prov_last_name": "DELBELLO",
                "prov_mid_name": "",
                "serv_direct_addr": "damon.delbello.3@8980.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "WMC Advanced Physician Servicesv8980",
                "prov_spec_text": "",
                "org_addr_1": "200 Westage Business Center",
                "org_city": "FISHKILL",
                "org_state": "NY",
                "org_zip": "12524-2264",
                "org_phone": "(845) 896-3212",
                "lat": 41.52722,
                "lng": -73.89676
            },
            {
                "id": 2927631,
                "prov_npi": "1386731777",
                "prov_first_name": "john",
                "prov_last_name": "Fan",
                "prov_mid_name": "T",
                "serv_direct_addr": "john.Fan.3@8980.direct.athenahealth.com",
                "prov_suffix": "",
                "org_name": "WMC Advanced Physician",
                "prov_spec_text": "",
                "org_addr_1": "500 Westage Business Center",
                "org_city": "FISHKILL",
                "org_state": "NY",
                "org_zip": "12524-2264",
                "org_phone": "(845) 896-1234",
                "lat": 41.52722,
                "lng": -73.89676
            },
        ],
        "status": "OK",
        "totalCount": "134"
    }
    

    Response statuses

    Status Code Response Key Meaning
    200 OK The request has succeeded.
    400 Required Params Missing Your request contains invalid params or some params are missing.
    401 Authentication fail 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.
    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.