> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.emtelligent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emtelligent.com/_mcp/server.

# Asking questions

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

```json
{
  "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`** `string` — default: 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`** `string` — required

The question, up to 1,000 characters.

---

**`type`** `string` — default: text

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

---

**`options`** `string[]`

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

---

**`multiple`** `boolean` — default: false

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

---

## Answer types

| `type`    | `answer` is                                                                                   |
| --------- | --------------------------------------------------------------------------------------------- |
| `text`    | A short answer in the document's own terms, qualifiers and units included ("Less than 10 mL") |
| `number`  | A number, in the document's units. The evidence quote shows the unit                          |
| `boolean` | `true` or `false`                                                                             |
| `date`    | `YYYY-MM-DD` when the document gives a full date, otherwise the date as written               |
| `choice`  | Exactly 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**.

```json
{
  "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"
}
```

| `status`           | Meaning                                                                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `answered`         | `answer` holds the value, with `confidence` and `evidence`                                                                                                                       |
| `not_found`        | The document does not answer the question. `answer` is `null` (`[]` for a `multiple` question), with no `confidence` or `evidence`                                               |
| `unmatched_option` | The 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.