Skip to main content
The CDS Hooks simulator stands in for the EHR side of the CDS Hooks specification. It lets you register a CDS service, invoke hooks with a simulated clinical context (patient-view, order-select, medication-prescribe, etc.), and record user feedback on the cards that come back. Use it to benchmark agents that either consume CDS cards surfaced in a provider workflow or produce cards as a CDS service reacting to EHR activity.

​
How your agent connects

The CDS sandbox exposes a CDS Hooks-style surface on the direct-service path. Register CDS services via discovery, invoke hooks, and submit feedback; all traffic is recorded as interaction evidence and correlates with the sandbox’s FHIR resources.
CDS Hooks endpoints are not currently mounted on the run-scoped /v1/benchmark-runs/{id}/cds/* surface. During a benchmark run, resolve the CDS sandbox from the sandboxes list on the run response and call the direct /sandboxes/{id}/cds/* endpoints with an organization API key.

​
Endpoints

MethodEndpointDescription
POST/sandboxes/{sandbox_id}/cds/servicesRegister CDS services by pointing to a discovery URL
GET/sandboxes/{sandbox_id}/cds/servicesList CDS services currently registered with the sandbox
POST/sandboxes/{sandbox_id}/cds/hooks/{hook}Fire a hook (e.g. patient-view, order-select) with a simulated context; returns the cards produced
POST/sandboxes/{sandbox_id}/cds/feedbackRecord user feedback on a CDS card (accepted, overridden, ignored)
See Register CDS service, List CDS services, Invoke CDS hook, and Submit CDS feedback.

​
Driving the rollout

Register CDS services by pointing at a discovery URL (CDS Hooks publishes a /cds-services endpoint per vendor): 
curl -X POST "https://api.verial.ai/sandboxes/$CDS_SANDBOX_ID/cds/services" \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discovery_url": "https://cds.example.com/cds-services"
  }'
Fire a hook (body fields are flat, snake_case): 
curl -X POST "https://api.verial.ai/sandboxes/$CDS_SANDBOX_ID/cds/hooks/patient-view" \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "patient-123",
    "user_id": "Practitioner/rivera",
    "encounter_id": "encounter-456"
  }'
Record feedback on a card the agent decided to act on: 
curl -X POST "https://api.verial.ai/sandboxes/$CDS_SANDBOX_ID/cds/feedback" \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "drug-interaction-check",
    "card_uuid": "card_01H...",
    "outcome": "accepted",
    "accepted_suggestions": ["suggestion-1"]
  }'

​
Configuration

At create time you configure the hooks the sandbox will advertise and, optionally, canned cards the sandbox will return when a hook is invoked. 
curl -X POST https://api.verial.ai/simulators \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CdsHooks",
    "name": "EHR CDS Surface",
    "config": {
      "hooks": ["patient-view", "order-select", "medication-prescribe"]
    }
  }'

​
Verification

There is no dedicated CDS Hooks check type in the current criterion catalog. CDS evidence is scored in two ways:
  • Interaction evidence. Every service registration, hook invocation, and feedback submission is logged as an interaction. The request context, returned cards, and feedback outcomes are attached to criterion-run evidence.
  • Cross-simulator criteria. When a CDS card leads to a change in FHIR (for example the agent accepts a create-medication suggestion), use fhir-resource-state on the resulting resource to score the outcome. When it leads to a portal action, use portal-state-match.

​
Next Steps

FHIR

CDS context objects reference FHIR resources; pair this simulator with a FHIR simulator.

CDS API reference

Direct-access CDS Hooks endpoints for authoring.

Criteria

The assertions the verification engine currently supports.

Simulators overview

Lifecycle, provisioning, and configuration patterns.