Tutorial | IMO Developer Portal

Terminology Management - Crosswalks

In this tutorial, we will leverage the Terminology Management - Crosswalks API’s to allow users to create, retrieve and manage crosswalks, which are mappings between different coding systems.

What are Crosswalks?

Crosswalks are mappings between different coding systems that allow healthcare providers to translate codes from one system to another. For example, mapping CPT procedure codes to equivalent HCPCS codes for billing purposes.

Getting started

General

To utilize the Crosswalks API, you'll need to first authenticate using an access token. Once authenticated, you can proceed to make requests to the API.

Authentication (Token)

Once you have your Client ID and Client Secret from IMO, follow these steps to construct the `Authorization` header.

Send a POST request to:

https://api.imohealth.com/oauth/token

with body:

{
   "client_id":"CLIENT_ID",
   "client_secret":"CLIENT_SECRET",
   "audience":"https://api.imohealth.com",
   "grant_type":"client_credentials"
}

and header:

content-type: application/json

The response will give you the access_token. Use that to create the header:

Authorization: "Bearer ACCESS_TOKEN_HERE"

Please contact IMO Customer Support at CustomerSupport@imo-online.com if you do not know your Client ID/Secret.

Request Format

The request format must be specified in the Content-Type header as following:

JSON: application/json

Response Format

The response format must be specified in the Accept header as following:

JSON: application/json

HTTP Status Codes

HTTP status codes indicate success or failure. For more on HTTP status codes, please see each endpoint's response section.

Time zone

All times / timestamps are in the UTC time zone.

Code systems - licensing

The following code systems requires a separate third party license, to be able to access and consume the content. If the

CPT4 - licensed by AMA (American Medical Association)

CDT - licensed by ADA (American Dental Association)

DSM - licensed by APA (American Psychological Association)

Code systems - licensing

Code System Name is the human readable name.

Code System Slug is the value that needs to be used in the api requests, for the system to be able to validate the code with the given code system slug value.

Code System Name	Code System Slug	Additional License Required	Comments
CPT®-4	cpt2025	Yes	A new slug will be created for each year, as CPT releases code system specific to each year.
ICD-10-CM	icd10cm
LOINC	loinc
HL7 CVX	cvx
HCPCS	hcpcs
ICD-10-PCS	icd10pcs
RxNorm	rxnorm
National Drug Code NDC	ndc
SNOMED US Edition	snomedusedition

Crosswalks

A crosswalk is a named collection of mappings between coding systems with versioning support.

POST /crosswalks

Create a new crosswalk, metadata, crosswalk-level custom attributes, mappings, and mapping-level custom attributes.. Crosswalk name is unique per organization and name should not be blank.

request body:

{
  "name": "Test Crosswalk",
  "description": "Custom crosswalk for mapping CPT codes to equivalent or related CPT and HCPCS codes",
  "customAttributes": [
    {
      "key": "Sub-category",
      "value": "Echocardiography Procedures"
    }
  ],
  "mappings": [
    {
      "sourceCode": "93351",
      "sourceCodeSystem": "cpt2025",
      "targetCodeSystem": "cpt2025",
      "targets": [
        {
          "targetCode": "93303",
          "customAttributes": [
            {
              "key": "Sub-category",
              "value": "Echocardiography Procedures"
            }
          ]
        }
      ]
    }
  ]
}

Parameter	Required?	Allowable Values	Error Handling
name	Required	Cannot be null, user can specify a crosswalk name (e.g., "Diabetes Crosswalk"). This field allows up to 500 characters.	If user does not provide a value, they will get 400 error with a message "Crosswalk name is required".
description	Optional	Optional value for the user to provide a description for the crosswalk. This field allows up to 5000 characters.
customAttributes	Optional	Optional array of key, value pair for the Custom Attributes at crosswalk level.
key	Required, if customAttributes attribute is present.	Cannot be null, user can specify the key attribute name. This field allows up to 250 characters.	If user does not provide a key, they will get 400 error with a message.
value	Optional, if customAttributes key is present	User can specify the key attribute name. This field allows up to 5000 characters.
mappings	Optional	Optional value for the user to provide a list of mappings for the crosswalk.
sourceCodeSystem	Required, if mappings object is present.	One of the acceptable list of code system slug values (refer to the General section).	If user does not provide sourceCodeSystem, it will skip that mapping object and move to the next object.
sourceCode	Required, if mapping object is present.	Source Code value for the provided source code system.	If user does not provide sourceCode, it will skip that mapping object and move to the next object.
targetCodeSystem	Required, if mapping object is present.	One of the acceptable list of code system slug values (refer to the General section).	If user does not provide targetCodeSystem, it will skip that target mapping object and move to the next object.
targetCode	Required, if mapping object is present.	Target Code value for the provided source to target mapping.	if user does not provide targetCode, it will skip that target code, and move to the next target code. If the target code is invalid, in the response, there will be a section "Invalid codes" and all the invalid codes will be listed in that section.
customAttributes	Optional	Optional array of key, value pair for the Custom Attributes at mapping target code level.
key	Required, if customAttributes attribute is present.	Cannot be null, user can specify the key attribute name. This field allows up to 250 characters.	If user does not provide a key, they will get 400 error with a message.
value	Optional, if customAttributes key is present	User can specify the key attribute name. This field allows up to 5000 characters.

response:

{
  "identifier": "1234567a-8a9b-1234-12a1-aa123a1a1aa0",
  "name": "Test Crosswalk",
  "description": "Custom crosswalk for mapping CPT codes",
  "version": 1,
  "createdAt": "2023-10-01T12:00:00Z",
  "createdBy": "UserName",
  "updatedAt": "2023-10-01T12:00:00Z",
  "updatedBy": "UserName",
  "invalidCodes": [
    "93309"
  ]
}

GET /crosswalks?sourceCodeSystem={{sourceCodeSystem}}&sourceCode={{sourceCode}}&pageSize=100&pageNumber=1

Get a list of crosswalks for the user's organization. This end point supports optional filtering by source code system and source code.

Parameter	Required?	Allowable Values	Error Handling
sourceCodeSystem	Optional,	One of the acceptable list of code system slug values (refer to the General section).
sourceCode	Optional,	Source Code value for the provided source code system.
pageSize	Optional	Number of items to be presented in the response
pageNumber	Optional	Current page, for which the results are being pulled. If page size is 100 and page number is 2, meaning, results from 101-200 are being pulled.

response:

{
  "total": 2,
  "currentPage": 1,
  "pageSize": 100,
  "crosswalks": [
    {
      "identifier": "1234567a-8a9b-1234-12a1-aa123a1a1aa0",
      "name": "Test Crosswalk",
      "version": 2,
      "description": "Custom crosswalk for mapping CPT codes to equivalent or related CPT and HCPCS codes",
      "customAttributes": [
        {
          "key": "Sub-category",
          "value": "Echocardiography Procedures"
        }
      ],
      "createdAt": "2023-10-01T12:00:00Z",
      "createdBy": "UserName",
      "updatedAt": "2023-10-01T12:00:00Z",
      "updatedBy": "UserName"
    }
  ]
}

GET /crosswalks/{identifier}

Get crosswalk details and crosswalk-level custom attributes for a specified crosswalk identifier.

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.

response:

{
  "identifier": "1234567a-8a9b-1234-12a1-aa123a1a1aa0",
  "name": "Test Crosswalk",
  "version": 2,
  "description": "Custom crosswalk for mapping CPT codes to equivalent or related CPT and HCPCS codes",
  "customAttributes": [
    {
      "key": "Sub-category",
      "value": "Echocardiography Procedures"
    }
  ],
  "createdAt": "2023-10-01T12:00:00Z",
  "createdBy": "UserName",
  "updatedAt": "2023-10-01T12:00:00Z",
  "updatedBy": "UserName"
}

GET /crosswalks/{identifier}/versions?pageSize=100&pageNumber=1

Get all versions for a specified crosswalk identifier.

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.
pageSize	Optional	Number of items to be presented in the response
pageNumber	Optional	Current page, for which the results are being pulled. If page size is 100 and page number is 2, meaning, results from 101-200 are being pulled.

response:

{
  "total": 2,
  "currentPage": 1,
  "pageSize": 100,
  "versions": [
    {
      "version": 1,
      "name": "Test Crosswalk",
      "description": "Custom crosswalk for mapping CPT codes",
      "customAttributes": [
        {
          "key": "Sub-category",
          "value": "Echocardiography Procedures"
        }
      ],
      "status": "published",
      "createdAt": "2023-10-01T12:00:00Z",
      "createdBy": "UserName",
      "updatedAt": "2023-10-01T12:00:00Z",
      "updatedBy": "UserName"
    }
  ]
}

GET /crosswalks/{identifier}/versions/{versionNumber}

Get details for a specified crosswalk identifier and version.

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.
versionNumber	Required	Version Number for the crosswalk, user want to retrieve the details for.	If the version number is not provided, user will get 404 not found error.

response:

{
  "version": 1,
  "name": "Test Crosswalk",
  "description": "Custom crosswalk for mapping CPT codes",
  "customAttributes": [
    {
      "key": "Sub-category",
      "value": "Echocardiography Procedures"
    }
  ],
  "status": "published",
  "createdAt": "2023-10-01T12:00:00Z",
  "createdBy": "UserName",
  "updatedAt": "2023-10-01T12:00:00Z",
  "updatedBy": "UserName"
}

GET /crosswalks/{identifier}/versions/{versionNumber}/mappings?pageSize=100&pageNumber=1

Get mappings and mapping-level custom attributes for a specified crosswalk identifier and version.

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.
versionNumber	Required	Version Number for the crosswalk, user want to retrieve the mappings for.	If the version number is not provided, user will get 404 not found error.
pageSize	Optional	Number of items (source code mapping objects) to be presented in the response. The default page size is 1o source code mappings and the maximum number is also 10.
pageNumber	Optional	Current page, for which the results are being pulled. If page size is 100 and page number is 2, meaning, results from 101-200 are being pulled. Default page number is 1.

response:

{
  "total": 15,
  "currentPage": 1,
  "pageSize": 10,
  "mappings": [
    {
      "sourceCode": "93351",
      "sourceDisplay": "Echocardiography, transthoracic, real-time with image documentation (2D)",
      "sourceCodeSystem": "cpt2025",
      "targetCodeSystem": "cpt2025",
      "targets": [
        {
          "targetCode": "93303",
          "targetDisplay": "Transthoracic echocardiography for congenital cardiac anomalies; complete",
          "identifier": "1234567a-8a9b-1234-12a1-aa123a1a1aa0",
          "customAttributes": [
            {
              "key": "Sub-category",
              "value": "Echocardiography Procedures"
            }
          ]
        }
      ]
    }
  ]
}

POST /crosswalks/{identifier}/versions/{versionNumber}/mappings

Add new mappings and mapping-level custom attributes to a specified crosswalk identifier and version. Until we have the full implementation for version support, system expects the user to always provide the latest version number in the request. With the version support, the updates will only be allowed on the latest version.

If the latest version is a "Draft", user will get a message to update the latest version from the UI or publish the draft version before attempting to update from the api.
If the latest version is "Published", system will create a new version, apply the updates to the newer version and auto publishes the newer version.

request body:

{
  "mappings": [
    {
      "sourceCode": "93351",
      "sourceCodeSystem": "cpt2025",
      "targetCodeSystem": "cpt2025",
      "targets": [
        {
          "targetCode": "93303",
          "customAttributes": [
            {
              "key": "Sub-category",
              "value": "Echocardiography Procedures"
            }
          ]
        }
      ]
    }
  ]
}

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.
versionNumber	Required	Version Number for the crosswalk, user want to retrieve the details for.	If the version number is not provided, user will get 404 not found error.
mappings	Optional	Optional value for the user to provide a list of mappings for the crosswalk.
sourceCodeSystem	Required, if mappings object is present.	One of the acceptable list of code system slug values (refer to the General section).	If user does not provide sourceCodeSystem, it will skip that mapping object and move to the next object.
sourceCode	Required, if mapping object is present.	Source Code value for the provided source code system.	If user does not provide sourceCode, it will skip that mapping object and move to the next object.
targetCodeSystem	Required, if mapping object is present.	One of the acceptable list of code system slug values (refer to the General section).	If user does not provide targetCodeSystem, it will skip that target mapping object and move to the next object.
targetCode	Required, if mapping object is present.	Target Code value for the provided source to target mapping.	if user does not provide targetCode, it will skip that target code, and move to the next target code. If the target code is invalid, in the response, there will be a section "Invalid codes" and all the invalid codes will be listed in that section.
customAttributes	Optional	Optional array of key, value pair for the Custom Attributes at mapping target code level.
key	Required, if customAttributes attribute is present.	Cannot be null, user can specify the key attribute name. This field allows up to 250 characters.	If user does not provide a key, they will get 400 error with a message.
value	Optional, if customAttributes key is present	User can specify the key attribute name. This field allows up to 5000 characters.

response: If there are any invalid codes present in the request, they will be presented in the "Invalid Codes" section.

{
  "message": "Target codes added successfully.",
  "invalidCodes": [
    "93309"
  ]
}

DELETE /crosswalks/{identifier}/versions/{versionNumber}/mappings

Delete a list of mappings from a specified crosswalk identifier and version. Until we have the full implementation for version support, system expects the user to always provide the latest version number in the request. With the version support, the deletes will only be allowed on the latest version.

If the latest version is a "Draft", user will get a message to update the latest version from the UI or publish the draft version before attempting to delete from the api.
If the latest version is "Published", system will create a new version, apply the deletes to the newer version and auto publishes the newer version.

request body:

{
  "mappings": [
    {
      "sourceCode": "93351",
      "sourceCodeSystem": "cpt2025",
      "targetCodeSystem": "cpt2025",
      "targetCodes": [
        "93303",
        "93304",
        "01234"
      ]
    }
  ]
}

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.
versionNumber	Required	Version Number for the crosswalk, user want to retrieve the details for.	If the version number is not provided, user will get 404 not found error.
mappings	Optional	Optional value for the user to provide a list of mappings for the crosswalk.
sourceCodeSystem	Required, if mappings object is present.	One of the acceptable list of code system slug values (refer to the General section).	If user does not provide sourceCodeSystem, it will skip that mapping object and move to the next object.
sourceCode	Required, if mapping object is present.	Source Code value for the provided source code system.	If user does not provide sourceCode, it will skip that mapping object and move to the next object.
targetCodeSystem	Required, if mapping object is present.	One of the acceptable list of code system slug values (refer to the General section).	If user does not provide targetCodeSystem, it will skip that target mapping object and move to the next object.
targetCodes	Required, if mapping object is present.	Target Code values to be deleted from the source to target mapping.	if user does not provide targetCode, it will skip that target code, and move to the next target code. If the target code is invalid, in the response, there will be a section "Invalid codes" and all the invalid codes will be listed in that section.

response:

{
  "message": "Target codes deleted successfully."
}

PATCH /crosswalks/{identifier}/versions/{versionNumber}/attributes

Update or add one or more crosswalk-level custom attributes for a specified crosswalk identifier and version.. Until we have the full implementation for version support, system expects the user to always provide the latest version number in the request. With the version support, the updates will only be allowed on the latest version.

If the latest version is a "Draft", user will get a message to update the latest version from the UI or publish the draft version before attempting to update from the api.
If the latest version is "Published", system will create a new version, apply the updates to the newer version and auto publishes the newer version.

request body:

{
  "customAttributes": [
    {
      "key": "Sub-category",
      "value": "Echocardiography Procedures"
    }
  ]
}

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.
versionNumber	Required	Version Number for the crosswalk, user want to retrieve the details for.	If the version number is not provided, user will get 404 not found error.
customAttributes	Required	Array of key, value pair for the Custom Attributes at mapping target code level.
key	Required	Cannot be null, user can specify the key attribute name. This field allows up to 250 characters.	If user does not provide a key, they will get 400 error with a message.
value	Optional.	User can specify the key attribute name. This field allows up to 5000 characters.

response:

{
  "message": "Custom attributes modified successfully."
}

DELETE /crosswalks/{identifier}/versions/{versionNumber}/attributes

Delete one or more crosswalk-level custom attributes for a specified crosswalk identifier and version.. Until we have the full implementation for version support, system expects the user to always provide the latest version number in the request. With the version support, the deletes will only be allowed on the latest version.

If the latest version is a "Draft", user will get a message to update the latest version from the UI or publish the draft version before attempting to delete from the api.
If the latest version is "Published", system will create a new version, apply the deletes to the newer version and auto publishes the newer version.

request body:

{
  "customAttributes": [
    "Sub-category"
  ]
}

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.
versionNumber	Required	Version Number for the crosswalk, user want to retrieve the details for.	If the version number is not provided, user will get 404 not found error.
customAttributes	Required	Array of keys, that needs to be deleted from the crosswalk level custom attributes.

response:

{
  "message": "Custom attributes deleted successfully."
}

PATCH /crosswalks/{identifier}/versions/{versionNumber}/mappings/{codeIdentifier}/attributes

Update or add one or more crosswalk mapping-level custom attributes for a specified crosswalk identifier and mapping identifier... Until we have the full implementation for version support, system expects the user to always provide the latest version number in the request. With the version support, the updates will only be allowed on the latest version.

If the latest version is a "Draft", user will get a message to update the latest version from the UI or publish the draft version before attempting to update from the api.
If the latest version is "Published", system will create a new version, apply the updates to the newer version and auto publishes the newer version.

request body:

{
  "customAttributes": [
    {
      "key": "Sub-category",
      "value": "Echocardiography Procedures"
    }
  ]
}

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.
versionNumber	Required	Version Number for the crosswalk, user want to retrieve the details for.	If the version number is not provided, user will get 404 not found error.
codeIdentifier	Required	Code Identifier for the given source and target code combination. This code identifier is available in the list of mappings response.	If the code identifier is not provided, user will get 404 not found error.
customAttributes	Required	Array of key, value pair for the Custom Attributes at mapping target code level.
key	Required	Cannot be null, user can specify the key attribute name. This field allows up to 250 characters.	If user does not provide a key, they will get 400 error with a message.
value	Optional.	User can specify the key attribute name. This field allows up to 5000 characters.

response:

{
  "message": "Custom attributes modified successfully."
}

DELETE /crosswalks/{identifier}/versions/{versionNumber}/mappings/{codeIdentifier}/attributes

Delete one or more crosswalk mapping-level custom attributes for a specified crosswalk identifier and mapping identifier... Until we have the full implementation for version support, system expects the user to always provide the latest version number in the request. With the version support, the deletes will only be allowed on the latest version.

If the latest version is a "Draft", user will get a message to update the latest version from the UI or publish the draft version before attempting to delete from the api.
If the latest version is "Published", system will create a new version, apply the deletes to the newer version and auto publishes the newer version.

request body:

{
  "customAttributes": [
    "Sub-category"
  ]
}

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.
versionNumber	Required	Version Number for the crosswalk, user want to retrieve the details for.	If the version number is not provided, user will get 404 not found error.
codeIdentifier	Required	Code Identifier for the given source and target code combination. This code identifier is available in the list of mappings response.	If the code identifier is not provided, user will get 404 not found error.
customAttributes	Required	Array of keys, that needs to be deleted from the crosswalk level custom attributes.

response:

{
  "message": "Custom attributes deleted successfully."
}

DELETE /crosswalks/{identifier}

Inactivate the crosswalk for the specified crosswalk identifier. The crosswalk will not be hard deleted, it will only be flagged as archived. This will enable the user for the future re-activation of these archived crosswalks.

Parameter	Required?	Allowable Values	Error Handling
identifier	Required	Identifier of the crosswalk, provided in the crosswalk list operation.	If the identifier is not provided, user will get 404 not found error.

response:

{
  "message": "Crosswalk archived successfully."
}