# 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](../../../access-control/identity-management/application-client-management.md) — 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:**

{% tabs %}
{% tab title="Request" %}
```http
GET /cds-services
Accept: application/json
```
{% endtab %}

{% tab title="Response" %}
```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"
    }
  ]
}
```
{% endtab %}
{% endtabs %}

| 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](https://cds-hooks.hl7.org/hooks/STU1/order-sign.html).

**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:**

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

{% tabs %}
{% tab title="Request" %}
```http
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"
    }
  }
}
```
{% endtab %}

{% tab title="Response" %}
```json
{
  "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"
            }
          ]
        }
      ]
    }
  ]
}
```
{% endtab %}
{% endtabs %}

### 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](https://cds-hooks.hl7.org/hooks/STU1/order-select.html).

**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:**

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

{% tabs %}
{% tab title="Request" %}
```http
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"
    }
  }
}
```
{% endtab %}

{% tab title="Response" %}
```json
{
  "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"
        }
      }
    }
  ]
}
```
{% endtab %}
{% endtabs %}

### 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](https://cds-hooks.hl7.org/hooks/order-dispatch/).

**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:**

{% 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 %}

### 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](https://cds-hooks.hl7.org/hooks/appointment-book/).

**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:**

{% 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/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"
        }
      ]
    }
  }
}
```
{% endtab %}

{% tab title="Response" %}
```json
{
  "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"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}
```
{% endtab %}
{% endtabs %}