CDQ API

For engineers at client health systems who send patient data to CDQ.

Overview

CDQ checks patient event data against approved care pathways. For each patient and pathway it reports which steps were done on time, done late, done too early, or missed, and which are not due yet.

You send:

• patients, each with a list of dated events (diagnoses, labs, visits, procedures, medications and so on),
• optional patient context (age or date of birth, sex, plan type, problem list, social needs flags),
• optional prior pathway assignments.

You get back:

• one status row per patient, pathway and step (step_statuses),
• one row per deviation: a missed, late or premature step (deviations),
• the patients and pathways that were not evaluated, with the reason (patients_skipped),
• recommendations, when any apply (recommendations).

CDQ does not store the patient data you send. Only counts (patients submitted and evaluated per pathway) are kept, for billing.

Two ways to send data

Both run the same evaluation on the same data. Pick the one that fits where you are.

The two are designed to be interchangeable:

• The upload's JSON template (download it from the Analysis page, cdq_events_template.json) is an API request body. The same file can be uploaded, or sent to the API once you fill in client_id and pathway_ids. Uploads ignore client_id, pathway_ids and as_of_date in the file.
• Each CSV column maps to one API field. See Upload ↔ API field mapping.

A common path is to start with uploads, then move the same extract into a pipeline that calls the API.

Authentication

Every /cdq/* endpoint needs one of these headers:

If both are sent, X-API-Key is used.

• Getting a key. A user with the client admin role creates keys in the web app on the API keys page. The key is shown once; copy it then. Keys can be revoked on the same page, and a revoked key fails at once.
• Client scoping. Every request names a client_id (a UUID). It must be the client the key or token belongs to; any other value returns 403. Your client ID is shown on the API keys page in the web app.
• HTTPS only. Plain HTTP requests are refused with 403.
• Roles. client_api (API keys) and client_admin can evaluate and read pathways. demo_viewer accounts can evaluate demo data but cannot change anything.

There are no request-rate limits. Repeated failed sign-ins are logged and alerted on.

Evaluate a batch

POST /cdq/analysis/evaluate-batch
Content-Type: application/json
X-API-Key: <your key>

The request body may be up to 25 MB by default. Split larger extracts into several requests that share one submission_id (see below).

Request

This is the upload template with client_id and pathway_ids filled in:

{
  "client_id": "3f2c9a1e-5b7d-4c8e-9a10-2b3c4d5e6f70",
  "pathway_ids": [
    "8a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e"
  ],
  "as_of_date": null,
  "patients": [
    {
      "patient_id": "P001",
      "patient_context": {"date_of_birth": "1967-04-12", "patient_sex": "F", "plan_type": "commercial",
                          "active_diagnoses": ["E11.9", "73211009"]},
      "prior_assignments": [{"pathway_name": "Chronic Diabetes Management", "assignment_status": "active",
                             "assigned_since": "2025-09-02"}],
      "events": [
        {"event_id": "e1", "event_type": "diagnosis", "event_date": "2025-09-02", "event_code": "E11.9", "event_code_system": "ICD-10"},
        {"event_id": "e2", "event_type": "lab", "event_date": "2025-09-20", "event_code": "4548-4", "event_code_system": "LOINC", "result_value": "8.1",
         "communication_date": "2025-09-24"}
      ]
    },
    {
      "patient_id": "P002",
      "patient_context": {"date_of_birth": "1958-02-20", "patient_sex": "M", "plan_type": "medicare"},
      "events": [
        {"event_id": "e3", "event_type": "procedure", "event_date": "2025-10-03", "event_code": "27447",
         "event_code_system": "CPT", "scheduled_date": "2025-11-14"}
      ]
    }
  ]
}

With curl:

curl -sS https://<your CDQ host>/cdq/analysis/evaluate-batch \
  -H "X-API-Key: $CDQ_API_KEY" \
  -H "Content-Type: application/json" \
  --data @batch.json

Fields

Top level

patients[]

patients[].events[]

patients[].patient_context (all keys optional)

Wrong types return 422 naming the key, for example patient_context.patient_age must be an integer.

patients[].prior_assignments[] (all keys optional)

Response

200 OK with a JSON object. Abridged example for the request above:

{
  "total_patients": 2,
  "total_pathways": 2,
  "as_of_date": "2025-10-03",
  "submission_id": "6d1f0b8e-2a4c-4e9b-9b7a-1c2d3e4f5a6b",
  "possible_deviations_count": 0,
  "deviations": [
    {
      "patient_id": "P001",
      "pathway_id": "8a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "pathway_name": "Chronic Diabetes Management",
      "step_name": "Diabetic eye exam",
      "deviation_type": "missing_step",
      "severity": "moderate",
      "expected_date": "2025-10-02",
      "actual_date": null,
      "days_variance": null,
      "confirmed": true,
      "missing_fields": null,
      "evaluation_source": "assigned",
      "visit_group": "ambulatory_visit"
    }
  ],
  "step_statuses": [
    {
      "patient_id": "P001",
      "pathway_id": "8a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "pathway_name": "Chronic Diabetes Management",
      "step_id": "c0ffee00-0000-4000-8000-000000000001",
      "step_name": "HbA1c test",
      "step_order": 1,
      "status": "COMPLETE",
      "actual_date": "2025-09-20",
      "expected_by_date": "2025-12-01",
      "window_open_date": "2025-09-02",
      "days_variance": -72,
      "evaluation_source": "assigned",
      "trigger_type": "icd10",
      "trigger_code": "E11",
      "trigger_date": "2025-09-02"
    },
    {
      "patient_id": "P002",
      "pathway_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "pathway_name": "Total Knee Replacement",
      "step_id": "c0ffee00-0000-4000-8000-000000000002",
      "step_name": "Pre-operative assessment",
      "step_order": 1,
      "status": "DUE",
      "actual_date": null,
      "expected_by_date": "2025-11-07",
      "window_open_date": "2025-10-15",
      "days_variance": null,
      "evaluation_source": "recommended",
      "trigger_type": "procedure_scheduled",
      "trigger_code": "27447",
      "trigger_date": "2025-11-14"
    }
  ],
  "patients_skipped": [
    {
      "patient_id": "P001",
      "pathway_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "pathway_name": "Total Knee Replacement",
      "reason": "pathway not in patient prior assignments"
    }
  ]
}

Pathway names, step names, codes and dates above are illustrative. The real ones come from your approved pathways.

Top level

deviations[]

step_statuses[]

patients_skipped[].reason values:

recommendations[]

Submissions and billing

• One billable run is one pathway evaluated in one submission.
• Send the same submission_id on every request that belongs together, for example a large extract split into parts, or a retry. Repeating a pathway within a submission does not add a run.
• A submission stays open for 24 hours after its first use. After that, a request with that submission_id returns 422; start a new one.
• enrollment_preview requests are not billed and are not given a submission.

Upload ↔ API field mapping

The upload reads one row per event. Patient-level columns can repeat on every row of a patient, or appear on any one of them: the first non-blank value wins. Column names are matched without regard to case, and spaces, dots and dashes count as underscores (Event Date matches event_date). When several aliases are present, the first alias in the list wins.

SDOH flag values: both treat 1, true, TRUE, yes and YES as set (the API also takes JSON true and 1).

Upload only

API only

Dates. The API takes YYYY-MM-DD only. Uploads also take YYYY/MM/DD, MM/DD/YYYY and M/D/YYYY (month first; day-first dates like 15/03/2026 are not read). Upload rows with a date CDQ can't read are left out and counted on the job page.

Missing values. In uploads, empty cells and NA, N/A and null count as missing. In the API, leave the key out or send null.

JSON uploads. Besides the API body shape, a JSON upload can be an array of flat event rows using the column names above, or a {"patients": [...]}, {"events": [...]}, {"data": [...]}, {"records": [...]} or {"rows": [...]} wrapper around one.

Event types and codes

A step is met by the first event, on or after the step's window opens, whose event_type is one the step accepts and whose event_code is one of the step's codes. A step with no codes can't be met by any event (CANNOT_CHECK).

Event types used to qualify patients for pathways (enrollment):

Event types and codes are read in any case, with spaces trimmed, by both the upload and the API.

Codes by kind of event

Medications. Medication steps and criteria name drug classes (for example statins or SGLT2 inhibitors). Send the medication as an RxNorm code: an ingredient, clinical drug, branded drug or pack RXCUI all work. NDC codes are also accepted, current or discontinued: 11 digits, or hyphenated 4-4-2, 5-3-2 or 5-4-1. CDQ maps them to RxNorm. event_code_system is optional for medications (RxNorm or NDC); CDQ recognises the code either way.

How results are worked out

Evaluation date. Results are as of one date. Steps due after it are DUE, not missed. If you don't set as_of_date, CDQ uses the latest event dated on or before today in the request (bookings and future-dated events left out); a set date can't be after today. This judges an older extract as of when it was pulled, not as of now. The upload form's evaluation date works the same way.

When the clock starts. Each pathway has a trigger. For each patient, the clock starts at:

1. the prior assignment's assigned_since, if you sent one for this pathway, else
2. the qualifying event, for pathways that start at an event (a discharge, a booked procedure), else
3. the first event that matches the trigger (for example the first diabetes diagnosis), else
4. for pathways based on age or plan alone, the patient's latest visit for the first step within its repeat interval (a year by default), or the evaluation date if there is none.

Each step then has a window counted in days from that start, or from the previous step.

Scheduled procedures. For a procedure that is booked but not yet done, send the event with scheduled_date set to the booked date (event_date is when it was booked). CDQ treats it as a booking on the booked date. A procedure pathway then starts at the booked date, so pre-operative steps fall due before it. A booking never counts as the procedure itself being done. A procedure already done is sent as a normal procedure event without scheduled_date, and the pathway starts at its date.

Results and referrals. Some steps check that a result was given to the patient (for example "Results Communication" after a mammogram) or that a referral was made (for example a community resource referral after a positive social-needs screen). Put the date on the row of the result or screen: communication_date for when the result was given, referral_date for when the referral was made. CDQ adds a communication or referral event with that row's code on that date, and it meets the step that follows the result or screen. You can also send such events directly, as rows with event_type communication or referral and the code of the result or screen. A visit with the step's own codes (an office visit to discuss results) also counts. Results are due within 7 days of the result for screening pathways.

Vaccines. Immunization steps accept a vaccine given at a visit (the CPT vaccine code or the Medicare administration code, as a procedure, encounter or immunization event) or as a prescription. CVX codes count only when event_code_system is CVX, since CVX and RxNorm share small numbers.

Transitions of care. Discharge pathways (for example heart failure or pneumonia follow-up) start at the discharge. Send the discharge as an event (event_type discharge, or an encounter with encounter_type discharge), plus the principal diagnosis as a diagnosis event during the stay. A patient admitted in the last 30 days with a qualifying diagnosis but no discharge yet is not evaluated (nothing is due until discharge). Instead the response carries a pending_discharge recommendation with the admission date, so the patient isn't missed.

Recommendations. Some pathways have rules that suggest a next action from a result or a delay, for example considering another pathway. These come back in recommendations. They are suggestions only: they never count as deviations and never change step statuses.

Early and late. An event before the step's window opens is a premature_step (counted as done, but flagged). For windows that open before the trigger, such as pre-operative steps, only events up to 60 days before the window count as premature; older ones are treated as unrelated history. An event after the due date is a late_step. No event by the due date is a missing_step.

Optional steps (for example "if abnormal" follow-ups) are shown in step_statuses but never reported as deviations.

Errors

Errors return JSON {"detail": "<message>"}.

Every response carries an X-Request-Id header. Quote it when you contact Preact about a request.

An error evaluating one patient on one pathway does not fail the request: that pair appears in patients_skipped with reason evaluation error (see server logs).

Other endpoints

Pathways by plan. Every client runs its own approved pathways. Library pathways depend on the plan: Per Pathway Run, Explorer and a free trial run the whole library; HEDIS runs the pathways that report HEDIS measures; Custom Pathways runs up to 10 library pathways the client chooses; HEDIS + Custom runs both. Choose them on the Billing page or with the selection endpoints below. You can read the steps and references of every pathway you can run. Building your own pathways (creating or editing them) comes with Custom Pathways, HEDIS + Custom and Explorer once paid; during a free trial or on Per Pathway Run those requests get 403, and pathways you built before keep running.

All /cdq/* endpoints use the same authentication. Pass your own client_id.

Code systems and licences

CDQ uses ICD-10-CM, SNOMED CT, LOINC, CPT/HCPCS and RxNorm codes in its pathways and accepts them in your data.

This material contains content from LOINC® (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license. LOINC® is a registered United States trademark of Regenstrief Institute, Inc.

CPT® is a registered trademark of the American Medical Association, and CPT codes are used under licence.

Medications can be sent as RxNorm codes, or as NDC codes, which CDQ maps to RxNorm. Drug classes are built from RxNorm. This product uses publicly available data courtesy of the U.S. National Library of Medicine (NLM), National Institutes of Health, Department of Health and Human Services; NLM is not responsible for the product and does not endorse or recommend this or any other product.