---
title: "Create a patientFormPdfFilledDocument"
method: POST
path: "/patientFormPdfFilledDocuments"
tags: ["patientFormPdfFilledDocuments"]
---

# Create a patientFormPdfFilledDocument

`POST /patientFormPdfFilledDocuments`

## Request

- Base URL: `https://api.lumahealth.io/api/v2`
- URL: `https://api.lumahealth.io/api/v2/patientFormPdfFilledDocuments`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/lumahealth/apis/rest-service/docs/patientFormPdfFilledDocuments/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- PatientFormPdfFilledDocumentRequestCreate
  - `patientFormPdfTemplate` string, required: ID of the PatientFormPdfTemplate this is a filled instance of
  - `values` object[], required: values submitted for each field in the source PatientFormPdfTemplate
    - `fieldId` string, required: index (as a string) into the source PatientFormPdfTemplate's fields array identifying which field this value was submitted for
    - `value` string, required: value submitted for this field. Checkbox fields submit the string 'true'/'false'

## Response `201`

Successful creation

- PatientFormPdfFilledDocumentResponse: One instance of a patient filling out a PatientFormPdfTemplate, producing a completed PDF - the DocuSign/DocuSeal "envelope" analog to PatientFormPdfTemplate's "template". The filled PDF itself is produced client-side and uploaded like any other file upload; this record stores the reference to that output file plus the submitted values.
  - `_id` string: Luma's internal ID of an object.
  - `user` string: The ID of the root account user.
  - `deleted` 0 | 1: Flag for logical deletion where 1 means deleted.
  - `createdBy` string: The ID of the user who created this object.
  - `updatedBy` string: The ID of the user who updated this object.
  - `createdAt` string, date-time: The date/time when this object was created.
  - `updatedAt` string, date-time: The date/time when this object was updated.
  - `patientFormPdfTemplate` string: ID of the PatientFormPdfTemplate this is a filled instance of
  - `fieldsSnapshot` object[]: snapshot of the source PatientFormPdfTemplate's fields at fill-time, so later edits to the live template never retroactively affect an already-filled document
    - `page` integer, required: 0-indexed page number within the source PDF this field is placed on
    - `type` 'text' | 'paragraph-text' | 'signature' | 'checkbox' | 'date' | 'number' | 'initials', required: type of the pdf form template field
    - `x` number, required: fraction (0-1) of the page width, measured from the left edge
    - `y` number, required: fraction (0-1) of the page height, measured from the top edge
    - `width` number, required: fraction (0-1) of the page width
    - `height` number, required: fraction (0-1) of the page height
    - `mappingField` string: when set, this field auto-fills from the matching PatientFormMappingFields concept instead of being filled in manually
    - `label` string: custom field label, used for manual fill when mappingField is not set
    - `placeholderText` string: patient-facing guidance text shown inside the field, distinct from the internal label
    - `required` boolean: whether the patient must fill this field in before submitting
    - `readOnly` boolean: whether this field is rendered read-only (auto-filled/informational, not editable by the patient) at fill-time
    - `defaultValue` string: default value pre-filled for this field, regardless of type
    - `minLength` integer: minimum number of characters accepted. Only meaningful for the text field types (text, paragraph-text)
    - `maxLength` integer: maximum number of characters accepted. Only meaningful for the text field types (text, paragraph-text)
    - `minValue` number: minimum numeric value accepted. Only meaningful when type is number
    - `maxValue` number: maximum numeric value accepted. Only meaningful when type is number
    - `dateRange` 'any' | 'future' | 'past': restricts which dates are accepted. Only meaningful when type is date
  - `values` object[]: values submitted for each field in fieldsSnapshot
    - `fieldId` string, required: index (as a string) into this document's fieldsSnapshot array identifying which field this value was submitted for
    - `value` string, required: value submitted for this field. Checkbox fields submit the string 'true'/'false'
  - `renderedFileUpload` string: ID of the generated, filled PDF produced client-side and uploaded via the existing FileUpload flow

## Other responses

- `401`: Not authenticated
- `403`: Access token does not have the required scope

## Changes

- **2026-10-17** `f19aeba84a26`: 2 warning, 4 info
  - added the new `initials` enum value to the `fieldsSnapshot/items/type` response property for the response status `201`
  - added the new `paragraph-text` enum value to the `fieldsSnapshot/items/type` response property for the response status `201`
  - added the optional property `fieldsSnapshot/items/maxValue` to the response with the `201` status
  - added the optional property `fieldsSnapshot/items/minValue` to the response with the `201` status
  - …2 more
- **2026-08-23** `d3c75c2a2f1d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lumahealth/apis/rest-service/changes/patientFormPdfFilledDocuments/post.md)

---

[API](https://skmtc.dev/lumahealth/apis/rest-service.md) - [All operations](https://skmtc.dev/lumahealth/apis/rest-service/llms.txt) - [OpenAPI document](https://skmtc.dev/lumahealth/apis/rest-service/revisions/f19aeba84a26?raw)