Skip to content

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's id on the case, and question, the text to show or say to the patient.
  • input: single_choice, multi_choice, text or number; and type, the answer's type on the case (choice, string or number).
  • required. A required question must be answered whenever it is asked.
  • options, each an id and a label, 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 question id names is one of any_of. When trigger_is_multi is true that question is a multi-select, and any one of its picks being in any_of is enough. A question with no ask_when is always asked.
  • send_as, on the height and weight question, which has no type of its own: it is answered as the two numeric answers listed, weight_pounds and height_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:

Inputanswer
single_choiceThe chosen option's label, verbatim.
multi_choiceThe chosen labels joined with "; ", or the none_option alone.
textThe patient's words.
numberA number.
Height and weightTwo 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.