CodeValidate API

Overview 

  • Accepts procedure and diagnosis codes, date of service, Medicare contractor number, location and type of claim. 
  • Response contains issues, messages, and exceptions associated with the claim. 
  • Checks code combinations for possible Medicare medical necessity or bundling issues with verification of NCD, LCD and NCCI edits.
  • VitalWare also provides a CodeValidate HTML control widget that you can embed into your browser-based application.

Walkthrough: CodeValidate Request

{  
 "codeCheckTypes":["LCD"],
    "effectiveDate": "2015-10-01",
    "providerType": "Facility",
    "state": "IL",
    ...
}

Request:  Preparing a Request

The following parameters are required when forming a request:

  • codeCheckTypes
  • effectiveDate 

Note that LCDs and Articles are combined, and specifying "Article" in the codeCheckTypes parameter is not required if "LCD" is already passed.

In this example, we check against LCDs and Articles.  We are also required to provide a specific contractor or provider type and location information that enables the service to pick a default contractor for that location.

  • To use a specific contractor, include contractorNumber in the request.
  • To use a default contractor, include providerType and either state or postalCode. This walkthrough uses "default contractor."
  • Add procedure and diagnosis codes to validate using the cptCodes and icdCodes parameters. 
{
    "codeCheckTypes": ["LCD"],
    "effectiveDate": "2015-10-01",
    "providerType": "Facility",
    "state": "IL",
    "cptCodes" : ["93325", "C8923"],
    "icdCodes": ["A40.3", "Z01.818", "B99.8"],
    "icdType": "ICD-10 CM"
}

XML Output 

<CodeCheckRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns="http://www.w3.org/2001/XMLSchema">
  <codeCheckTypes>LCD</codeCheckTypes>
  <effectiveDate>2014-07-23T00:00:00</effectiveDate>
  <providerType>Facility</providerType>
  <state>IL</state>
  <cptCodes>93325</cptCodes>
  <cptCodes>C8923</cptCodes>
  <icdCodes>A40.3</icdCodes>
  <icdCodes>Z01.818</icdCodes>
  <icdCodes>B99.8</icdCodes>
  <icdType>ICD-10 CM</icdType>
</CodeCheckRequest>

For more details on request parameters, please see CodeValidate API Request Parameters below.

Response:  Interpreting the Response

The response contains details for both the codes entered and policy sources that were referenced. The items property contains hierarchical validation results for each procedure, and also for each diagnosis in combination with the procedure. The type of information returned for each code combination includes:

  • Whether or not the code combination meets medical necessity
  • Informational messages
  • Exceptions by age, gender, or frequency
  • Policy sources referenced

Sample Response: 

{
  "count": 2,
  "result": {
    "codes": {
      "93325": {
        "codeId": 312324,
        "shortDescription": "DOPPLER COLOR FLOW ADD-ON",
        "longDescription": "Doppler echocardiography color flow velocity mapping  
          (List separately in addition to codes for echocardiography)",
        "codeType": "CPT",
        "isValid": true,
        "statusIndicator": "N"
      },
      "C8923": {
        "codeId": 448742,
        "shortDescription": "2D TTE w or w/o fol w/con,co",
        "longDescription": "Transthoracic echocardiography with contrast, or without 
          contrast followed by with contrast, real-time with image documentation 
          (2d), includes m-mode recording, when performed, complete, without  
          spectral or color doppler echocardiography",
        "codeType": "HCPCS",
        "isValid": true,
        "statusIndicator": "S"
      },
      ...
    },
    "policies": {
      "L33577": {
        "policyType": "L",
        "title": "Transthoracic Echocardiography (TTE)",
        "version": 11,
        "isInLibrary": true
      },
      "L33579": {
        "policyType": "L",
        "title": "Transesophageal Echocardiography (TEE)",
        "version": 6,
        "isInLibrary": true
      }
    },
    "items": [
      {
        "code": "93325",
        "messages": [
          {
            "policy": "L33577",
            "message": "L33577 * This CPT code is always performed in addition to  
              the primary service or procedure and must never be reported as 
              a stand-alone code."
          }
        ],
        "status": "Error",
        "subItems": [
          {
            "issues": [
              {
                "policy": "L33577",
                "status": "OK",
                "message": "Per policy L33577, A40.3 supports medical necessity"
              },
              {
                "policy": "L33579",
                "status": "Warning",
                "message": "Per policy L33579, HCPCS 93325 with diagnosis A40.3 
                  meets medical necessity but has additional restrictions 
                  based on age, gender and/or frequency. (see policy)"
              }
            ],
            "code": "A40.3",
            "exceptions": [
              {
                "policy": "L33579",
                "exception": "Frequency",
                "status": "Warning",
                "message": "L33579 * TEE services covered twice per year."
              }
            ],
            "status": "Warning",
            "policies": [
              "L33577",
              "L33579"
            ]
          },
          {
            "issues": [
              {
                "policy": "L33579",
                "status": "Error",
                "message": "Per policy L33579, B99.8 does not support medical 
                  necessity"
              },
              {
                "policy": "L33577",
                "status": "Error",
                "message": "Per policy L33577, B99.8 does not support medical 
                  necessity"
              }
            ],
            "code": "B99.8",
            "status": "Error",
            "policies": [
              "L33579",
              "L33577"
            ]
          },
          {
            "issues": [
              {
                "policy": "L33579",
                "status": "Error",
                "message": "Per policy L33579, Z01.818 does not support medical 
                  necessity"
              }
            ],
            "code": "Z01.818",
            "status": "Error",
            "policies": [
              "L33579"
            ]
          }
        ]
      },
      ...
    ]
  },
  ...
}

In this example:

  • The procedure code 93325 meets medical necessity with diagnosis code A40.3, but it does not with B99.8 or Z01.818.
  • When encountering items that include the "Error" status, the cause is usuallyy within the issues array, each including a reference to the specific policy source. For convenience, status values are summarized and rolled up to the parent item.
  • You should also notice that some items contain messages arrays that are not associated with any type of status. These are informational in nature and include a reference to the policy source.
  • This example contains exception information returned for diagnosis code A40.3. In this case, there are frequency limitations that may apply. Exceptions are returned with a "Warning" status when it cannot be determined whether they apply or not.
  • Patient-related exceptions, such as age or gender, can return as "OK" or "Error" if patient information is provided in the request.

For more details on responses, please see the CodeValidate API Response and ResultItem/ResultSubItem below.

CodeValidate API Reference

CodeValidate Request Parameters

Property Data type Description
codeCheckTypes string[] One or more source types to validate against. Valid values include:
  • "LCD" - LCDs and Articles
  • "NCD"
  • "CMS" - CMS Manuals
  • "Transmittal"
  • "MLM" - MLN Matters
  • "Commercial"
cptCodes string[] One or more CPT/HCPCS codes on the claim.
contractorNumber string Contractor number used when validating against LCDs/Articles. When "LCD" is included in codeCheckTypes, you must include either contractorNumber or a combination of state or postalCode along with providerType to use the default contractor for the location. (see below)
state string State abbreviation used in combination with providerType to find the default contractor for LCDs/Articles.
postalCode string Postal code used in combination with providerType to find the default contractor for LCDs/Articles.
providerType string Type of provider used in combination with state or postalCode to find the default contractor for LCDs/Articles.. Valid values include:
  • "Facility"
  • "Physician"
  • "DME"
  • "HomeHealth"
payerCode string Commercial payer code provided by Vitalware.  When "Commercial" is included in codeCheckTypes, you must include the payerCode property.
effectiveDate Date Date of service
icdCodes string[] One or more diagnosis codes on the claim.
icdType string The diagnosis code type. Valid values include:
  • "ICD-9 CM"
  • "ICD-10 CM"
patient PatientProfile Optional patient information that can be used to return more specific age or gender exception information. Parameters in this structure include:
Parameter Data type Description
age int Optional patient age.
birthdate date Optional patient birth date that can be used to calculate age on date of service.
gender string Optional patient gender. Values include "Male" and "Female"
cptIcdMapping Dictionary <string,string[]> For advanced usage, this allows you to override the default behavior of validating any diagnoses against any procedure. This dictionary is keyed by CPT/HCPCS code and contains the diagnosis codes to check against it. These codes must be passed exactly as they are in the cptCodes and icdCodes parameters.

CodeValidate API Response

After processing the request, the service returns results in a generic wrapper which contains the number of items (count) and the result payload (result). The contents of the result payload are as follows:

Property Data type Description
codes Dictionary <string,CodeDetail> A dictionary keyed by code, containing code details for all procedure and diagnoses codes passed in. The CodeDetail properties include:
Property Data type Description
shortDescription string Short code description
longDescription string Long code description
codeType string Type of code
isValid bool Whether or not the code was found and is valid
invalidReason string Reason code was not valid. Valid values include:
  • "NotFound"
  • "Deleted"
  • "Invalid"
statusIndicator string Status indicator associated with code
policies Dictionary <string,PolicySummary> A dictionary keyed by policy label, containing information for all sources referenced. The PolicySummary properties include:
Property Data type Description
policyType string Source type. Values include:
  • "L" - LCD
  • "A" - Article
  • "N" - NCD
  • "C" - CMS Manual
  • "T" - Transmittal
  • "M" - MLN Matter Article
  • "P" - Commercial/Medicaid
title string Source title
version int Source version, if applicable
documentationRequirements string Documentation requirements that apply to source
indications string Indications that apply to source
limitations string Limitations that apply to source
utilizationRequirements string Utilization requirements that apply to source
publication string Publication number, if applicable
isInLibrary bool Whether or not source is in VW library
items ResultItem[] Validation results for each of the passed in CPT/HCPCS codes, see below for more information about properties within a ResultItem.

ResultItem, ResultSubItem

  • ResultItem and ResultSubItem objects are identically defined except that a ResultItem contains one or more ResultSubItem objects within it.
  • ResultItem objects contain validation results for each CPT/HCPCS code, while ResultSubItem objects contain validation for a diagnosis in relation to the CPT/HCPCS code it is contained within.
  • You should expect to see exactly one ResultItem per CPT/HCPCS code passed in, and within each one, exactly one ResultSubItem per diagnosis code. This is true regardless if the code is valid or invalid.
subItems ResultSubItem[] Validation results for each diagnosis code in combination with the CPT/HCPCS code for the ResultItem. NOTE: This property is only present on ResultItem objects.
code string The procedure or diagnosis code
exceptions ResultItemException[] Exceptions for this code, such as age, gender or frequency. Properties within each include:
Property Data type Description
policy string Source for exception
exception string Type of exception. Possible values include:
  • "Age"
  • "Gender"
  • "Frequency"
status string Status associated with exception. Values include:
  • "OK"
  • "Warning"
  • "Error"
message string Message for exception
issues ResultItemIssue[] Information specific to the code or code combination. This may include message related to policy sources that are informational or may be error messages. Properties within each issue include:
Property Data type Description
policy string Source for issue
status string Status associated with issue. Values include:
  • "OK"
  • "Warning"
  • "Error"
message string Message for issue
messages ResultItemMessage[] Informational messages specific to the code or code combination. Properties within each message include:
Property Data type Description
policy string Source for exception
message string Message content
status string Status associated with code or code combination rolled up from issues contained within this item. Values include:
  • "OK"
  • "Warning"
  • "Error"
  • "PolicyNotFound"
  • "InvalidCode"
  • "DeletedCode"
policies string[] Policy sources that were referenced for this code combination.