ICD Search API

Overview

ICD Search services consist of two core components:

  • ICD Search (Sherpa) service: Provides access to a database of ICD codes that correspond with a user’s search term(s).  Codes are identified using clinical topics.  Sherpa returns the conditions and codes that match your criteria.
  • iDocuMint HTML Control:  A browser-based HTML control that uses the Sherpa engine to search and return results for ICD codes and clinical search terms to describe a condition, illness, injury, disease or complaint.

ICD Search API

  • ICD Search API provides programmatic access to Sherpa search services to lookup ICD codes that correspond with concept search terms.
  • ICD Search returns corresponding code and condition results to match your search criteria. Codes are identified using clinical concepts.  

Endpoints

SherpaSearch v2 Environment  Endpoint
Build   https://mashery.vitalware.com/build/ws/v2/SherpaSearch
RC https://mashery.vitalware.com/rc/ws/v2/SherpaSearch
PROD https://mashery.vitalware.com/ws/v2/SherpaSearch

Request Syntax

{ 
     "search": ["left foot fracture"],  
     "conceptIdList": [903, 2037, 94726]}
} 

Request Parameters

Parameter

Type

Description Default 
callerUid string Optional value, provided by your application, Sherpa will include in the response. null
codeSet String The code set to search. Valid values:
  • "ICD-10 CM"
  • "ICD-10 PCS"
  • "ICD-9 CM"
ICD-10 CM
conceptIdList int[] The concept IDs of the clinical concepts that limit the conditions that the search returns.
  • All concepts specified will apply to all conditions that the search returns.
empty array
dateOfService date The target date for the search. The search returns results that are valid as of the specified date. today
endRow int The maximum number of conditions that the search returns. 10
includeIndex bool

Whether to include the ICD index when performing searches.

Set to true to include. This may add clinical conditions to the set of returned conditions.

false
includeUnspecifiedConcepts bool Whether to include unspecified concepts.  Set to true to include in the results. false
search string The search terms that a found clinical condition must satisfy.  null
startRow int The start row of the returned conditions. Typically used when paging the results to display. 1

iDocuMint

An iDocuMint search starts when you type a clinical search term(s) for a condition, illness, injury or complaint. Each word in a search is identified as a separate clinical topic when a search topic is identified by Sherpa.

In the example below, iDocuMint  is using the ICD Search service on the terms “left”, “foot” and “fracture” are identified.

  • Categories display under the search bar, identifying categories such as Encounter, Anatomic Position, Healing, etc. 
  • The categories returned will vary depending on the initial search term(s).
  • Below each category name is a list of concepts belonging in that category. Each concept applies to one or more of the conditions found in the Sherpa database. 
  • In our example above, the concept “Initial” under the Encounter category applies to the first code returned, M80.072A (Age-related osteoporosis with current pathological fracture, left ankle and foot, initial encounter for fracture). It’s important to note that the clinical concept words aren not necessarily contained in a code description.
  • Clicking on a clinical topic will narrow down the codes returned to topics that apply, reducing the remaining categories. Here, choosing the topic “ankle” reduced our remaining codes to 30 and removed the category of Anatomy.

  • As clinical topics are selected, topics are displayed next to the search field in a blue bread-crumb. Any topic selected can be “backed-out” of the search by clicking the ‘X’ . The results will refresh using the remaining topics  selected.

  • A code can be documented by either clicking topics until a single code remains or by clicking a code in the list below categories.

The following table summarizes four example searches and the remaining codes after each concept is chosen. Included are columns with the Sherpa IDs representing the concepts and the IDs of the corresponding categories.

Search Terms

Selected Category

Category ID

Selected Concept

Concept ID

Codes Remaining

Categories Removed

left foot fracture 498
Anatomy 15 Ankle 903 30 Primary Sherpa, Anatomy, Anatomic Position, Open/Closed, Fracture Geometry, Displaced/NonDisplaced, Weight/Count/Number, Traumatic/NonTraumatic, Not
Healing 34 Delayed 2037 3 Encounter, Healing, With/Without, Duration/Time/Age
Etiology/Reason 3 Due to specified disease 94726 1 (Code M84.675G) Etiology/Reason, Following/In/On/After, Acuity

Sherpa service

  • ICD codes can be searched outside of the iDocuMint application by using the Sherpa Service.

Search Flow

The Sherpa service can be used to perform clinical condition searches,  like iDocuMint does.

The example above has four separate searches. Every search specified "left","foot", and "fracture" as search terms. The first search didn’t specify any clinical concept, the second specified one clinical concept ("ankle"), the second specified two concepts "ankle" and "delayed").

The Sherpa object parameter for the search terms is search, and the parameter for an array of clinical concept IDs is conceptIdList. For a complete list of all request parameters, see the API Reference.

The service response contains the following hierarchical information:

  • request: a copy of our original request to the service
  • result: the result returned by the service, containing:
    • params: more granular information for each of the search parameters. This will likely include inferred parameters that you are not aware of.
    • messages: messages about the search that can be presented to the user.
    • results: our actual search results, containing:
      • selectedDiagnosisTotal: the total code count (Codes Remaining from our example above)
      • selectedDiagnosisPageset: details for each of the codes and conditions found by the search
      • selectedConcepts: details for the clinical concept and their categories

Walkthrough: Example

The following represents calling the Sherpa Service using the fourth example from iDocuMint above. For this example, we simply pass our search terms using the search and conceptIdList parameters:

<pre class="lang-javascript">
	<code> var someElement = document.querySelector('#my-app');</code>

</pre> <pre class="language-css">

	<code>
		.some-element {
			color: red;
			font-weight: bold;
		}
	</code>
</pre> {     
        "search": ["left foot fracture"],     
        "conceptIdList": [903, 2037, 94726] 
 } 
 ```

The full response for this example is too large to display, so the following is abbreviated:

{   
    "result": {
       "parameters": {       
       "param": [{"type": 
    "phrase",         
    "value": "left",         
    "hasInfo": false,     
    "isAlias": false,"isDIndex": false,"position": 0     
   },       ...       ],     },     "messages": [{       "message": "Search executed succesfully"     }],     "result":
  {       "selectedDiagnosisTotal": {         "count": 86       },       "selectedDiagnosisPageset": {         "diagnosis": 
 [{           "id": 158865,           "code": "M80072A",           "codeAlt": "M80.072A",           "desc": "Age-related osteoporosis with current pathological fracture, left ankle and foot, initial encounter for fracture"         },         ...         ]       },   
     "selectedConcepts": {         "conceptType": [{           "type": "Anatomy",           "typeId": 15,           "count": 13,           "concepts": {             "concept": [{               "id": 1590,               "desc": "Calcaneus",               "count": 13,    
 
            "hasInfo": false             },              ...             ]           }         },         ...         ]       },       "infoNodes": {},       "instructions": {}     }   },   "request": {     "codeSet": "ICD-10 CM",     "includeIndex": false,     "search": "left foot fracture",     "conceptIdList": [903, 2037, 94726]   },   "version": "2",   "responseStatus": {     "deprecated": false   } }

API Reference

Sherpa API Request

Parameter Data type Description Default value
callerUid string An optional value, provided by your application, that Sherpa will include in the response. null
codeSet String The code set to search. Valid values:
  • "ICD-10 CM"
  • "ICD-10 PCS"
  • "ICD-9 CM"
ICD-10 CM
conceptIdList int[] The concept IDs of the clinical concepts that limit the conditions that the search returns. All concepts specified will apply to all conditions that the search returns. empty array
dateOfService date The target date for the search. The search returns results that are valid as of the specified date. today
endRow int The maximum number of conditions that the search returns. 10
includeIndex bool Whether to include the ICD index when performing searches. Set to true to include. This may add clinical conditions to the set of returned conditions. false
includeUnspecifiedConcepts bool Whether to include unspecified concepts.  Set to true to include in the results false
search string The search terms that a found clinical condition must satisfy.  null
startRow int The start row of the returned conditions, typically used when paging the results to display. 1