---
description: order-dispatch CDS Hook — fires when an order is dispatched to a specific performer
---

# 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](https://cds-hooks.hl7.org/hooks/order-dispatch/). Implemented by Payerbox for [CRD](../../prior-auth/crd.md) per [Da Vinci CRD STU 2.0.1](https://hl7.org/fhir/us/davinci-crd/STU2.0.1/).

## Endpoint

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

## Auth

SMART Backend Services. See [Authentication](../authentication.md).

## 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

{% hint style="info" %}
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.
{% endhint %}

{% tabs %}
{% tab title="Request" %}

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

{% endtab %}

{% tab title="Response" %}

```json
{
  "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" }
              }
            }
          ]
        }
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}