Table of Contents

Use

The Matching API is similar to the Search API in that it locates an HMS practitioner record based on user input. It differs from Search in that it will either identify a unique practitioner that fits the input values or return nothing. Matching is based on Match Plans, which contain one or more rounds that are run in succession until either a round identifies a single match or the plan completes without finding a match.

Match Plans

  • Matching is performed by running a Match Plan using the input values provided.
  • Match Plans are identified by Match Plan Name.
  • Match Plans are created and maintained by HMS.

Method

  • Method: POST

URL

  • URL Structure: Root/Version/Request&Security

Within that structure, this section documents how the Request portion is used for matching requests as well as the Body of the request. The following points are relevant to structuring matching requests:

  • The only type of Request allowed and documented covers running a Match Plan created by HMS.
  • Returns for a successful match consist of a single practitioner ID.
  • Returns for an unsuccessful match have the same format but with an empty practitioner ID.

Request

The Request portion of a match request consists of the matching command and the 'Match Plan', and has this format:

  • Request = Command/Match Plan

  • Command = matching/match

Required:

  • Match Plan - Identifies the Match Plan to use for Matching. Provided by HMS.

Optional:

There are no optional parameters with Matching.

Matching API URL Example

The full URL for the Matching API is built as: Root/Version/Request&Security

Using the following values:

Root = https://api.hmsonline.com Version = v1 Match Plan = TESTPLAN

Request = matching/match/TESTPLAN

Security = timestamp=1369844777731&key=EU2BD6eHBQeUMpMxDW9dmg==&signature=8qrFmQbQgILzdDeQfbJTxHXeZvE=

Yields the following URL:

https://api.hmsonline.com/v1/matching/match/TESTPLAN?timestamp=1369844777731&key=EU2BD6eHBQeUMpMxDW9dmg==&signature=8qrFmQbQgILzdDeQfbJTxHXeZvE=

Note: All security values shown here and throughout this documentation are for illustration purposes only and will not work as shown. See Security Credentials for more information.

Body

The information to be matched against the HMS practitioners is given in the Body of the API call. The Body consists of a JSON string defining the matching input data. The format of this JSON is:

{
  "matchInput": {
    "practitioner": {
      <Match Terms>
    }
  }
}
Where Match Terms consist of FieldValue pairs (e.g., "first_name":"john" will include First Name = "john" as a match input term).

Note: The JSON Body of the Matching API is case sensitive and must be entered in lower case.

Match Terms and Input Layout

The available input Match Terms are shown below. All Match Terms are in the Input Layout shown below. Not all fields in the Input Layout are used in Matching, and not all Match Terms are used in every Match Plan. HMS can assist with understanding existing Match Plans as well as creating client -specific Match Plans.

Match Terms

Term Description
first_name Practitioner First Name
last_name Practitioner Last Name
middle_name_1 Practitioner Middle Name
npi:npi National Provider Identifier
dea:dea_id DEA Identifier
upin:upin Unique Physician Identifier
state_license:state_license_id State License Identifier
state_license:state_code State License State Code
address:address_line1 Practitioner Address Line 1
address:city_name Practitioner Address City
address:state_code Practitioner Address State Code
address:latitude Practitioner Address Latitude
address:longitude Practitioner Address Longitude

Input Layout

Coming soon

JSON Matching Examples

Examples of Matching API Body JSON matching input strings follow. The URL would be constructed as shown above.

Match Example 1

Using input match terms of:

  • First Name = john
  • Last Name = smith
  • City = king of prussia
  • State = pa
  • Location
    • Latitude = 40.084508
    • Longitude = -75.342109 
{
  "matchInput": {
    "practitioner": {
      "first_name": "john",
      "last_name": "smith",
      "address:longitude":"-75.342109",
      "address:latitude":"40.084508",
     "address:city_name":"king of prussia",
     "address:state_code":"pa"
    }
    }
}

The results would look something like the following:

Match found:

[{
   "result": "PI00JN5HC2"
 }]

No Match found:

[{
   "result": ""
 }]