Skip to main content

Physician Answers

When the physician answers, the decision gains a physician block: one selected answer per question, each with a physician-reported confidence, plus optional comments.

The physician block

GET /api/v1/decisions/{id} (answered)
{
  "id": "dec_7Hq2…",
  "object": "decision",
  "status": "answered",
  "escalated_at": "2026-11-03T15:01:10Z",
  "due_at": "2026-11-04T15:01:10Z",
  "disclaimer": "This answer is provided for informational and educational purposes only, based on the material you submit. It is not medical advice, does not create a physician-patient relationship, and you remain responsible for any decision made using it.",
  "…": "…",
  "physician": {
    "expert": {
      "id": "exp_example",
      "name": "Example Reviewer, MD",
      "specialties": [
        "internal_medicine"
      ]
    },
    "answers": [
      {
        "type": "predicate",
        "name": "unsupported_claim",
        "value": true,
        "confidence": 0.9,
        "comment": "Not documented means unknown, not \"no known allergies.\""
      },
      {
        "type": "choice",
        "name": "error_category",
        "choice": "unsupported_certainty",
        "confidence": 0.9,
        "comment": "Missing documentation became a confirmed negative."
      },
      {
        "type": "score",
        "name": "error_severity",
        "level": 2,
        "label": "Material",
        "confidence": 0.8,
        "comment": "A false \"no allergies\" can lead to a harmful prescription."
      }
    ],
    "answered_at": "2026-11-04T09:12:00Z"
  }
}
FieldDescription
expertWho answered: id, name, specialties. This is attribution for this answer.
answersExactly one answer per question, in question order, with matching name and type.
answered_atWhen the answer was submitted.

Like every decision object, the answered decision carries a top-level disclaimer string: the answer is provided for informational and educational purposes only, based on the material you submit. It is not medical advice, creates no physician–patient relationship, and you remain responsible for decisions made with it. Keep it attached to the answer wherever you store, display or forward it.

Answer fields

Question typeSelected answerAlso
predicatevalue: true or falseconfidence, comment
choicechoice: one of your supplied values, with its original type (string or boolean)confidence, comment
scorelevel: 0-based index, and label: that level's labelconfidence, comment

There is no physician refusal or "insufficient information" answer type. A physician who is uncertain still selects their best judgment within your schema, rates it with low confidence, and can explain why in a comment. A completed review with low-confidence answers is a completed review and is charged at the quoted price.

Physician-reported confidence

Each answer carries a required confidence between 0.0 and 1.0 in steps of 0.1. The physician picks an integer rating from 0 ("no confidence") to 10 ("complete confidence") and the API returns the rating divided by 10. There is no default; the physician must choose. 0.0 is a real rating and is always serialized.

  • It is confidence in the selected answer. For a predicate, {"value": false, "confidence": 0.9} means the physician is quite confident the answer is false. It is not the probability that the predicate is true.
  • It is self-reported, not calibrated. It is one physician's judgment of their own certainty, and may be biased. It is not equivalent to an AI probability or AI confidence, even though both use a 0–1 range.
  • It is a fixed scale. Only the eleven values 0.0, 0.1, … 1.0 occur. AI values are never rounded to this scale.

Comments

  • Each answer may include a comment of up to 280 characters explaining that answer. Commentary is per question; there is no separate overall rationale.
  • With include_commentary: true, the physician must write a nonblank comment on every answer. Otherwise comments are optional, and comment is omitted when the physician didn't write one. Commentary is included in the review price.
  • Lengths are counted in Unicode code points, including spaces and punctuation. An emoji or accented letter counts as one; in JavaScript use [...text].length, not text.length.
  • This is a short structured decision, not a written report. Longer narrative reports are not offered.

Mapping AI answers to physician answers

Both ai.answers and physician.answers are ordered arrays with one entry per question and matching name. Their fields mean different things:

Question typeAI answerPhysician answerHow to compare
predicateprobability that the answer is truevalue (true/false) + confidence in that valueCompare the AI's implied answer (probability ≥ 0.5) with value. Don't compare probability to confidence directly: a false at 0.9 is a strong "no".
choicechoice, confidence, probabilities[]choice + confidenceCompare choice values (same type). The AI's probability for the physician's choice is in probabilities[].
scorescore, confidence, probabilities[] by level indexlevel + label + confidenceCompare level with the AI's most probable level (probabilities[].value), not with a rounded score.
refusalThe AI declinedThe physician still answers with the question's typeNo AI answer to compare.
Not interchangeable. A shared 0–1 range makes it easy to put AI and physician numbers side by side, but they measure different things. If you use agreement between them (for example to decide when to escalate), validate that rule on your own data.