---
title: "Submit a standardized mdhub questionnaire (PHQ-9, GAD-7, MADRS) by raw scores"
method: POST
path: "/questionnaires/submit-mdhub"
tags: ["Questionnaires"]
---

# Submit a standardized mdhub questionnaire (PHQ-9, GAD-7, MADRS) by raw scores

`POST /questionnaires/submit-mdhub`

Submits a standardized questionnaire identified by `mdhubType`
using only an array of integer scores. The server fetches the
authoritative questionnaire schema from mdhub by `mdhubType`
and maps each entry in `responses` to the appropriate response
label (Likert scale items for PHQ-9 and GAD-7, option indexes
for MADRS).

**Lengths and ranges:**
- `mdhub-phq-9`: 9 integers, each `0..3`
- `mdhub-gad-7`: 7 integers, each `0..3`
- `mdhub-madrs`: 10 integers, each `0..6`

Validation runs against the actual questionnaire stored in
mdhub, so wrong array length or out-of-range entries return a
`400` with detailed `issues[]`.

Once stored, an AI summary and a numeric score are generated
automatically.

## Request body

- SubmitMdhubQuestionnaireRequest
  - `patientId` string, required — ID of the patient (as returned by the create patient endpoint).
  - `mdhubType` 'mdhub-phq-9' | 'mdhub-gad-7' | 'mdhub-madrs', required — Identifier of the mdhub-managed standardized questionnaire. The server resolves this to the corresponding questionnaire schema and uses it to map each entry in `responses` to the proper response label.
  - `responses` integer[], required — Raw integer scores in question order. - **PHQ-9 / GAD-7**: each entry is a 0–3 score on the 4-point frequency scale ("Not at all", "Several days", "More than half the days", "Nearly every day"). Length must be 9 (PHQ-9) or 7 (GAD-7). - **MADRS**: each entry is a 0–6 score against the item's options. Length must be 10.

## Response `201`

Questionnaire submitted successfully

- SubmitQuestionnaireResponse
  - `patientQuestionnaireId` string, required — ID of the stored patient-questionnaire on the mdhub side.

## Other responses

- `400` — Validation failed (e.g. wrong array length, out-of-range score)
- `401` — Unauthorized - Invalid or missing API key
- `403` — Patient does not belong to this clinic
- `404` — Patient or mdhub questionnaire not found
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.dev/mdhub/apis/mdhub-api.md) · [All operations](https://skmtc.dev/mdhub/apis/mdhub-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mdhub/mdhub-api/revisions/ee7fca23d80b/schema)