The Search API is the main tool in the HMS API suite. It is used to perform searches of the HMS practitioner information within the limits of a client contract.
Root/Version/Request&Security
Within that structure, this section documents how the Request portion is used for search requests as well as the Body of the request. The following points are relevant to structuring search requests:
The Request portion of a search request consists of the search command, the Index, and two optional parameters and has this format: Command/Index?Page Size&Page Number
Command = search
Required:
Index - Names the index used in the search. Currently, use masterfile for all queries.Optional: If both optional parameters are given, they must be separated by an ampersand (&).
Page Size - Defines the number of returns per page. Default = 10. Max. = 250.
Format: pageSize=n, Example: pageSize=20
Page Number - Defines the page to return. If not specified, returns the first page of results.
Format: page=n, Example: page=3 Returns the 3rd page of results.
If either optional parameter is given, an ampersand must precede the Securityportion of the URL.
The full URL for the Search API is built as: Root/Version/Request&Security
Using the following values:
Root = https://api.hmsonline.com
Version = v1
Request = search/masterfile&pageSize=20&page=2
Security = timestamp=1369844777731&key=EU2BD6eHBQeUMpMxDW9dmg==&signature=8qrFmQbQgILzdDeQfbJTxHXeZvE=
Yields the following URL:
https://api.hmsonline.com/v1/search/masterfile?pageSize=20&page=2×tamp=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.
The search to be performed is defined in the Body of the API call. The Body consists of a JSON string defining the search.
Important Note: The JSON Body of the Search API is case sensitive and must be entered in lower case.
Examples of Search API Body JSON query strings follow. The URL would be constructed as shown above.
{"match_all":{}} {
"bool": {
"must": [
{
"nested": {
"path": "practitioner",
"score_mode": "total",
"query": {
"bool": {
"must": [
{
"term": {
"practitioner.hms_piid": "pi0048kwj8"
}
}
]
}
}
}
}
]
}
}{
"bool": {
"must": [
{
"nested": {
"path": "practitioner",
"score_mode": "total",
"query": {
"bool": {
"must": [
{
"match": {
"practitioner.first_name": {
"query": "john",
"operator": "and"
}
}
}
]
}
}
}
}
]
}
}{
"nested": {
"path": "practitioner",
"score_mode": "total",
"query": {
"bool": {
"must": [
{
"fuzzy_like_this": {
"fields": [
"first_name"
],
"like_text": "amera",
"min_similarity": "0.5"
}
}
]
}
}
}
}{
"nested": {
"path": "practitioner.address",
"score_mode": "total",
"query": {
"bool": {
"must": [
{
"fuzzy": {
"practitioner.address.address_line1": {
"min_similarity": 0.5,
"boost": 1,
"value": "wstrn",
"prefix_length": 0
}
}
}
]
}
}
}
}{
"bool": {
"should": [
{
"bool": {
"must": [
{
"nested": {
"path": "practitioner.npi",
"score_mode": "total",
"query": {
"term": {
"npi": " "
}
}
}
}
]
}
},
{
"bool": {
"must": [
{
"nested": {
"path": "practitioner",
"score_mode": "total",
"query": {
"bool": {
"must": [
{
"match": {
"last_name": "PORTER"
}
},
{
"fuzzy_like_this": {
"fields": [
"first_name"
],
"like_text": "DENNI",
"min_similarity": ".5"
}
}
]
}
}
}
},
{
"nested": {
"path": "practitioner.address",
"score_mode": "total",
"query": {
"match": {
"address_zip5": "26201"
}
}
}
}
]
}
}
]
}
}{
"bool": {
"must": [
{
"nested": {
"path": "practitioner",
"score_mode": "total",
"query": {
"bool": {
"must": [
{
"wildcard": {
"practitioner.first_name": "robe*"
}
}
]
}
}
}
},
{
"nested": {
"path": "practitioner.address",
"score_mode": "total",
"query": {
"bool": {
"must": [
{
"match": {
"practitioner.address.city_name": "casper"
}
}
]
}
}
}
}
]
}
}{
"bool": {
"must": [
{
"nested": {
"path": "practitioner.address",
"query": {
"filtered": {
"query": {
"match_all": {}
},
"filter": {
"geo_distance": {
"distance": "8mi",
"practitioner.address.location": {
"lat": 40.73,
"lon": -74.1
}
}
}
}
}
}
}
]
}
}{
"bool": {
"must": [
{
"nested": {
"path": "practitioner.specialty",
"score_mode": "total",
"query": {
"bool": {
"must": [
{
"match": {
"practitioner.specialty.rank": "1"
}
},
{
"match": {
"practitioner.specialty.specialty_description": "internal medicine"
}
},
{
"match": {
"practitioner.specialty.type": "abbrev_specialty"
}
}
]
}
}
}
}
]
}
}This is the layout associated with the masterfile index.
{
"name": "masterfile golden record",
"commonKey": [
"hms_piid"
],
"children": [
{
"name": "practitioner",
"key": [
"hms_piid"
],
"containers": {
"practitioner": {
"columns": [
"hms_piid",
"name_prefix",
"first_name",
"middle_name1",
"middle_name2",
"last_name",
"name_suffix",
"credential1",
"credential2",
"gender_description",
"practitioner_type_description",
"date_born",
"date_died"
]
},
"address": {
"columns": [
"address_key",
"address_type",
"rank",
"address_line1",
"address_line2",
"city_name",
"state_code",
"address_zip5",
"address_zip4",
"latitude",
"longitude",
"fips5_code",
"cbsa_code",
"census_block_group",
"address_std_code",
"lat_lon_resolution_code",
"lid",
"agid"
]
},
"location": {
"columns": [
"latitude",
"longitude"
],
"id": [
"address_key"
],
"tags": {
"latitude": "lat",
"longitude": "lon"
}
},
"address_contact": {
"columns": [
"address_key",
"value",
"type",
"rank"
]
},
"specialty": {
"columns": [
"specialty_description",
"type",
"rank"
]
},
"contact": {
"columns": [
"value",
"type"
]
},
"school": {
"columns": [
"school_code",
"school_name",
"year_graduated",
"rank"
]
},
"certification": {
"columns": [
"certification_description",
"board_description",
"expiration_year",
"issue_year",
"renewal_year",
"lifetime_flag",
"rank"
]
},
"dea": {
"columns": [
"dea_id",
"expiration_date",
"business_activity_code",
"business_activity_sub_code",
"dea_schedule",
"active_flag",
"rank",
"address_line1",
"address_line2",
"city_name",
"state_code",
"address_zip5",
"address_zip4",
"x_dea",
"bac_description",
"bac_subbac_description"
]
},
"derived_specialty": {
"columns": [
"rank",
"specialty_description"
]
},
"npi": {
"columns": [
"npi",
"rank",
"entity_type_code",
"replacement_npi",
"npi_status",
"deactivation_reason_code",
"deactivation_date",
"reactivation_date",
"enumeration_date"
]
},
"npi_taxonomy": {
"columns": [
"npi",
"ansi_x12_taxonomy_code",
"rank"
]
},
"upin": {
"columns": [
"upin_id",
"rank"
]
},
"state_license": {
"columns": [
"state_code",
"state_license_id",
"state_license_type",
"state_license_status",
"state_license_qualifier",
"state_license_sub_qualifier",
"expiration_date",
"issue_date"
]
},
"state_csr": {
"columns": [
"csr_number",
"state_code",
"drug_schedule_auth_lvl_2",
"drug_schedule_auth_lvl_2n",
"drug_schedule_auth_lvl_3",
"drug_schedule_auth_lvl_3n",
"drug_schedule_auth_lvl_4",
"drug_schedule_auth_lvl_5",
"expiration_date",
"issue_date",
"status",
"sub_status",
"schedule",
"address_line1",
"address_line2",
"city_name",
"address_state",
"address_zip5",
"address_zip4"
]
},
"sanctions": {
"columns": [
"sanction_id"
]
},
"sanction_offenses": {
"columns": [
"sanction_id",
"hms_offense_code",
"hms_offense_desc",
"hms_offense_date"
]
},
"sanction_actions": {
"columns": [
"sanction_id",
"fine_amount",
"sanction_period_start_date",
"hms_board_code",
"hms_board_desc",
"action_date",
"hms_action_code",
"hms_action_desc",
"sanction_period_end_date",
"month_duration"
]
},
"medicare_participation": {
"columns": [
"participation_flag"
]
},
"medicare_enrollment": {
"columns": [
"first_name",
"last_name",
"effective_date",
"end_date",
"opt_out_flag"
]
},
"is_active": {
"columns": [
"vend_flag_value"
],
"tags": {
"vend_flag_value": "value"
}
},
"piid_migration": {
"columns": [
"new_piid",
"piid_migration_status",
"hops",
"date_modified"
]
}
}
}
]
}