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 within a Radius of a city location
- 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 | Sortable |
|---|---|---|---|---|---|---|
| & | String | no | If searching multiple parameters, the operator & must be used. | n/a | n/a | |
| offset | Integer | no | 0 | An optional value indicating the offset of the first returned resource. | n/a | n/a |
| limit | Integer | no | 10 | An optional value indicating the maximum number of resource items to return for a single request. | n/a | n/a |
| sort_by | String | no | prov_npi | An optional value indicating the sort by value criteria. Multiple fields are supported. | n/a | n/a |
| sort_order | String | no | ascending | An optional value indicating the sort order criteria. | n/a | n/a |
| serv_direct_addr | String | no | null | Direct address associated with the Direct account. (Partial match is acceptable.) | Contains | Yes both ascending and descending |
| prov_npi | String | no | null | 10 Digit NPI associated with the Direct address. | Must be 10 digits | Yes both ascending and descending |
| prov_first_name | String | no | null | First name associated with the Direct address. | Starts with | Yes both ascending and descending |
| prov_mid_name | String | no | null | Middle name associated with the Direct address. | Starts with | Yes both ascending and descending |
| prov_last_name | String | no | null | Last name associated with the Direct address. | Starts with | Yes both ascending and descending |
| prov_spec_text | String | no | null | Specialization associated with the Direct address.(Partial match is acceptable.) | Contains | Yes both ascending and descending |
| prov_suffix | String | no | null | The suffix associated with the provider. | Contains | Yes both ascending and descending |
| org_name | String | no | null | Organization associated with the Direct address. (Partial match is acceptable.) | Contains | Yes both ascending and descending |
| org_addr_1 | String | no | null | Street associated with the Direct address. (Partial match is acceptable.) | Contains | Yes both ascending and descending |
| org_city | String | no | null | City associated with the Direct address. | Starts with | Yes both ascending and descending |
| org_state | String | no | null | State abbreviation associated with the Direct address. | Exact match | Yes both ascending and descending |
| org_zip | Integer | no | null | A zipcode associated with the Direct address. | Starts with | Yes both ascending and descending |
| org_phone | String | no | null | Telephone associated with the Direct address. | Starts with | Yes both ascending and descending |
| radius | Integer | no | null | Proximity to the zipcode or location. | Radius functionality is capped to 1000 miles and 1000 miles will be default if no radius size is provided. | Yes both ascending and descending. (distance is the field which displays the order in the response) |
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 details for Direct accounts within a radius of a ZIP code in the Provider Directory. The last field in the response “Distance” is the proximity to the Zip code search criteria based on miles. Distance is a Double nonnull value. The precision is to two decimal places rounded up. This field will not be included in the response if search does not include the radius parameter.
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,
"distance": 0.55
},
],
"status": "OK",
"totalCount": "134"
}
View Direct Accounts within a Radius of a city location
Description
This endpoint returns details for Direct accounts within a radius of a location based on city and state combination in the Provider Directory. The last field in the response “Distance” is the proximity to the the city location search criteria based on miles. Distance is a Double nonnull value. The precision is to two decimal places rounded up. This field will not be included in the response if search does not include the radius parameter.
HTTP Request
GET https://api-hostname/providerdirectory/v2/providers?org_city=Fishkill&org_state=NY&radius=5
curl "https://api-hostname/providerdirectory/v2/providers?org_city=Fishkill&org_state=NY&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,
"distance": 0.55
},
],
"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.
Note: If radius and org_zip or location (org_city and org_state) are specified in search parameters it will be sorted by the nearest distance to the org_zip or location (org_city and org_state).
HTTP Request
GET https://api-hostname/providerdirectory/v2/providers?org_zip=12524&radius=5&sort_by=prov_last_name,prov_first_name&sort_order=ascending
| Parameter | Type | Required | Default | value | Description |
|---|---|---|---|---|---|
| sort_by | String | no | prov_npi | comma separated list of any parameters(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,
"distance": 0.55
},
{
"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,
"distance": 0.55
},
],
"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,
"distance": 0.55
},
{
"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,
"distance": 0.55
},
],
"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. |