CDS Hooks API

Supported Operations

All following CDS Hooks operations are NOT publicly accessible. If you want to access them from third party application read Application/Client Management — configure Client resources for programmatic API access with OAuth 2.0 flows or Basic Auth.

Discovery

Returns the list of CDS Services available on this server.

Endpoint: GET [base]/cds-services

Response: A JSON object containing an array of available CDS Services with their configuration, including supported hooks, prefetch templates, and usage requirements.

Example:

GET /cds-services
Accept: application/json

{
  "services": [
    {
      "id": "order-sign-crd",
      "hook": "order-sign",
      "title": "CRD Prior Authorization (Order Sign)",
      "description": "Provides final prior authorization determination when orders are being signed",
      "prefetch": {
        "patient": "Patient/{{context.patientId}}",
        "encounter": "Encounter/{{context.encounterId}}",
        "coverage": "Coverage?patient={{context.patientId}}&status=active"
      },
      "usageRequirements": "Requires context.patientId and at least one order in context.draftOrders"
    }
  ]
}

Field	Type	Description
services	array	Array of available CDS Service definitions
services[].id	string	Unique identifier for this CDS Service
services[].hook	code	The hook this service should be invoked on (e.g., `order-sign`, `order-select`)
services[].title	string	Human-readable name of this service
services[].description	string	Description of what this service does
services[].prefetch	object	Key/value pairs of FHIR queries for prefetch data
services[].usageRequirements	string	Human-readable description of any preconditions for using this service

order-sign

The order-sign hook fires when a clinician is ready to sign one or more orders for a patient (including orders for medications, procedures, labs, and other orders). This hook is among the last workflow events before an order is promoted out of a draft status. The context contains all order details, such as dose, quantity, route, etc., although the order has not yet been signed and therefore still exists in a draft status.

For more details, see the official order-sign hook specification .

Endpoint: POST [base]/cds-services/order-sign-crd

Request: A CDS Hooks request containing the hook context with draft orders and optional prefetch data.

Response: A CDS Hooks response containing Cards with coverage requirements, prior authorization information, or suggestions.

Context

Field	Optionality	Prefetch Token	Type	Description
userId	REQUIRED	Yes	string	The id of the current user (e.g., `PractitionerRole/123` or `Practitioner/abc`)
patientId	REQUIRED	Yes	string	The FHIR Patient.id of the current patient in context
encounterId	OPTIONAL	Yes	string	The FHIR Encounter.id of the current encounter in context
draftOrders	REQUIRED	No	Bundle	A Bundle of FHIR request resources with a draft status, representing orders that aren't yet signed

Request Parameters

Field	Optionality	Type	Description
hook	REQUIRED	string	Must be `order-sign`
hookInstance	REQUIRED	string	A universally unique identifier for this particular hook call
context	REQUIRED	object	Hook-specific contextual data (see Context table above)
fhirServer	OPTIONAL	URL	The base URL of the CDS Client's FHIR server
fhirAuthorization	OPTIONAL	object	OAuth 2.0 bearer access token for FHIR server access
prefetch	OPTIONAL	object	FHIR data that was prefetched by the CDS Client

Example:

The response content depends on the external decision-making service configured via CDS_DECISION_SERVICE_URL. The example above shows a typical response structure, but actual Cards, suggestions, and links are generated by your decision service based on coverage requirements and prior authorization rules.

POST /cds-services/order-sign-crd
Content-Type: application/json
Accept: application/json

{
  "hook": "order-sign",
  "hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
  "fhirServer": "https://ehr.example.com/fhir",
  "fhirAuthorization": {
    "access_token": "some-opaque-fhir-access-token",
    "token_type": "Bearer",
    "expires_in": 300,
    "scope": "user/Patient.read user/Observation.read",
    "subject": "cds-service"
  },
  "context": {
    "userId": "PractitionerRole/123",
    "patientId": "1288992",
    "encounterId": "89284",
    "draftOrders": {
      "resourceType": "Bundle",
      "entry": [
        {
          "resource": {
            "resourceType": "MedicationRequest",
            "id": "smart-MedicationRequest-103",
            "status": "draft",
            "intent": "order",
            "medicationCodeableConcept": {
              "coding": [
                {
                  "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                  "code": "617993",
                  "display": "Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension"
                }
              ]
            },
            "subject": {
              "reference": "Patient/1288992"
            },
            "dosageInstruction": [
              {
                "text": "5 mL bid x 10 days",
                "timing": {
                  "repeat": {
                    "frequency": 2,
                    "period": 1,
                    "periodUnit": "d"
                  }
                },
                "doseAndRate": [
                  {
                    "doseQuantity": {
                      "value": 5,
                      "unit": "mL",
                      "system": "http://unitsofmeasure.org",
                      "code": "mL"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  },
  "prefetch": {
    "patient": {
      "resourceType": "Patient",
      "id": "1288992",
      "name": [
        {
          "given": ["John"],
          "family": "Doe"
        }
      ],
      "birthDate": "1970-01-01",
      "gender": "male"
    }
  }
}

{
  "cards": [
    {
      "uuid": "7b0b3f7a-8d2b-4d8b-a6e4-8cb4d3f2a6c1",
      "summary": "Prior Authorization required for this medication",
      "detail": "Prior Authorization required, follow the attached link for documentation.",
      "indicator": "warning",
      "source": {
        "label": "CRD Decision Service",
        "url": "https://cds.example.org",
        "topic": {
          "code": "prior-auth",
          "system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/cardType",
          "display": "Prior Authorization"
        }
      },
      "links": [
        {
          "label": "Documentation Requirements",
          "url": "https://example.org/documentation-requirements",
          "type": "absolute"
        },
        {
          "label": "Launch DTR to complete Questionnaire",
          "url": "https://dtr.example.org/launch",
          "type": "smart",
          "appContext": "questionnaire=https://example.org/fhir/Questionnaire/medication-pa"
        }
      ],
      "suggestions": [
        {
          "uuid": "a2f2dfd8-3fb4-4a2e-84da-0d2d2a8b8f2a",
          "label": "Save Update To EHR",
          "isRecommended": true,
          "actions": [
            {
              "type": "update",
              "description": "Update MedicationRequest to add coverage information extension",
              "resource": {
                "resourceType": "MedicationRequest",
                "id": "smart-MedicationRequest-103",
                "status": "draft",
                "intent": "order",
                "subject": { "reference": "Patient/1288992" },
                "extension": [
                  {
                    "url": "http://hl7.org/fhir/us/davinci-crd/StructureDefinition/ext-coverage-information",
                    "extension": [
                      {
                        "url": "coverage",
                        "valueReference": { "reference": "Coverage/cov001" }
                      },
                      {
                        "url": "date",
                        "valueDate": "2026-01-07"
                      },
                      {
                        "url": "doc-needed",
                        "valueCode": "clinical"
                      },
                      {
                        "url": "questionnaire",
                        "valueCanonical": "https://example.org/fhir/Questionnaire/medication-pa"
                      }
                    ]
                  }
                ]
              },
              "resourceId": "MedicationRequest/smart-MedicationRequest-103"
            }
          ]
        }
      ]
    }
  ]
}

order-select

The order-select hook fires when a clinician selects one or more orders from a list of potential orders for a patient (including orders for medications, procedures, labs, and other orders). This hook occurs when the clinician is still in the process of selecting orders to include in the current ordering session, before they are finalized. The context contains all draft orders being considered, along with a selections array indicating which specific orders have been selected.

For more details, see the official order-select hook specification .

Endpoint: POST [base]/cds-services/order-select-crd

Request: A CDS Hooks request containing the hook context with draft orders, selections, and optional prefetch data.

Response: A CDS Hooks response containing Cards with coverage requirements, prior authorization information, or suggestions.

Context

Field	Optionality	Prefetch Token	Type	Description
userId	REQUIRED	Yes	string	The id of the current user (e.g., `PractitionerRole/123` or `Practitioner/abc`)
patientId	REQUIRED	Yes	string	The FHIR Patient.id of the current patient in context
encounterId	OPTIONAL	Yes	string	The FHIR Encounter.id of the current encounter in context
selections	REQUIRED	No	array	An array of resource references (e.g., `MedicationRequest/123`) indicating which orders from draftOrders have been selected
draftOrders	REQUIRED	No	Bundle	A Bundle of FHIR request resources with a draft status, representing orders in the current ordering session

Request Parameters

Field	Optionality	Type	Description
hook	REQUIRED	string	Must be `order-select`
hookInstance	REQUIRED	string	A universally unique identifier for this particular hook call
context	REQUIRED	object	Hook-specific contextual data (see Context table above)
fhirServer	OPTIONAL	URL	The base URL of the CDS Client's FHIR server
fhirAuthorization	OPTIONAL	object	OAuth 2.0 bearer access token for FHIR server access
prefetch	OPTIONAL	object	FHIR data that was prefetched by the CDS Client

Example:

This example shows a typical coverage information Card. Your decision service (configured via CDS_DECISION_SERVICE_URL) may return different Card types depending on coverage requirements — see Card Types Reference for the full list.

POST /cds-services/order-select-crd
Content-Type: application/json
Accept: application/json

{
  "hook": "order-select",
  "hookInstance": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fhirServer": "https://ehr.example.com/fhir",
  "fhirAuthorization": {
    "access_token": "some-opaque-fhir-access-token",
    "token_type": "Bearer",
    "expires_in": 300,
    "scope": "user/Patient.read user/Observation.read",
    "subject": "cds-service"
  },
  "context": {
    "userId": "PractitionerRole/123",
    "patientId": "1288992",
    "encounterId": "89284",
    "selections": [
      "MedicationRequest/smart-MedicationRequest-103"
    ],
    "draftOrders": {
      "resourceType": "Bundle",
      "entry": [
        {
          "resource": {
            "resourceType": "MedicationRequest",
            "id": "smart-MedicationRequest-103",
            "status": "draft",
            "intent": "order",
            "medicationCodeableConcept": {
              "coding": [
                {
                  "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                  "code": "617993",
                  "display": "Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension"
                }
              ]
            },
            "subject": {
              "reference": "Patient/1288992"
            }
          }
        },
        {
          "resource": {
            "resourceType": "ServiceRequest",
            "id": "smart-ServiceRequest-456",
            "status": "draft",
            "intent": "order",
            "code": {
              "coding": [
                {
                  "system": "http://snomed.info/sct",
                  "code": "73761001",
                  "display": "Colonoscopy"
                }
              ]
            },
            "subject": {
              "reference": "Patient/1288992"
            }
          }
        }
      ]
    }
  },
  "prefetch": {
    "patient": {
      "resourceType": "Patient",
      "id": "1288992",
      "name": [
        {
          "given": ["John"],
          "family": "Doe"
        }
      ],
      "birthDate": "1970-01-01",
      "gender": "male"
    }
  }
}

{
  "cards": [
    {
      "uuid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "summary": "Coverage information for selected medication",
      "detail": "The selected medication is covered under the patient's plan with a $25 copay.",
      "indicator": "info",
      "source": {
        "label": "CRD Decision Service",
        "url": "https://cds.example.org",
        "topic": {
          "code": "coverage-info",
          "system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/cardType",
          "display": "Coverage Information"
        }
      }
    }
  ]
}

order-dispatch

The order-dispatch hook fires when a user is dispatching one or more orders to a specific performer (e.g., a pharmacy, lab, or imaging center). This hook occurs after orders have been signed and allows CDS services to provide coverage and prior authorization guidance based on the selected performer.

For more details, see the official order-dispatch hook specification .

Endpoint: POST [base]/cds-services/order-dispatch-crd

Request: A CDS Hooks request containing the hook context with dispatched order references, performer, and optional prefetch data.

Response: A CDS Hooks response containing Cards with coverage requirements, prior authorization information, or suggestions.

Context

Field	Optionality	Prefetch Token	Type	Description
patientId	REQUIRED	Yes	string	The FHIR Patient.id of the current patient in context
dispatchedOrders	REQUIRED	No	array	An array of resource references (e.g., `ServiceRequest/123`) indicating which orders are being dispatched
performer	REQUIRED	Yes	string	A reference to the performer (e.g., `Organization/456`) to whom the orders are being dispatched
fulfillmentTasks	OPTIONAL	No	array	An array of Task resources representing fulfillment tasks for the dispatched orders

Request Parameters

Field	Optionality	Type	Description
hook	REQUIRED	string	Must be `order-dispatch`
hookInstance	REQUIRED	string	A universally unique identifier for this particular hook call
context	REQUIRED	object	Hook-specific contextual data (see Context table above)
fhirServer	OPTIONAL	URL	The base URL of the CDS Client's FHIR server
fhirAuthorization	OPTIONAL	object	OAuth 2.0 bearer access token for FHIR server access
prefetch	OPTIONAL	object	FHIR data that was prefetched by the CDS Client

Example:

The response content depends on the external decision-making service configured via CDS_DECISION_SERVICE_URL. Actual Cards, suggestions, and links are generated by your decision service based on coverage requirements and prior authorization rules.

POST /cds-services/order-dispatch-crd
Content-Type: application/json
Accept: application/json

{
  "hook": "order-dispatch",
  "hookInstance": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "fhirServer": "https://ehr.example.com/fhir",
  "fhirAuthorization": {
    "access_token": "some-opaque-fhir-access-token",
    "token_type": "Bearer",
    "expires_in": 300,
    "scope": "user/Patient.read user/ServiceRequest.read",
    "subject": "cds-service"
  },
  "context": {
    "patientId": "1288992",
    "dispatchedOrders": [
      "ServiceRequest/imaging-order-001",
      "ServiceRequest/imaging-order-002"
    ],
    "performer": "Organization/radiology-center-456",
    "fulfillmentTasks": [
      {
        "resourceType": "Task",
        "status": "draft",
        "intent": "order",
        "code": {
          "coding": [
            {
              "system": "http://hl7.org/fhir/CodeSystem/task-code",
              "code": "fulfill"
            }
          ]
        },
        "focus": {
          "reference": "ServiceRequest/imaging-order-001"
        },
        "for": {
          "reference": "Patient/1288992"
        },
        "owner": {
          "reference": "Organization/radiology-center-456"
        }
      }
    ]
  },
  "prefetch": {
    "patient": {
      "resourceType": "Patient",
      "id": "1288992",
      "name": [
        {
          "given": ["John"],
          "family": "Doe"
        }
      ],
      "birthDate": "1970-01-01",
      "gender": "male"
    },
    "coverage": {
      "resourceType": "Coverage",
      "id": "cov-001",
      "status": "active",
      "beneficiary": {
        "reference": "Patient/1288992"
      },
      "payor": [
        {
          "reference": "Organization/insurance-company-789"
        }
      ]
    }
  }
}

{
  "cards": [
    {
      "uuid": "d4e5f6a7-b8c9-0123-def4-567890123456",
      "summary": "Prior Authorization required for imaging at selected facility",
      "detail": "The selected radiology center requires prior authorization for MRI imaging under this patient's coverage.",
      "indicator": "warning",
      "source": {
        "label": "CRD Decision Service",
        "url": "https://cds.example.org",
        "topic": {
          "code": "prior-auth",
          "system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/cardType",
          "display": "Prior Authorization"
        }
      },
      "suggestions": [
        {
          "uuid": "e5f6a7b8-c9d0-1234-ef56-789012345678",
          "label": "Select in-network facility",
          "actions": [
            {
              "type": "update",
              "description": "Change performer to in-network facility",
              "resource": {
                "resourceType": "Task",
                "status": "draft",
                "intent": "order",
                "owner": {
                  "reference": "Organization/in-network-radiology-123"
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

appointment-book

The appointment-book hook fires when a user is scheduling one or more future appointments for a patient. This hook allows CDS services to provide coverage and prior authorization guidance while appointments are being proposed or booked, such as recommendations about scheduling, required documentation, or coverage limitations.

For more details, see the official appointment-book hook specification .

Endpoint: POST [base]/cds-services/appointment-book-crd

Request: A CDS Hooks request containing the hook context with proposed appointments and optional prefetch data.

Response: A CDS Hooks response containing Cards with coverage requirements, prior authorization information, or suggestions.

Context

Field	Optionality	Prefetch Token	Type	Description
userId	REQUIRED	Yes	string	The id of the current user (e.g., `Practitioner/123` or `PractitionerRole/abc`)
patientId	REQUIRED	Yes	string	The FHIR Patient.id of the current patient in context
encounterId	OPTIONAL	Yes	string	The FHIR Encounter.id of the current encounter in context
appointments	REQUIRED	No	Bundle	A Bundle of proposed Appointment resources that are being booked

Request Parameters

Field	Optionality	Type	Description
hook	REQUIRED	string	Must be `appointment-book`
hookInstance	REQUIRED	string	A universally unique identifier for this particular hook call
context	REQUIRED	object	Hook-specific contextual data (see Context table above)
fhirServer	OPTIONAL	URL	The base URL of the CDS Client's FHIR server
fhirAuthorization	OPTIONAL	object	OAuth 2.0 bearer access token for FHIR server access
prefetch	OPTIONAL	object	FHIR data that was prefetched by the CDS Client

Example:

POST /cds-services/appointment-book-crd
Content-Type: application/json
Accept: application/json

{
  "hook": "appointment-book",
  "hookInstance": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "fhirServer": "https://ehr.example.com/fhir",
  "fhirAuthorization": {
    "access_token": "some-opaque-fhir-access-token",
    "token_type": "Bearer",
    "expires_in": 300,
    "scope": "user/Patient.read user/Appointment.read",
    "subject": "cds-service"
  },
  "context": {
    "userId": "Practitioner/dr-smith-123",
    "patientId": "1288992",
    "encounterId": "89284",
    "appointments": {
      "resourceType": "Bundle",
      "entry": [
        {
          "resource": {
            "resourceType": "Appointment",
            "id": "proposed-appt-001",
            "status": "proposed",
            "serviceType": [
              {
                "coding": [
                  {
                    "system": "http://snomed.info/sct",
                    "code": "394802001",
                    "display": "General medicine"
                  }
                ]
              }
            ],
            "appointmentType": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
                  "code": "FOLLOWUP",
                  "display": "Follow-up"
                }
              ]
            },
            "description": "Follow-up appointment for chronic condition management",
            "start": "2026-02-15T09:00:00Z",
            "end": "2026-02-15T09:30:00Z",
            "participant": [
              {
                "actor": {
                  "reference": "Patient/1288992"
                },
                "status": "accepted"
              },
              {
                "actor": {
                  "reference": "Practitioner/dr-smith-123"
                },
                "status": "accepted"
              }
            ]
          }
        }
      ]
    }
  },
  "prefetch": {
    "patient": {
      "resourceType": "Patient",
      "id": "1288992",
      "name": [
        {
          "given": ["John"],
          "family": "Doe"
        }
      ],
      "birthDate": "1970-01-01",
      "gender": "male"
    },
    "coverage": {
      "resourceType": "Coverage",
      "id": "cov-001",
      "status": "active",
      "beneficiary": {
        "reference": "Patient/1288992"
      },
      "payor": [
        {
          "reference": "Organization/insurance-company-789"
        }
      ]
    }
  }
}

{
  "cards": [
    {
      "uuid": "f6a7b8c9-d0e1-2345-f678-901234567890",
      "summary": "Appointment covered under patient's plan",
      "detail": "This follow-up visit is covered with a $20 copay. No prior authorization required.",
      "indicator": "info",
      "source": {
        "label": "CRD Decision Service",
        "url": "https://cds.example.org",
        "topic": {
          "code": "coverage-info",
          "system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/cardType",
          "display": "Coverage Information"
        }
      }
    },
    {
      "uuid": "a7b8c9d0-e1f2-3456-7890-123456789abc",
      "summary": "Consider scheduling annual wellness visit",
      "detail": "Patient is due for annual wellness visit which is covered at 100% with no copay.",
      "indicator": "info",
      "source": {
        "label": "CRD Decision Service",
        "url": "https://cds.example.org",
        "topic": {
          "code": "clinical-reminder",
          "system": "http://hl7.org/fhir/us/davinci-crd/CodeSystem/cardType",
          "display": "Clinical Reminder"
        }
      },
      "suggestions": [
        {
          "uuid": "b8c9d0e1-f234-5678-90ab-cdef12345678",
          "label": "Add annual wellness visit",
          "actions": [
            {
              "type": "create",
              "description": "Schedule annual wellness visit",
              "resource": {
                "resourceType": "Appointment",
                "status": "proposed",
                "serviceType": [
                  {
                    "coding": [
                      {
                        "system": "http://snomed.info/sct",
                        "code": "410620009",
                        "display": "Annual wellness visit"
                      }
                    ]
                  }
                ],
                "participant": [
                  {
                    "actor": {
                      "reference": "Patient/1288992"
                    },
                    "status": "needs-action"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

Last updated: 2026-01-14T10:44:52Z