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 and payers to translate codes from one system to another. For example, mapping CPT procedure codes to equivalent HCPCS codes or Snomed codes.

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)

Available Code Systems

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 attribute names. 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"
      "type": "crosswalk_version"
    },
    {
      "key": "Sub-category",
      "value": "Any value",
      "type": "crosswalk_code"
    }
  ],
  "mappings": [
    {
      "sourceCode": "93351",
      "sourceCodeSystem": "cpt2025",
      "targetCodeSystem": "cpt2025",
      "targets": [
        {
          "targetCode": "93303"
        }
      ]
    }
  ]
}

Parameter	Required?	Allowable Values	Error Handling	Comments
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 and mapping 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 250 characters.		If the `type` is set to "crosswalk_code" this value will be ignored.
type	Optional, if customAttributes key is present	User can specify the type as "crosswalk_version" or "crosswalk_code" to signify the custom attributes has been added for the crosswalk-level or mapping-level, respectively.	If user does not provide a type, it will default to "crosswalk_version"	A type set as "crosswalk_version" will be for the crosswalk-level attributes while the "crosswalk_code" types will be for the mapping-level attributes
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.
targets	Required, if mapping object is present	Array of objects containing a "targetCode"	If user does not provide a targets array, it won't create any mappings for that created crosswalk
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.

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",
  "invalidCodes": [
    "code": "93309",
    "codeSystem": "cpt2025"
  ]
}

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. If either one or both sourceCode or sourceCodeSystem are not provided in the URL: like so:

GET /crosswalks?pageSize=100&pageNumber=1

Then a list of all crosswalks for the user's organization will be returned

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. The maximum value is 100 and the minimum value is 1
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": [
        {
          "identifier": "59e6f7a0-1a40-4154-9b3f-9ce79a30d5ee"
          "attributeKey": "Sub-category",
          "attributeValue": "Echocardiography Procedures",
          "attributeType": "crosswalk_version"
        },
        {
          "identifier": "0cef1d08-56d5-4e2d-9469-911c4ebc2e88"
          "attributeKey": "Sub-category",
          "attributeValue": "Placeholder value stored since this is not the mapping itself",
          "attributeType": "crosswalk_code"
        }
      ]
    }
  ]
}

GET /crosswalks/{identifier}

Get crosswalk details 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",
  "isActive": "true"
  "type": "custom",
  "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. The minimum value is 1 and the maximum value is 100
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": [
        {
          "identifier": "59e6f7a0-1a40-4154-9b3f-9ce79a30d5ee"
          "attributeKey": "Sub-category",
          "attributeValue": "Echocardiography Procedures",
          "attributeType" "crosswalk_version"
        },
        {
          "identifier": "0cef1d08-56d5-4e2d-9469-911c4ebc2e88",
          "attributeKey": "Sub-category",
          "attributeValue" "Placeholder value for crosswalk_code",
          "attributeType": "crosswalk_code"
        }
      ],
      "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": [
    {
      "identifier": "59e6f7a0-1a40-4154-9b3f-9ce79a30d5ee",
      "attributeKey": "Sub-category",
      "attributeValue": "Echocardiography Procedures",
      "attributeType": "crosswalk_version"
    },
    {
      "identifier": "0cef1d08-56d5-4e2d-9469-911c4ebc2e88",
      "attributeKey": "Sub-category",
      "attributeValue": "Placeholder value for crosswalk_code",
      "attributeType": "crosswalk_code"
    }
  ],
  "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)",
      "sourceSystem": "cpt2025",
      "targetSystem": "cpt2025",
      "targets": [
        {
          "targetCode": "93303",
          "targetDisplay": "Transthoracic echocardiography for congenital cardiac anomalies; complete",
          "identifier": "1234567a-8a9b-1234-12a1-aa123a1a1aa0",
          "customAttributes": [
            {
              "identifier": "dd4d99e8-a9c6-490a-9deb-a1a8b98a1fef"
              "key": "Sub-category",
              "value": "Actual value for crosswalk_code",
              "attributeType": "crosswalk_code"
            }
          ]
        }
      ]
    }
  ]
}

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

Add new mappings 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.

request body:

{
  "mappings": [
    {
      "sourceCode": "93351",
      "sourceCodeSystem": "cpt2025",
      "targetCodeSystem": "cpt2025",
      "targets": [
        {
          "targetCode": "93309",
        },
        {
          "targetCode": "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.
targets	Required, if mapping object is present	Array of objects containing a "targetCode"	If user does not provide a targets array, it won't create any mappings for that created crosswalk
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.

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": [
    {
      "code": "93309",
      "codeSystem": "cpt2025"
  ],
  "details": {
    "mappingsRequested": 2,
    "mappingsCreated": 1,
    "mappingDuplicates": 0,
    "mappingsInvalid": 1
  }
}

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.

request body:

{
  "mappings": [
    {
      "sourceCode": "93351",
      "sourceCodeSystem": "CPT®-4",
      "targetCodeSystem": "CPT®-4",
      "targetCodes": [
        "93303",
        "93304",
        "01234"
      ]
    }
  ]
}

Parameter	Required?	Allowable Values	Error Handling	Comments
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 name values (refer to the General section).	If user does not provide sourceCodeSystem, it will skip that mapping object and move to the next object.	The code system being passed in must be the code system names value. For example, instead of the "cpt2025" slug, it would be the code system name "CPT®-4"
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 name 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.	The code system being passed in must be the code system names value. For example, instead of the "cpt2025" slug, it would be the code system name "CPT®-4"
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."
}

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

Add one or more crosswalk-level custom attributes or mapping-level custom attribute names 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.

request body:

{
  "attributes": [
    {
      "attributeName": "New Attribute Name",
      "attributeValue": "New Attribute Value"
    }
  ],
  "attributeType": "crosswalk_version"
}

Parameter	Required?	Allowable Values	Error Handling	Comments
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 the user wants to retrieve the details for.	If the version number is not provided, user will get 404 not found error.
attributes	Required	Array of key, value pair for the Custom Attributes at the crosswalk level or mapping level
attributeName	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 422 error with a message.	Must not already be used for the given crosswalk and version for the given attribute type
attributeValue	Optional.	User can specify the key attribute name. This field allows up to 250 characters.
attributeType	Optional	"crosswalk_version" or "crosswalk_code"	If not specified, will default to "crosswalk_version"	Separate calls will need to be made for "crosswalk_code" and "crosswalk_version" type attributes

response:

{
  "message": "Attributes saved successfully.",
  "count": 1
}

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

Update one or more crosswalk-level custom attributes or mapping-level custom attribute names 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.

request body:

{
  "customAttributes": [
    {
      "crosswalkVersionAttributeIdentifier": "59e6f7a0-1a40-4154-9b3f-9ce79a30d5ee"
      "key": "Sub-category",
      "value": "Echocardiography Procedures"
    }
  ],
  "attributeType": "crosswalk_version"
}

Parameter	Required?	Allowable Values	Error Handling	Comments
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 the user wants 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.
crosswalkVersionAttributeIdentifier	Required	Identifier of the crosswalk version attribute, provided by the GET crosswalk version(s) operations in the customAttributes portion of the response (Not to be confused with the identifiers provided by the GET Mappings operation)	If user does not provide this identifier, they will get a 422 error with a message	The attribute being updated will have to actually exist under the provided crosswalk version attribute identifier and attribute type (or defaulted type)
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 422 error with a message.
value	Optional.	User can specify the key attribute name. This field allows up to 250 characters.
attributeType	Optional	"crosswalk_version" or "crosswalk_code"	If not specified, will default to "crosswalk_version"	The attribute being updated will have to actually exist under the provided attribute identifier and attribute type (or defaulted type)

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.

request body:

{
  "attributeKeys": [
    "Sub-category"
  ],
  "attributeType: "crosswalk_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.
attributeKeys	Required	Array of keys, comma separated, that needs to be deleted from the crosswalk level or mapping-level custom attributes
attributeType	Optional	Type of attribute to be deleted with the given key. Can be of type "crosswalk_version" or "crosswalk_code"	If the attribute type is not provided, the value will default to "crosswalk_version"

response:

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

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

Update one or more crosswalk mapping-level custom attribute values 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.

request body:

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

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.
attributes	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 250 characters.

response:

{
  "message": "Custom attributes modified 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 '5adb36c5-d1bc-413b-a2a0-925f985d9626' archived successfully."
}