Skip to navigation
Guides

Asking questions

Plain-language questions in, typed answers out

A questions job answers up to 100 questions about one clinical document. You do not need a FHIR Questionnaire: ask in plain language, and say what type of answer you want.

Submitting

{
  "type": "questions",
  "document": { "text": "… clinical document text …" },
  "questions": [
    "What is the primary diagnosis?",
    { "id": "a1c", "text": "What was the most recent HbA1c?", "type": "number" },
    { "id": "cancer", "text": "Does this patient have cancer?", "type": "boolean" },
    { "id": "side", "text": "Which side was biopsied?", "type": "choice",
      "options": ["Left", "Right", "Not stated"] },
    { "id": "meds", "text": "List all current medications.", "multiple": true }
  ]
}

Each question is a string, or an object:

id
stringDefaults to q1, q2, … by position

1 to 64 characters from A-Z a-z 0-9 _ . -, unique within the job. Echoed back on the answer, so you can match answers to questions.

text
stringRequired

The question, up to 1,000 characters.

type
stringDefaults to text

text, number, boolean, date or choice. See below.

options
string[]

Required for choice: the allowed answers. Distinct, at most 200.

multiple
booleanDefaults to false

The question can have several answers, for example “List all current medications”.

Answer types

typeanswer is
textA short answer in the document’s own terms, qualifiers and units included (“Less than 10 mL”)
numberA number, in the document’s units. The evidence quote shows the unit
booleantrue or false
dateYYYY-MM-DD when the document gives a full date, otherwise the date as written
choiceExactly one of your options; not_found when what the document says is not among them

The result

Answers come back in the order you asked them.

{
  "id": "job_8f2c1d0e9b7a6c5d4e3f2a1b",
  "type": "questions",
  "answers": [
    { "id": "q1", "question": "What is the primary diagnosis?", "type": "text",
      "status": "answered", "answer": "Nodular basal cell carcinoma", "confidence": 0.97,
      "evidence": { "quote": "NODULAR BASAL CELL CARCINOMA",
                    "spans": [ { "start": 812, "end": 840 } ] } },
    { "id": "a1c", "question": "What was the most recent HbA1c?", "type": "number",
      "status": "not_found", "answer": null },
    { "id": "meds", "question": "List all current medications.", "type": "text",
      "status": "answered",
      "answer": [
        { "answer": "metformin 500 mg twice daily", "confidence": 0.95,
          "evidence": { "quote": "Metformin 500 mg BID", "spans": [ { "start": 1203, "end": 1223 } ] } },
        { "answer": "lisinopril 10 mg daily", "confidence": 0.94,
          "evidence": { "quote": "lisinopril 10 mg daily", "spans": [ { "start": 1225, "end": 1247 } ] } }
      ] }
  ],
  "stats": { "answerable": 5, "answered": 4, "answer_values": 5,
             "unmatched_option": 0, "suppressed": 0, "evidence_located": 5 },
  "pipeline_version": "2026.10.12-1"
}
statusMeaning
answeredanswer holds the value, with confidence and evidence
not_foundThe document does not answer the question. answer is null ([] for a multiple question), with no confidence or evidence
unmatched_optionThe answer matched none of your options. answer holds what it gave, for review; do not store it as one of your values. Rare, because answers are constrained to your options

For a multiple question, answer is a list of {answer, confidence, evidence} objects, one per value.

Writing questions that answer well

  • Be specific. “What was the most recent HbA1c?” answers better than “HbA1c?”. “Anatomic site of the excision” answers better than “Site?”.
  • Ask one thing per question. Split “What are the tumour size and grade?” into two questions.
  • Use choice when you need a controlled value. The answer is then always one of your options, which is easier to store and compare than free text.
  • Use boolean for yes/no. Negation in the document (“no evidence of malignancy”) is taken into account.