5. Request/Response Structure

Background Information

This topic details the structure of requests and responses for the AUC API.

• For more information on the CDS-Hooks interface see: https://cds-hooks.org.
• For more information on the FHIR notation see: http://hl7.org/fhir/.
• For more information on the Argonaut project see: https://argonautproject.github.io/cds-hooks-for-pama/.

Making the Call

To access the API you need to use the following end-point:

https://auc.logicnets.net/auc/auc-hook

You can add the following parameter:

mode = "test"

The full URL would look like this:

https://auc.logicnets.net/auc/auc-hook?mode=test

This will instruct the webservice to not generate the final UCI and will cause the transaction not be charged for. We recommend to use this parameter during the development and testing of your web service integration work.

Additionally you can specify if the AUC webservice will run in strict or relaxed mode. In strict mode the given order set and indication will be evaluated against the recommended order set. The outcome is appropriate only when there is an exact match between all the orders. The outcome is incomplete order in case there is a partial match and not-appropriate if there is no match at all. 

validation_mode=strict (default if no parameter is provided)

Adding the relaxed mode value to the validation_mode parameter will return an appropriate outcome in case there is a partial match. Many client applications can only present one order at the time to the AUC Web Service. In this mode a single order will be validated as appropriate when this single order is part of a recommended order set.

validation_mode=relaxed

CDS-Hooks Request Structure

The initial request consists of the following main structure, according to the cds-hooks protocol:

{
   "context": {
      "userId": "Practitioner/example",
      "organizationId": "LogicNets",
      "patientId": "1",
      "draftOrders": {
         "resourceType": "Bundle",
         "entry": []
      }
   },
   "hookInstance": "61ed65d1-5dda-4398-923e-71064d04748f",
   "hook": "order-select",
   "prefetch": {}
}

The AUC validation request may require multiple round trips, so the client should generate a unique hookInstance ID (see line 11 in the image above). This ID needs to be used for each of the multiple requests during the validation process. You must generate a new hookInstance ID for a new validation.

In the client, we generate the hookInstance ID uuid with the jQuery.fn.uuid function on line 65.

In this example we left the prefetch section empty. You can use this section to specify patient data, which you can map to the decision points in the guidelines. 

Draft Orders ServiceRequest Structure

The entry section specifies the ServiceRequest with the draft order (see lines 8-17 below). It also specifies the reason/indication that needs to be validated by a guideline (see lines 25-41 below).

"entry": [
            {
               "resource": {
                  "resourceType": "ServiceRequest",
                  "id": "1234",
                  "status": "draft",
                  "intent": "plan",
                  "code": {
                     "coding": [
                        {
                           "display": "CT hip w/ contrast (MARS)",
                           "code": "CT hip w/ contrast (MARS)",
                           "system": "http://logicnets.info/fhir/value"
                        }
                     ],
                     "text": "CT hip w/ contrast (MARS)"
                  },
                  "requester": {
                     "display": "Dr. Adam Careful",
                     "reference": "Practitioner/example"
                  },
                  "subject": {
                     "reference": "Patient/1"
                  },
                  "reasonCode": [
                     {
                        "text": "Hip Pain",
                        "coding": [
                           {
                              "code": "M25.55",
                              "system": "http://hl7.org/fhir/sid/icd-10-cm",
                              "display": "Pain in hip"
                           },
                           {
                              "code": "49218002",
                              "system": "http://snomed.info/sct",
                              "display": "Hip pain"
                           }
                        ]
                     }
                  ]
               }
            }
         ]

Order

The imaging order is specified in the code section (see lines 8-17 above), and in the example above we used our internal LogicNets code system. You can also use the CPT code system, which would look like this:  

"code": {
   "coding": [
      {
         "display": "CT hip w/ contrast (MARS)",
         "code": "73701",
         "system": "http://www.ama-assn.org/go/cpt"
      }
   ],
   "text": "CT hip w/ contrast (MARS)"
},

Reason/Indication

The reason or indication is specified in the reasonCode section of the ServiceRequest. In the example below you see an example of both ICD-10 and SNOMED. You can use either one to map to the correct guideline.

"reasonCode": [
     {
        "text": "Hip Pain",
        "coding": [
           {
              "code": "M25.55",
              "system": "http://hl7.org/fhir/sid/icd-10-cm",
              "display": "Pain in hip"
           },
           {
              "code": "49218002",
              "system": "http://snomed.info/sct",
              "display": "Hip pain"
           }
        ]
     }
  ]

 

In article Guideline Reason Codes (SNOMED, ICD-10, LN) we have specified which guidelines map to which indications. If you need other code systems to be mapped, such as ICD-9, please contact us.

The Response

The structure of the data is in the form of an array of "cards", also called "app-link-cards". These cards have a complete set of information for each guideline that matched the ReasonCode in the request.

If you do not provide a ReasonCode the system will iterate through all the guidelines and return app-link-cards for all the guidelines that reference the imaging order.

 

Each card contains the basic cds-hooks elements. The extension element is used to map the additional AUC data in the response.   

The returned AUC elements are:

pama-rating
Code values: appropriate, not-appropriate, no-criteria-apply
Type: codeableConcept
appropriate corresponds with what CMS describes as "adheres to appropriate use criteria"
not-appropriate corresponds with "does not adhere to appropriate use criteria"
no-criteria-apply corresponds with "there is no appropriate use criteria applicable".

When running the LogicNets AUC webservice in strict mode an incompete-order set returns a pama-rating as not-appropriate. When running the LogicNets AUC webservice in relaxed mode an incomplete order set returns a pama-rating as appropriate.

This is empty in certain situations (e.g. testmode, no (valid) contract number supplied)

 

HCPCSModifier
Code values: MA, MB, MC, MD, ME, MF, MG, MH, QQ
Type: string

The following HCPCS modifiers have been established for this program for placement on the same line as the CPT code for the advanced diagnostic imaging service. See also what outcomes are generated by the webservice:

MA Ordering professional is not required to consult a clinical decision support mechanism due to service being rendered to a patient with a suspected or confirmed emergency medical condition. The outcome can still be insufficient-patient-data, appropriate, not-appropriate), but modifier MA is returned.
MB Ordering professional is not required to consult a clinical decision support mechanism due to the significant hardship exception of insufficient internet access. No outcome is applicable.
MC Ordering professional is not required to consult a clinical decision support mechanism due to the significant hardship exception of electronic health record or clinical decision support mechanism vendor issues. No outcome is applicable.
MD Ordering professional is not required to consult a clinical decision support mechanism due to the significant hardship exception of extreme and uncontrollable circumstances. No outcome is applicable.
ME The order for this service adheres to the appropriate use criteria in the clinical decision support mechanism consulted by the ordering professional. The outcome is appropriate.
MF The order for this service does not adhere to the appropriate use criteria in the qualified clinical decision support mechanism consulted by the ordering professional. The outcome is not-appropriate.
MG The order for this service does not have appropriate use criteria in the clinical decision support mechanism consulted by the ordering professional. No outcome is applicable.
MH Unknown if ordering professional consulted a clinical decision support mechanism for this service, related information was not provided to the furnishing professional or provider. The outcome is Insufficient-patient-data.
QQ Ordering professional consulted a qualified clinical decision support mechanism for this service and the related data was provided to the furnishing professional (effective date: 7/1/18). The outcome is not applicable. This is not an outcome from a CDSM, the furnishing provider needs to provide this.

PLESpecification
Type: uri
Link to location of PLE guideline used in consultation stored on PLE location as part of documentation.
Example: https://intermountainhealthcare.org/ext/Dcmnt?ncid=529526162

Specification
Type: uri
Link to location of PLE guideline used in consultation stored on LogicNets location as part of documentation.
Example: https://rel746.logicnets.local/packages/IMHipPain/documents/Dcmnt.pdf

Icon
Type: string
Points to image associated with the guideline that is consulted. This image can be used in the representation of the result UI/report.
Example: https://rel746.logicnets.local/packages/IMHipPain/images/HP_icon.png

PLELicensor
Type: string
The organization that provided the guidelines used in the validation and approved by CMS. In our CDSM Intermountain Healthcare and NCCN are PLE licensors.

ClinicalPriorityArea
Type: string
This is the name of the guideline that is used to perform the validation.
Example: Hip Pain

NPI
Type: string
Represents the NPI for who the consultation will be recorded. The consultations and future compliance requirements from CMS will be associated.
Example: 1245319599

ReferringOrganization
Type: string
This is the same string as provided as part of the request: organizationId.

DraftOrder
Type: object
This object contains the array of entries as specified in the original request.

pama-rating-qcdsm-consulted
Type: string
CMS-assigned identifier for this Qualified CDS Mechanism consulted (also known as a "G-code"). LogicNets’ G code is: G1019

pama-rating-consult-id
Type: uri
Unique correlation handle that can be used for audit logging and, if needed, reporting to CMS as the Unique Consultation Identifier (UCI).
Note that this field can be returned empty in case the webservice was called in test mode (by adding mode=test to start URL, see above) or if the contract number is not valid.
Example: urn:uuid:9a7584c1-a1eb-fa7c-9fe1-437b1ba44040

pama-rating-auc-applied
Type: uri
URL indicating the AUC applied. This value can be helpful, for example, to assess which specific AUCs are most often over-ridden.
Example: http://logicnets.info/cdsm/auc.version/7.4.6.32967/CPM3005_HP/Apr%2E%202021/1.0

report
Type: string
This string contains a report in HTML explaining the outcome of the consultation. This can be rendered in a browser to a user for outcome information.

Links
Type: array
Launchable URLs for starting the interactive application to complete consultation. Array contains an absolute link and a smart link format. The smart link is formatted for SmartonFHIR launching.

 

URL Configuration

The URL in the response card can be used to launch and interactive dialog with a user. You can render this for example in an iframe. Please see 6. API Sample Client JavaScript Implementation for more information on this.

  

This URL can be configured by appending the following parameters:

textonly=1

This will force the interactive dialog to only show the question panel and no graphical representation of the pathway.

 

disallow_update_draft_order=1

This will disable the update order button in the order recommendation screen. Some clients do not support a programmatic update of the originating order. If that is the case, you can use this parameter to not show this button in the interactive dialog.

 

Full Request Example

Note: Depending on the size of your screen, you may need to go to the bottom of the topic and use the scroll bar to see the full article.

Full Response Example