0

5. Request/Response Structure

Background Information

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

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.

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:

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
MB Ordering professional is not required to consult a clinical decision support mechanism due to the significant hardship exception of insufficient internet access
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
MD Ordering professional is not required to consult a clinical decision support mechanism due to the significant hardship exception of extreme and uncontrollable circumstances
ME The order for this service adheres to the appropriate use criteria in the clinical decision support mechanism consulted by the ordering professional
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
MG The order for this service does not have appropriate use criteria in the clinical decision support mechanism consulted by the ordering professional
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
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)

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.

Message Type Description
{    
   "hookInstance": "F022252F-4E26-C551-FCD8-9C1792Ass99D3A",

UUID

This is the unique identifier for making subsequent client calls to this interaction. This is generated by the client and needs to be unique for each consultation.

   "hook": "order-select",

String

This is the Hook type.

   "context": {    
      "userId": "Practitioner/example",

String

This is the name or ID of the referring physician (NPI).

      "organizationId": "LogicNets",

String

Optional: This is the unique identifier for the organization and is used for reporting.

      "patientId": "1",

String

This is the unique ID for the patient.

      "draftOrders": {    
         "resourceType": "Bundle",    
         "entry": [{    
               "resource": {    
                  "resourceType": "ServiceRequest",   See http://hl7.org/fhir/servicerequest.html for more information.
                  "id": "1234",  

This is the ID from the order in the requesting system. LogicNets' CDSM does not do anything with this ID, but it is returned in our responses.

                  "status": "draft",

String

The status is always "draft", as this is the order to be validated.

                  "intent": "plan",

String

The intent is always "plan".

                  "code": {    
                     "coding": [{    
                           "display": "CT hip with contrast",

String

 
                           "code": "CT hip with contrast",

String

 
                           "system": "http://logicnets.info/fhir/value"

String

 
                        }],    
                     "text": "CT hip with contrast"

String

This is the text representation of the order to be validated.

                  },    
                  "requester": {    
                     "display": "Dr. Adam Careful",

String

This is the display name of the referring physician.

                     "reference": "Practitioner/example"

String

NPI (see userID).

                  },    
                  "subject": {    
                     "reference": "Patient/1"

String

This is the same as PatientId above.

                  },    
                  "reasonCode": [{    
                        "text": "Hip Pain",

String

This is the text representation of the indication.

                        "coding": [{  

Only one of the codes below needs to be provided for the system to trigger this AUC.

                              "code": "M25.55",

String

This is the ICD-10 code representation of the indication.

                              "system": "http://hl7.org/fhir/sid/icd-10-cm",

String

This is the ICD-10 system reference.

                              "display": "Pain in hip"

String

This is the ICD-10 display name of the indication.

                           }, {    
                              "code": "49218002",

String

This is the SNOMED code representation of the indication.

                              "system": "http://snomed.info/sct",

String

This is the SNOMED system reference.

                              "display": "Hip pain"

String

This is the SNOMED display name of the indication.

                           }]    
                     }    
                  ]    
               }    
            }    
         ]    
      }    
   },    
   "prefetch": {

Complex

You can provide existing answers or patient data in this prefetch section.

      "conditions": {    
         "resourceType": "Bundle",    
         "entry": [{    
               "resource": {    
                  "resourceType": "Condition",    
                  "code": {    
                     "coding": [{    
                           "display": "POST Total Hip Arthroplasty",    
                           "code": "POST THA",    
                           "system": "http://logicnets.info/fhir/path.value/hpa_status"    
                        }],    
                     "text": "POST Total Hip Arthroplasty"    
                  }    
               }    
            }, {    
               "resource": {    
                  "resourceType": "Condition",    
                  "code": {    
                     "coding": [{    
                           "display": "Infection",    
                           "code": "infection",    
                           "system": "http://logicnets.info/fhir/path.value/clinical_scenario_post_tha"    
                        }],    
                     "text": "Infection"    
                  }    
               }    
            }, {    
               "resource": {    
                  "resourceType": "Condition",    
                  "code": {    
                     "coding": [{    

                           "system": "http://logicnets.info/fhir/path.value/

auc_criteria_validated_hp_plus_infection_post_tha.auc_criteria_validated",

   
                           "code": "Pain or constitutional symptoms"    
                        }]    
                  }    
               }    
            }, {    
               "resource": {    
                  "resourceType": "Condition",    
                  "code": {    
                     "coding": [{    

                           "system": "http://logicnets.info/fhir/path.value/

auc_criteria_validated_hp_plus_infection_post_tha.auc_criteria_validated",

   
                           "code": "Positive lab results (WBC, ESR, CRP)"    
                        }    
                     ]    
                  }    
               }    
            }, {    
               "resource": {    
                  "resourceType": "Condition",    
                  "code": {    
                     "coding": [{    

                           "system": "http://logicnets.info/fhir/path.value/

auc_criteria_validated_hp_plus_infection_post_tha.auc_criteria_validated",

   
                           "code": "Negative or noncontributory radiographs"    
                        }]    
                  }    
               }    
            }]    
      }    
   }    
}    

Full Response Example

Message Type Description/Use
{    
   "cards" : [{    
      "extension" : [{    
         "valueCodeableConcept" : {    
            "coding" : [{    
               "system" : "http://fhir.org/argonaut/CodeSystem/pama-rating",    
               "code" : "appropriate" String This is the outcome/PAMA rating:
- appropriate
- not-appropriate
- insufficient-patient-data
- no-criteria-apply
            }]    
         },    
         "url" : "http://fhir.org/argonaut/Extension/pama-rating"    
      },    
      {    
         "url" : "http://logicnets.info/fhir/Extension/PLESpecification",    
         "valueUri" : "https://intermountainhealthcare.org/ext/Dcmnt?ncid=529526162" String This is the link to IMH resource documentation.
      },    
      {    
         "url" : "http://logicnets.info/fhir/Extension/PLELicensor",    
         "valueUri" : "Intermountain Health Services" String This is the PLE licensor.
      },    
      {    
         "valueString" : "Practitioner/example",    
         "url" : "http://logicnets.info/fhir/Extension/NPI" String This is the given NPI.
      },    
      {    
         "valueString" : "LogicNets", String This is the ID of the referring organization. This is important for reporting.
         "url" : "http://logicnets.info/fhir/Extension/ReferringOrganization"    
      },    
      {    
         "valueString" : "http://logicnets.com", String This is the CDS-M identifier. It will be LogicNets G-Code.
         "url" : "http://fhir.org/argonaut/Extension/pama-rating-qcdsm-consulted"    
      },    
      {    
         "url" : "http://fhir.org/argonaut/Extension/pama-rating-consult-id",    
         "valueUri" : "urn:uuid:067c95ab-384f-52ec-be1a-1461e1181f5b" String This is the consultation ID, which was also referred to previously as the Decision Support Number.
      },    
      {    
         "valueString" : "http://logicnets.info/cdsm/auc.version/7.4.24852/CPM3005_HP/Dec%2E%202018/1.0", String This is the version number.
         "url" : "http://fhir.org/argonaut/Extension/pama-rating-auc-applied"    
      },    
      {    
         "valueString" : "
  • Summary: The suggested order(s) 'CT hip with contrast' is/are appropriate...",
String This is the HTML representation of the conclusion report.
         "url" : "http://logicnets.info/fhir/Extension/Report"    
      }],    
      "links" : [{    
         "label" : "IMHipPain",    
         "type" : "absolute",    
         "dsn" : "urn:uuid:067c95ab-384f-52ec-be1a-1461e1181f5b",   This is the decision support number or consultation ID.
         "url" : "https://lnauc.logicnets.local/logicnets/logicnets.lns?verb=start&code=auc%5Fsession%5Fstarter&dsn=urn%3Auuid%3A067c95ab%2D384f%2D52ec%2Dbe1a%2D1461e1181f5b"    
      },    
      {    
         "label" : "IMHipPain",    
         "type" : "smart",    
         "appContext" : "{ \"dsn\":\"urn:uuid:067c95ab-384f-52ec-be1a-1461e1181f5b\"}",    

         "url" : "https://lnauc.logicnets.local/logicnets/

auc_session_starter/urn:uuid:067c95ab-384f-52ec-be1a-1461e1181f5b/launch"

   
      }],    
      "source" : {    
         "label" : "LogicNets AUC",    
         "url" : "http://www.logicnets.com"    
      },    
      "suggestions" : [{   Suggestions present alternative or more appropriate orders. This is empty if there are no alternative suggestions.
         "label" : "The guideline recommends alternative order: 'MRI hip w/ and w/o contrast'",    
         "actions" : [{    
            "resource" : {    
               "id" : "1234",    
               "reasonCode" : [{    
                  "coding" : [{    
                     "code" : "M25.55",    
                     "display" : "Pain in hip",    
                     "system" : "http://hl7.org/fhir/sid/icd-10-cm"    
                  },    
                  {    
                     "code" : "49218002",    
                     "display" : "Hip pain",    
                     "system" : "http://snomed.info/sct"    
                  }],    
                  "text" : "Hip Pain"    
               }],    
               "resourceType" : "ServiceRequest",    
               "status" : "draft",    
               "intent" : "plan",    
               "code" : {    
                  "coding" : [{    
                     "code" : "MRI hip w/ and w/o contrast",    
                     "display" : "MRI hip w/ and w/o contrast (MARS)",    
                     "system" : "http://logicnets.info/fhir/value"    
                  }],    
                  "text" : "MRI hip w/ and w/o contrast"    
               },    
               "subject" : {    
                  "reference" : "Patient/1"    
               },    
               "requester" : {    
                  "display" : "Dr. Adam Careful",    
                  "reference" : "Practitioner/example"    
               }    
            },    
            "type" : "update"   This indicates that the action is of type update.
         }],    
         "uuid" : "EFAD2EB2-0744-719E-5452-2D5958984937"    
      }],    
      "outcome" : "appropriate",   This is the outcome of the validation request.
      "decisions" : [{   The decisions contain the questions and their answers in the pathway of the guideline. Note that this section returns all the decision nodes when no prefetch data has been provided.
         "resourceType" : "QuestionnaireResponse",    
         "item" : {    
            "linkedId" : "hpa_status",    
            "text" : "Does the patient have hip pain  after having had  a Total Hip Arthroplasty (THA)?",   This is the question in the guideline.
            "answer" : [{   This is the codified answer that the user provided.
               "valueCoding" : {    
                  "caption" : "POST Total Hip Arthroplasty",    
                  "code" : "POST THA",    
                  "system" : "http://logicnets.info/fhir/path.value/hpa_status"   Read this as hpa_status="POST THA".
               }    
            }]    
         }    
      },    
      {    
         "resourceType" : "QuestionnaireResponse",    
         "item" : {    
            "linkedId" : "clinical_scenario_post_tha",    
            "text" : "Suspected clinical scenario",    
            "answer" : [{    
               "valueCoding" : {    
                  "caption" : "Infection",    
                  "code" : "infection",    
                  "system" : "http://logicnets.info/fhir/path.value/clinical_scenario_post_tha"    
               }    
            }]    
         }    
      },    
      {    
         "resourceType" : "QuestionnaireResponse",    
         "item" : {    
            "linkedId" : "auc_criteria_validated_hp_plus_infection_post_tha.auc_criteria_validated",    
            "text" : "AUC met (IF ALL)?",    
            "answer" : [{    
               "valueCoding" : {    
                  "caption" : "Pain or constitutional symptoms",    
                  "code" : "Pain or constitutional symptoms",    

                  "system" : "http://logicnets.info/fhir/path.value/

auc_criteria_validated_hp_plus_infection_post_tha.auc_criteria_validated"

   
               }    
            },    
            {    
               "valueCoding" : {    
                  "caption" : "Positive lab results (WBC, ESR, CRP)",    
                  "code" : "Positive lab results (WBC, ESR, CRP)",    

                  "system" : "http://logicnets.info/fhir/path.value/

auc_criteria_validated_hp_plus_infection_post_tha.auc_criteria_validated"

   
               }    
            },    
            {    
               "valueCoding" : {    
                  "caption" : "Negative or noncontributory radiographs",    
                  "code" : "Negative or noncontributory radiographs",    

                  "system" : "http://logicnets.info/fhir/path.value/

auc_criteria_validated_hp_plus_infection_post_tha.auc_criteria_validated"

   
               }    
            }]    
         }    
      },    
      {    
         "resourceType" : "QuestionnaireResponse",    
         "item" : {    
            "linkedId" : "auc_criteria_validated_hp_plus_infection_post_tha.auc_criteria_validated_met",    
            "text" : "",    
            "answer" : [{    
               "valueCoding" : {    
                  "caption" : "Yes",    
                  "code" : "Yes",    

                  "system" : "http://logicnets.info/fhir/path.value/

auc_criteria_validated_hp_plus_infection_post_tha.auc_criteria_validated_met"

   
               }    
            }]    
         }    
      },    
      {    
         "resourceType" : "QuestionnaireResponse",    
         "item" : {    
            "linkedId" : "_orders.orderp",    
            "text" : "Imaging: primary recommendation",    
            "answer" : []    
         }    
      },    
      {    
         "resourceType" : "QuestionnaireResponse",    
         "item" : {    
            "linkedId" : "_orders.ordera",    
            "text" : "Imaging: alternative recommendation",    
            "answer" : [{    
               "valueCoding" : {    
                  "caption" : "CT hip with contrast (MARS)",    
                  "code" : "CT hip with contrast",    
                  "system" : "http://logicnets.info/fhir/path.value/_orders.ordera"    
               }    
            }]    
         }    
      },    
      {    
         "resourceType" : "QuestionnaireResponse",    
         "item" : {    
            "linkedId" : "_orders.order_selected",    
            "text" : "",    
            "answer" : [{    
               "valueCoding" : {    
                  "caption" : "Yes",    
                  "code" : "Yes",    
                  "system" : "http://logicnets.info/fhir/path.value/_orders.order_selected"    
               }    
            }]    
         }    
      }],    
      "detail" : "Hip Pain",    
      "indicator" : "info",    
      "summary" : "The suggested order(s) 'CT hip with contrast' is/are appropriate according to the guideline but 'MRI hip w/ and w/o contrast' is/are more appropriate"   This is the summary text of the outcome.
   }],    
   "extension" : {   This is the card extension with response details. In this case, these are the same as the extension details in the card above.
      "systemActions" : [{    
         "resource" : {    
            "extension" : [{    
               "valueCodeableConcept" : {    
                  "coding" : [{    
                     "system" : "http://fhir.org/argonaut/CodeSystem/pama-rating",    
                     "code" : "appropriate"    
                  }]    
               },    
               "url" : "http://fhir.org/argonaut/Extension/pama-rating"    
            },    
            {    
               "url" : "http://logicnets.info/fhir/Extension/PLESpecification",    
               "valueUri" : "https://intermountainhealthcare.org/ext/Dcmnt?ncid=529526162"    
            },    
            {    
               "url" : "http://logicnets.info/fhir/Extension/PLELicensor",    
               "valueUri" : "Intermountain Health Services"    
            },    
            {    
               "valueString" : "Practitioner/example",    
               "url" : "http://logicnets.info/fhir/Extension/NPI"    
            },    
            {    
               "valueString" : "LogicNets",    
               "url" : "http://logicnets.info/fhir/Extension/ReferringOrganization"    
            },    
            {    
               "valueString" : "http://logicnets.com",    
               "url" : "http://fhir.org/argonaut/Extension/pama-rating-qcdsm-consulted"    
            },    
            {    
               "url" : "http://fhir.org/argonaut/Extension/pama-rating-consult-id",    
               "valueUri" : "urn:uuid:067c95ab-384f-52ec-be1a-1461e1181f5b"    
            },    
            {    
               "valueString" : "http://logicnets.info/cdsm/auc.version/7.4.24852/CPM3005_HP/Dec%2E%202018/1.0",    
               "url" : "http://fhir.org/argonaut/Extension/pama-rating-auc-applied"    
            },    
            {    
               "valueString" : "Summary: The suggested order(s) 'CT hip with contrast' is/are appropriate... "    
               "url" : "http://logicnets.info/fhir/Extension/Report"    
            }]    
         }    
      }]    
   }    
}    
Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular
Like Follow
  • 1 hr agoLast active
  • 273Views
  • 4 Following

Home