- Previous: ICD Search API
- Up: APIs
- Next: CCI/MUE API
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.
- For details on all properties in the CodeValidate API see the CodeValidate API Reference below.
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.
- Add procedure and diagnosis codes to validate using the cptCodes and icdCodes parameters.
- 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."
- To include patient demographics, include patient object in the request.
{ "codeCheckTypes": ["LCD"], "patient": { "gender": "m", "birthdate": "1970-01-01" }, "effectiveDate": "2015-10-01", "providerType": "Facility", "state": "IL", "cptCodes" : ["93325", "C8923"], "icdCodes": ["A40.3", "Z01.818", "B99.8"], "icdType": "ICD-10 CM" }
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" }, "A40.3": { "codeId": 99152, "shortDescription": "Sepsis due to Streptococcus pneumoniae", "longDescription": "Sepsis due to Streptococcus pneumoniae", "codeType": "ICD-10 CM", "isValid": true, "priorAuthReq": false, "unacceptablePrincipalDx": false, "minAge": 0, "maxAge": 124 }, ... }, "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:
|
||||||||||||
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:
|
||||||||||||
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:
|
||||||||||||
patient | PatientProfile | Optional patient information that can be used to return more specific age or gender exception information. Parameters in this structure include:
|
||||||||||||
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:
|
||||||||||||||||||||||||||||||||||||
policies | Dictionary <string,PolicySummary> | A dictionary keyed by policy label, containing information for all sources referenced. The PolicySummary properties include:
|
||||||||||||||||||||||||||||||||||||
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:
|
|||||||||||||||
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:
|
|||||||||||||||
messages | ResultItemMessage[] | Informational messages specific to the code or code combination. Properties within each message include:
|
|||||||||||||||
status | string | Status associated with code or code combination rolled up from issues contained within this item. Values include:
|
|||||||||||||||
policies | string[] | Policy sources that were referenced for this code combination. |
- Previous: ICD Search API
- Up: APIs
- Next: CCI/MUE API