We have exposed searching the Provider Directory via a REST API so you are able to integrate searching the Provider Directory into your application.


Please note: The following details are for the RosettaHealth production Provider Directory, to use the production Provider Directory there are three requirements

  • you must authenticate with the RosettaHealth production Provider Directory using a production account, for example sandbox accounts will not pass authentication
  • the RosettaHealth DirectTrust Provider Directory Exchange Agreement needs to be signed and accepted. Until you have accepted the terms and conditions of the DirectTrust Provider Directory exchange agreement you will receive an unauthorized response when searching the directory
  • you must have at least 1 messaging account to be able to query the Provider Directory


To search the RosettaHealth production Provider Directory perform an HTTP request including all of the following criteria

  • HTTP Method: GET
  • Scheme: HTTPS
  • Hostname: api.direct.hispdirect.com
  • Resource: /service/user/provider/search
  • Authentication: HTTP Basic - using the credentials of a Domain / Facility Administrator or a Direct account
  • See the Query String Parameters table below for details of search criteria


Please note: The following details are for the RosettaHealth sandbox Provider Directory, to use the sandbox Provider Directory there are two requirements

  • you must authenticate using a sandbox account, for example production accounts will not pass authentication
  • you must have at least 1 messaging account to be able to query the Provider Directory


To search the RosettaHealth sandbox Provider Directory perform an HTTP request including all of the following criteria

  • HTTP Method: GET
  • Scheme: HTTPS
  • Hostname: api.sandbox.rosettahealth.net
  • Resource: /service/user/provider/search
  • Authentication: HTTP Basic - using the credentials of a Domain / Facility Administrator or a Direct account
  • See the Query String Parameters table below for details of search criteria


Please note: The sandbox Provider Directory data is limited
  • city is always Annapolis
  • state is always MD
  • directAddress is in the form example@direct.address.X.tld
  • firstName is in the form First name X
  • lastName is in the form Last name X
  • telephone is in the form (555) 123-4XXX
  • orgName is in the form Organization name X


Query String Parameters


Parameter name
Description
directAddress
Direct address of provider
firstName
first name of provider
lastName
last name of provider
orgName
name of provider's organization
city
city of provider's organization
state
state of provider's organization
zip
zip / post code of provider's organization
resultSize
maximum number of results to return regardless of number of results found

1. while no particular parameter is required, to perform a query you must include at least one of the parameters from directAddress through to zip

2. the search parameters are AND'd together, so providing multiple search parameters means all terms will be met by returned results
3. currently the matching condition is a case insensitive contains, this is likely to change to a case insensitive begins with and possibly a case insensitive ends with


Successful query response


Property name
Description
state
value will be PASS for successful queries
action
value will be SEARCH_PERFORMED for successful queries
description
value will be Successful search of Provider Directory for successful queries
resutlsFound
integer, 0 or greater - this is the total number of results, not bound by the resultSize parameter
providerList
array of provider objects, see provider object properties below


Provider object properties


Property name
Description
dataSource
currently always DirectTrust
dateAdded
timestamp of most recent import, format - yyyy-MM-dd HH:mm:ss Z
hispOperator
eg. NITOR
directAddress
provider's Direct address, will have a value
firstName
provider's first name, will have a value
lastName
provider's last name, will have a value
orgName
organization's name, may be blank
city
organization's city, will have a value but may not be a valid name of a US city
state
organization's state, will have a value and all cases we've seen so far are the standard 2 letter US state abbreviations
zip
organization's zip / post code, will have a value but may not be in valid zip / post code format eg. 5 digits or 5 digits a dash and 4 digits
speciality
currently always blank
specialityCode
currently always null
telephone
organization's phone number, may be blank but if populated there is no set format
npi
currently always blank


1. RosettaHealth does not control the data, the data comes via DirectTrust from what each HISP operator provides

2. because RosettaHealth does not control the data we have implemented a few requirements for DirectTrust Provider Directory data to meet before returning it via our API. These requirements are to help ensure the usefulness of the data. The requirements are each provider must include a hispOperator, directAddress, firstName, lastName, city, state and zip.


Example JSON successful response

{
    "action": "SEARCH_PERFORMED",
    "description": "Successful search of Provider Directory",
    "providerList": [
        {
            "city": "A City",
            "dataSource": "DirectTrust",
            "dateAdded": "2016-10-13 12:21:44 -0400",
            "directAddress": "a@direct.address.com",
            "firstName": "A First Name",
            "hispOperator": "A HISP Operator",
            "lastName": "A Last Name",
            "npi": "",
            "orgName": "An Organization",
            "speciality": "",
            "specialityCode": null,
            "state": "DC",
            "telephone": "",
            "zip": "20000"
        }
    ],
    "resultsFound": 1,
    "state": "PASS"
}


Unsuccessful query response


Property name
Description
state
value will be FAIL for unsuccessful queries
cause
currently value will either be INVALID_PARAMETERS or NOT_AUTHORIZED
description
if parameters are invalid then value will be No search parameters provided, if not authorized then value will either be NOT_AUTHORIZED:user: XXX is not a member of a domain that has accepted the provider directory agreement or the message of the thrown exception
Example JSON unsuccessful response
{
    "cause": "INVALID_PARAMETERS",
    "description": "INVALID_PARAMETERS:No search parameters provided",
    "state": "FAIL"
}