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). It occurs after orders have been signed and allows CDS services to provide coverage and prior authorization guidance based on the selected performer.

Defined by the CDS Hooks order-dispatch specification. Implemented by Payerbox for CRD per Da Vinci CRD STU 2.0.1.

Endpoint

POST <base>/cds-services/order-dispatch-crd

Auth

SMART Backend Services. See Authentication.

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" }
              }
            }
          ]
        }
      ]
    }
  ]
}