Question sets
The intakes Cuvo publishes for each treatment, how an agent asks one, and how a case is checked against it before it is filed.
A question set is an intake Cuvo's clinical team publishes for a treatment: the questions a clinician needs answered before deciding a case, in the order to ask them, with the conditions under which each one is asked. You can file a case with answers of your own, but a case that names a set is checked against it before anything is written, so an intake that would come back with a question is refused while the patient is still there to answer.
Both reads need catalog:read and work in both modes. A test key reads the sandbox's copy of the
live sets: the same questions, the same ids, with medication ids from the sandbox formulary.
Fetching one
GET /v1/question_sets lists every published set at its latest version: id, title, version,
published_at, and medication_ids, the GET /v1/medications rows it is the intake for (empty
when the formulary carries none of them). It pages like every other list. category is the
treatment category the set is the intake for, or null; a case naming the set is checked against
the patient's state under it (Cases), for the medications in medication_ids only
and only where the clinic's catalog does not already categorise them.
GET /v1/question_sets/{id} returns the same with questions. Pass ?version= to read an earlier
version; an unknown set or a version that was never published answers 404 not_found. Versions
count from 1 and never change once published, so you can pin the version you built against and
upgrade when you choose. Every published version stays acceptable on a case, not only the latest.
The questions
Each question carries:
id, the answer'sidon the case, andquestion, the text to show or say to the patient.input:single_choice,multi_choice,textornumber; andtype, the answer'stypeon the case (choice,stringornumber).required. A required question must be answered whenever it is asked.options, each anidand alabel, on a choice question.none_option, on a multi-select, the option that cannot be combined with another.ask_when, when the question is conditional: ask it only when the answer to the questionidnames is one ofany_of. Whentrigger_is_multiis true that question is a multi-select, and any one of its picks being inany_ofis enough. A question with noask_whenis always asked.send_as, on the height and weight question, which has notypeof its own: it is answered as the two numeric answers listed,weight_poundsandheight_inches(feet times 12, plus inches).critical_options, when the set marks any of a question's options as needing a clinician's attention. See below.
An optional key is absent rather than null when it does not apply.
Asking it
Walk the questions in order and ask each one whose ask_when holds against what the patient has
already answered; skip the rest, and send nothing for a skipped question. Then answer each:
| Input | answer |
|---|---|
single_choice | The chosen option's label, verbatim. |
multi_choice | The chosen labels joined with "; ", or the none_option alone. |
text | The patient's words. |
number | A number. |
| Height and weight | Two answers, weight_pounds and height_inches, each a number. |
Send the answer's type from the question, and its question text as the patient saw it.
Filing the case
Name the set and the version you asked on POST /v1/cases:
{
"patient": "pat_…",
"requested_medications": [ … ],
"answers": [
{ "id": "weight_pounds", "question": "Weight in pounds", "answer": 212, "type": "number" }
],
"consent_ids": ["cons_…", "cons_…"],
"question_set": { "id": "semaglutide-glp-1-weight-loss", "version": 1 }
}
The answers are checked before the case is written. A set or version that is not published is
refused with an issue on question_set. Otherwise every failing answer is its own issue on
400 invalid_request: answers.<i>.answer for an answer that is not one of the options, not a
number, or combines the none_option with another pick, and answers for a required question that
was asked and not answered. Answers whose ids the set does not name are yours and pass untouched.
The case returns question_set as you sent it; a case that names no set carries null and is filed
exactly as before.
Critical options
A pick in critical_options never refuses a case. It files like any other answer, and the
clinician reviewing the case must acknowledge each one before deciding it. In test mode the answers
are checked the same way, and the simulated clinician decides on the
test controls as usual.