Oystehr Services
Zambda
Examples
Terminology Search

Terminology Search

This document will show you how to use the UMLS Metathesaurus API (opens in a new tab) to set up ICD-10-CM terminology search, for free, using a Zambda.

What is ICD-10-CM?

ICD-10-CM is a set of codes used in the United states to uniquely identify reasons for patient encounters. Insurance claims may require documentation of diagnosis using ICD-10-CM codes.

Terminology Search Zambda Setup Instructions

1. Get a National Library of Medicine API key

2. Add the API Key to the Project's Secrets

Create an Secret using the Developer Console

3. Create the Zambda file

Create a javascript file called index.js using the below command. This is the code that will be executed when the Zambda is invoked:

echo 'exports.index = async event => {
  console.log("validating input body")
  if (!event.body) {
    throw new Error("No request body provided")
  }
 
  console.log("extracting search parameters and secrets from the input")
  const { search } = JSON.parse(event.body)
  const secrets = event.secrets
 
  console.log("getting the api key from secrets")
  let apiKey
  const secretKeyName = "NLM_API_KEY"
  if (secrets != null) {
    apiKey = secrets[secretKeyName]
  } else {
    apiKey = process.env[secretKeyName]
  }
 
  console.log("validating the api key")
  if (apiKey == null) {
    throw new Error(
      `Secret or Environment Variable with key ${secretKeyName} was not set.`
    )
  }
 
  console.log("searching for the codes")
  const searchResponse = { codes: [] }
  try {
    console.log("calling the UMLS Metathesaurus API")
    const icdResponse = await fetch(
      `https://uts-ws.nlm.nih.gov/rest/search/current?apiKey=${apiKey}&pageSize=50&returnIdType=code&inputType=sourceUi&string=${search}&sabs=ICD10CM`
    )
 
    console.log("validating the API response")
    if (!icdResponse.ok) {
      throw new Error(icdResponse.statusText)
    }
 
    console.log("formatting the API response")
    const icdResponseBody = await icdResponse.json()
 
    console.log("saving the API response codes to searchResponse")
    searchResponse.codes = icdResponseBody.result.results.map(entry => ({
      code: entry.ui,
      display: entry.name
    }))
  } catch (error) {
    // in case of error, throw an error
    console.error("Error while trying to request NLM ICD10 search endpoint", error)
    throw new Error("Error while trying to get ICD-10 codes")
  }
 
  console.log("returning searchResponse")
  return {
    statusCode: 200,
    body: JSON.stringify(searchResponse)
  }
}' > index.js

Zip the index.js file so it can be uploaded:

zip terminology-search.zip index.js

4. Deploy the Zambda

Now we'll upload our Zambda to Oystehr. To do this, we'll need to create a Zambda in Oystehr and then upload our zipped file to it. Zambda names are unique per-project, and cannot contain spaces or special characters. We'll use terminology-search for this example.

Create an Authenticated Zambda

5. Test the Zambda

Your Zambda is deployed! Hooray! All that's left is to test it out. Add your Zambda ID, Access Token, and Project ID to the curl below. Additionally, replace search_value with either an ICD-10-CM code or some text to get all the codes matching that search parameter.

  curl -X POST https://project-api.zapehr.com/v1/zambda/your_zambda_id/execute \
    --header 'Authorization: Bearer your_access_token' \
    --header 'x-zapehr-project-id: your_project_id' \
    --data '{"search": "search_value"}'

Example Outputs

Example Text Search

Searching for "woodworking" returns the following:

{
    "status": 200,
    "output": {
        "codes": [
            {
                "code": "W31.2",
                "display": "Contact with powered woodworking and forming machines"
            },
            {
                "code": "W31.2XXS",
                "display": "Contact with powered woodworking and forming machines, sequela"
            },
            {
                "code": "W31.2XXD",
                "display": "Contact with powered woodworking and forming machines, subsequent encounter"
            },
            {
                "code": "W31.2XXA",
                "display": "Contact with powered woodworking and forming machines, initial encounter"
            }
        ]
    }
}

Example Code Search

Searching for "W31.2" returns the following:

{
    "status": 200,
    "output": {
        "codes": [
            {
                "code": "W31.2",
                "display": "Contact with powered woodworking and forming machines"
            }
        ]
    }
}
SecretsQuota