---
title: "Submit a filled custom questionnaire for a patient"
method: POST
path: "/questionnaires/submit"
tags: ["Questionnaires"]
---

# Submit a filled custom questionnaire for a patient

`POST /questionnaires/submit`

Creates a submitted patient-questionnaire for an existing
patient. The patient must belong to the clinic that owns the
API key.

Use this endpoint for **custom questionnaires** you define
yourself (intake forms, post-visit follow-ups, screeners,
etc.). For mdhub-managed standardized questionnaires
(PHQ-9, GAD-7, MADRS) use `/questionnaires/submit-mdhub`
instead — it only needs raw integer scores and handles
response-label mapping for you.

Each schema item is validated against its `type`. Supported
types: `input_title`, `input_free_text`, `input_number`,
`input_single`, `input_multiple`, `input_list`,
`input_likert`, `dropdown_single`, `dropdown_multiple`.
`id` and `order` on each schema item are always assigned by
the server (`id` via UUID, `order` via array position
starting at 1) — any values sent by the client are ignored.
`description` defaults to `""` and `required` defaults to
`false` when omitted.

Once stored, an AI summary is generated automatically.

## Request body

- SubmitQuestionnaireRequest
  - `patientId` string, required — ID of the patient (as returned by the create patient endpoint).
  - `questionnaire` SubmitQuestionnaireData, required — Filled custom-questionnaire payload accepted by `/questionnaires/submit`. Same shape as `QuestionnaireData`, but each schema item only requires `title` and `type` — `id`, `order`, `description`, and `required` are auto-filled by the server when omitted.
    - `title` string, required — Questionnaire title.
    - `description` string — Questionnaire description, optional.
    - `type` 'questionnaire_intake' | 'questionnaire_follow_up' | 'questionnaire_screening' | 'questionnaire_intake_agent' — Questionnaire kind, optional. Defaults to `questionnaire_follow_up`.
    - `questionnaireId` string — External questionnaire identifier, optional.
    - `schema` SubmitQuestionnaireSchemaItem[], required — Ordered questionnaire inputs, including section title items and filled responses.
      - `title` string, required
      - `description` string
      - `type` 'input_free_text' | 'input_single' | 'input_multiple' | 'input_list' | 'input_title' | 'input_number' | 'input_likert' | 'dropdown_single' | 'dropdown_multiple', required
      - `required` boolean
      - `options` string[] — Available options for single, multiple, and dropdown inputs.
      - `requireComment` string[] — Option values that should collect a follow-up comment.
      - `comment` string — Optional comment captured for the selected response.
      - `columns` string[] — Column names for list/table inputs.
      - `prefix` string — Unit or prefix for number inputs.
      - `questions` string[] — Question labels for likert inputs.
      - `scale` QuestionnaireLikertScale — Likert scale metadata. Some imported questionnaires may send null instead.
        - `label` string
        - `value` string
        - `items` string[]
      - `response` union — Filled response value. String for free text, single, dropdown-single, and number inputs; array of strings for multiple and dropdown-multiple; array of list column objects for list inputs; array of question/ response objects for likert inputs. Title inputs typically omit response.
        - string
        - string[]
        - QuestionnaireListResponseColumn[]
          - `col` string — Preferred column key.
          - `column` string — Legacy/alternate column key used by some questionnaire creation flows.
          - `responses` string[], required
        - QuestionnaireLikertResponse[]
          - `question` string, required
          - `response` string, required

## Response `201`

Questionnaire submitted successfully

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

## Other responses

- `400` — Validation failed
- `401` — Unauthorized - Invalid or missing API key
- `403` — Patient does not belong to this clinic
- `404` — Patient 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)