- Previous: APIs
- Up: APIs
- Next: CodeValidate API
ICD Search API
Overview
ICD Search API
- 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.
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 |
conceptIdList | int[] | The concept IDs of the clinical concepts that limit the 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 |
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 |
- Previous: APIs
- Up: APIs
- Next: CodeValidate API