---
description: order-sign CDS Hook — fires when a clinician is about to sign one or more orders
---

# order-sign

The `order-sign` hook fires when a clinician is ready to sign one or more orders for a patient (medications, procedures, labs, and others). It is among the last workflow events before an order is promoted out of a `draft` status. The context contains all order details (dose, quantity, route, etc.), although the orders are still in draft.

Defined by the [CDS Hooks order-sign specification](https://cds-hooks.hl7.org/hooks/STU1/order-sign.html). 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-sign-crd
```

## Auth

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

## 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 below 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 %}