Forms - Perform

The forms module stores a studio’s form templates (FormTemplate), sends them to trainees as assignments (FormAssignment) and keeps the submitted answers (FormResponse). Source: backend/apps/core-api/src/modules/forms. Two routers are covered here:

Router	Mount	Middleware
`formsRouter` (`forms.routes.ts`)	`/v1/web/forms`	`serviceAuth`, `webUserContext(ctx.prisma)`, `webLimiter`
`defaultFormsRouter` (`default-forms.routes.ts`)	`/v1/admin/default-forms`	`serviceAuth` only

A third router in the same file, traineeFormsRouter at /v1/trainee/forms, serves the trainee app and is documented on its own page. Related pages: Forms AI creates draft templates from a link, files or pasted text. Form signing is the public lane for PDF_SIGNATURE forms. Update forms is the scheduler that sends recurring check-in forms and form reminders.

Auth and guards

Every /v1/web/forms request passes HMAC service auth from @perform/security, then middleware/web-context.ts:

x-studio-id and x-user-id are required. Without them the request fails with UNAUTHORIZED (401, missing web user context).
x-user-role is parsed into OWNER, HEAD_COACH, SUB_COACH or TRAINEE. Any other value, or no header, becomes SUB_COACH.
The studio is resolved from x-studio-id (Studio.externalOrgId) and created if it does not exist. An OWNER gets a HEAD_COACH row in Coach on first contact.
The result is req.auth with studioId, userId and role.

The forms router adds no requireRole and does not use middleware/coach-access.ts. Any caller that passes the web lane can call every endpoint below, and all data is scoped by req.auth.studioId only. A coach whose permissions restrict them to assigned trainees is not narrowed here. /v1/admin/default-forms has service auth only. There is no webUserContext, no req.auth and no role guard inside default-forms.routes.ts. Any service holding a valid service secret can manage the global default templates.

Shared concepts

Form types and status

Field	Values	Notes
`type`	`INTAKE`, `CHECK_IN`, `ONE_TIME`, `PDF_SIGNATURE`	`PDF_SIGNATURE` is a document the trainee signs through a public link, never in the app
`status`	`DRAFT`, `PUBLISHED`, `ARCHIVED`	New templates default to `DRAFT`
`cadence`	`WEEKLY`, `BIWEEKLY`, `MONTHLY`	Stored only on `CHECK_IN` templates
assignment `status`	`PENDING`, `COMPLETED`, `CANCELLED`	Cancelling from this API deletes the row, see below

Form schema

schema is accepted as a free JSON object and always passed through normalizeFormSchema (form-schema.ts) before it is stored, so what you read back is FormSchemaV2:

type FormSchemaV2 = {
  schemaVersion: 2;
  fields: FormField[];
  settings: {
    submitLabel?: string;
    successMessage?: string;
    displayName?: string;
    rtl: boolean;
    pages: { id: string; title?: string; ctaLabel?: string; condition?: FormCondition }[];
    thankYou?: { richText: RichSpan[] };
    document?: { url: string; pageCount: number; pages: { width: number; height: number }[]; fileName?: string; sizeBytes?: number };
  };
};

Field types (FORM_FIELD_TYPES): text, number, phone, israeli_id, age, height, weight, body_measurement, goal, email, gender, date, birth_date, dropdown, checkbox_confirmation, rating, range, image_upload, video_upload, food_preferences, read_more, coach_message, text_block, media_block, signature. read_more, coach_message, text_block and media_block are display only (DISPLAY_ONLY_TYPES) and are not counted in fieldCount. settings.displayName is the name the trainee sees. When it is absent the trainee sees the template name.

Template response shape

Every template endpoint returns the FormTemplate row plus two computed fields from enrichTemplate:

fieldCount: number of fields that are not display only.
responseCount: number of FormResponse rows for the template.

{
  "id": "cmf1x2abc0001xyz",
  "studioId": "cmf0studio0001",
  "type": "CHECK_IN",
  "cadence": "WEEKLY",
  "sendWeekday": 0,
  "sendDayOfMonth": null,
  "name": "Weekly check-in",
  "description": null,
  "schema": {
    "schemaVersion": 2,
    "fields": [
      { "id": "f_a1b2c3d4", "type": "weight", "key": "weight", "label": "Weight (kg)", "required": true, "order": 0, "page": 0, "saveToClient": true }
    ],
    "settings": { "rtl": true, "pages": [{ "id": "p1" }] }
  },
  "logic": null,
  "version": 2,
  "status": "PUBLISHED",
  "active": true,
  "createdAt": "2026-09-30T08:12:44.000Z",
  "updatedAt": "2026-10-01T10:02:11.000Z",
  "fieldCount": 1,
  "responseCount": 14
}

Errors common to all endpoints

Code	Status	When
`UNAUTHORIZED`	401	No `req.auth.studioId` (or `userId` on assign)
`VALIDATION`	422	A Zod schema rejected the query, params or body. `details` lists `path` and `message` per issue
`RATE_LIMITED`	429	The web lane limiter

Templates

`GET /v1/web/forms/templates`

Lists the studio’s templates, newest first (createdAt descending). Auth: web lane, any role.

string

One of INTAKE, CHECK_IN, ONE_TIME, PDF_SIGNATURE.

string

One of DRAFT, PUBLISHED, ARCHIVED.

boolean

Filters on FormTemplate.active. Parsed with z.coerce.boolean(), so any non-empty string, including false, is read as true. Omit the parameter to get both.

string

Case-insensitive contains match on name.

number

default:"1"

Positive integer.

number

default:"20"

Positive integer, maximum 500.

Response: data holds items (templates in the shape above), total, page and pageSize.

{
  "ok": true,
  "data": {
    "items": [
      { "id": "cmf1x2abc0001xyz", "type": "INTAKE", "name": "Onboarding", "status": "PUBLISHED", "active": true, "version": 1, "fieldCount": 12, "responseCount": 3 }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "requestId": "req_01"
}

Errors: VALIDATION.

`POST /v1/web/forms/templates`

Creates a template. Responds with 201. Auth: web lane, any role.

string

required

INTAKE, CHECK_IN, ONE_TIME or PDF_SIGNATURE.

string

required

At least 1 character.

object

required

The form schema. Normalized to FormSchemaV2 before saving.

string

Optional description.

string | null

WEEKLY, BIWEEKLY or MONTHLY. Only kept for CHECK_IN, where it defaults to WEEKLY. Stored as null for every other type.

number | null

Integer 0 to 6. Only kept for CHECK_IN.

number | null

Integer 1 to 31. Only kept for CHECK_IN.

object

Free JSON stored on FormTemplate.logic. Forms AI writes logic.aiImport here and the AutoFit import reads logic.autofitImport.

string

default:"DRAFT"

DRAFT, PUBLISHED or ARCHIVED.

boolean

default:"true"

Inactive templates cannot be assigned.

For PDF_SIGNATURE, when the schema has settings.document, the router’s documentCheck (form-sign/source-document.ts) verifies the uploaded PDF before the row is written. See the document errors below. Response: the created template with fieldCount and responseCount (0). Errors:

Code	Status	`details.reason`	When
`VALIDATION`	422		Body failed the Zod schema
`BAD_REQUEST`	400	`DOCUMENT_NOT_OURS`	`settings.document.url` is not an object under this studio’s `forms/<studioId>/` storage prefix
`BAD_REQUEST`	400	`DOCUMENT_TOO_LARGE`	The PDF is larger than 15 MB
`BAD_REQUEST`	400	`DOCUMENT_UNREADABLE`	The object could not be read, is not a readable PDF, or a rehearsal signing of it failed
`BAD_REQUEST`	400	`DOCUMENT_NOT_PDF`	The object does not start with the `%PDF` magic bytes
`BAD_REQUEST`	400	`DOCUMENT_ENCRYPTED`	The PDF is password protected
`BAD_REQUEST`	400	`DOCUMENT_PAGE_COUNT_MISMATCH`	The real page count differs from `settings.document.pageCount`
`BAD_REQUEST`	400	`DOCUMENT_TOO_COMPLEX`	Parsing the PDF hit the worker’s time or memory limits

`GET /v1/web/forms/templates/:id`

Returns one template of the caller’s studio. Auth: web lane, any role.

string

required

FormTemplate.id.

Response: the template with fieldCount and responseCount. Errors: NOT_FOUND (404, form template not found) when the id does not exist in this studio.

`PATCH /v1/web/forms/templates/:id`

Updates a template. Only the fields you send change. Auth: web lane, any role.

string

required

FormTemplate.id.

string

At least 1 character.

string

INTAKE, CHECK_IN, ONE_TIME or PDF_SIGNATURE. See the type change rules below.

string | null

WEEKLY, BIWEEKLY, MONTHLY or null.

number | null

Integer 0 to 6.

number | null

Integer 1 to 31.

string | null

Send null to clear it.

object

Replaces the schema after normalization.

object

Replaces logic.

string

DRAFT, PUBLISHED or ARCHIVED.

boolean

Turns the template on or off for sending.

Service rules (updateTemplate in forms.service.ts):

A PDF_SIGNATURE template cannot change type, and no other template can become PDF_SIGNATURE.
A template cannot become ONE_TIME while any Product or Client still references it through onboardingFormId or updateFormId.
Schedule fields are only written when the resulting type is CHECK_IN. Switching a template to CHECK_IN without a cadence sets WEEKLY. Switching away from CHECK_IN clears cadence, sendWeekday and sendDayOfMonth.
Every request that sends status: "PUBLISHED" increments version by 1, including when the template is already published. New assignments record the version at send time in FormAssignment.formVersion.
For PDF_SIGNATURE, a new schema triggers the document check only when settings.document.url or pageCount changed.

Response: the updated template. Errors:

Code	Status	When
`NOT_FOUND`	404	Template not in this studio
`BAD_REQUEST`	400	`a document to sign cannot change type, and no form can become one`
`BAD_REQUEST`	400	`a linked onboarding or check-in form cannot become one-time`
`BAD_REQUEST`	400	Any document check reason listed under create
`VALIDATION`	422	Body failed the Zod schema

`GET /v1/web/forms/templates/:id/document`

Streams the source PDF of a PDF_SIGNATURE template so the builder can render it with pdf.js. The handler is coachDocumentHandler in form-sign/form-sign.routes.ts. Auth: web lane, any role.

string

required

FormTemplate.id.

Response: the raw PDF bytes, not the JSON envelope. Headers: Content-Type: application/pdf, Cache-Control: private, no-store, X-Robots-Tag: noindex. Errors:

Code	Status	When
`UNAUTHORIZED`	401	No studio on the request
`NOT_FOUND`	404	Template not in this studio, not a `PDF_SIGNATURE` form, no document, a document URL outside this studio’s `forms/<studioId>/` prefix, or bytes that are not a PDF (`this form has no document`)
`BAD_REQUEST`	400	`DOCUMENT_TOO_LARGE`, the stored object is over 15 MB

`DELETE /v1/web/forms/templates/:id`

Deletes a template. Responds with 204 and no body. Auth: web lane, any role.

string

required

FormTemplate.id.

The Prisma relations on FormAssignment and FormResponse use onDelete: Cascade, so deleting a template also deletes its assignments and responses. Errors: NOT_FOUND (404) when the template is not in this studio.

`POST /v1/web/forms/templates/:id/duplicate`

Copies a template. Responds with 201. Auth: web lane, any role.

string

required

The template to copy.

The copy keeps type, cadence, sendWeekday, sendDayOfMonth, description and the normalized schema. It is created with active: false, status: "DRAFT" and version: 1. The name is the original name followed by the Hebrew suffix (עותק). logic is copied without the autofitImport key (copiedLogic), so the AutoFit import cannot attach answers to the copy. Response: the new template with fieldCount and responseCount (0). Errors: NOT_FOUND (404).

Assignments

`POST /v1/web/forms/templates/:id/assign`

Sends a form to one trainee by creating a FormAssignment. Responds with 201. Auth: web lane, any role. req.auth.userId is stored as assignedById.

string

required

FormTemplate.id.

string

required

The trainee. Must belong to the caller’s studio.

date

Coerced with z.coerce.date(). A future value hides the form from the trainee until that moment.

string

Trimmed, maximum 500 characters. Stored on the assignment and returned to the trainee app.

object

PDF_SIGNATURE only. A map of coach field key to string value. Ignored for every other type.

What assignForm does, in order:

Check the template

The template must exist in the studio and have active: true. An inactive template fails with details.reason: "FORM_INACTIVE".

Prepare a document to sign

For PDF_SIGNATURE the template must be PUBLISHED, have settings.document, and have at least one field the trainee fills. fieldValues is validated by validateFieldValues in signing.ts: only keys of fields with filledBy: "coach" are allowed, values are trimmed, blank values are dropped, each value is at most 500 characters, and every required coach field must have a value.

Create the assignment

formVersion is the template’s current version. For PDF_SIGNATURE the row also gets a signToken (16 random bytes, base64url), the validated coach values as prefill and the schema as signSchema. The link signs that frozen schema even if the coach edits the template later. notifiedAt is stamped at creation for PDF_SIGNATURE, so no push pass ever announces it.

Record activity

A ClientActivity row is written with type: "FORM", action: "ASSIGNED", actorType: "TRAINER", entityType: "FORM", entityId set to the template id and entityName to the template name.

Notify the trainee

For non PDF forms that are visible now (no future dueAt, and Client.planFrozenOn is null), the service claims the assignment by setting notifiedAt, then sends a FORM_SENT trainee push through createTraineeNotifier with vars.form set to the trainee-facing form name and data holding assignmentId and formId. If the studio has not disabled the notification and nobody was reached, muted or skipped, the claim is released so the hourly pending-form notifier can retry.

Raise FORM_SENT

When the form is sent now (always true for PDF_SIGNATURE), formSentHook runs raiseFormSent (tasks/form-sent.ts). It starts the studio’s FORM_SENT automation flows, or falls back to creating FORM_SENT tasks in InboxItem when no flow handles the event. Errors from the hook are swallowed. See Task automations and Tasks.

A form with a future dueAt or a frozen plan gets no push and no FORM_SENT event at this point. The hourly scheduler described in Update forms picks it up when it becomes visible. This endpoint does not deliver a signing link to the trainee. It returns signingUrl and the caller decides how to send it. Response: the assignment through presentAssignment. signToken, prefill and signSchema are never returned. signingUrl is <APP_WEB_URL>/sign/<token> for PDF_SIGNATURE and null otherwise. When APP_WEB_URL is not set the base falls back to https://app.byperform.co.il.

{
  "ok": true,
  "data": {
    "id": "cmf2assign0001",
    "studioId": "cmf0studio0001",
    "formTemplateId": "cmf1x2abc0001xyz",
    "clientId": "cmf0client0009",
    "formVersion": 2,
    "status": "PENDING",
    "assignedById": "user_8f2k",
    "prompt": "Please fill this before Sunday",
    "dueAt": null,
    "notifiedAt": "2026-10-07T09:15:02.000Z",
    "completedAt": null,
    "createdAt": "2026-10-07T09:15:02.000Z",
    "updatedAt": "2026-10-07T09:15:02.000Z",
    "signingUrl": null
  },
  "requestId": "req_02"
}

Errors:

Code	Status	`details.reason`	When
`NOT_FOUND`	404		Template not in this studio (`form template not found`) or client not in this studio (`client not found`)
`BAD_REQUEST`	400	`FORM_INACTIVE`	Template has `active: false`
`BAD_REQUEST`	400	`FORM_NOT_PUBLISHED`	`PDF_SIGNATURE` template is not `PUBLISHED`
`BAD_REQUEST`	400	`FORM_NO_DOCUMENT`	`PDF_SIGNATURE` template has no PDF
`BAD_REQUEST`	400	`FORM_NO_TRAINEE_FIELDS`	`PDF_SIGNATURE` template has no field for the trainee
`BAD_REQUEST`	400	`UNKNOWN_FIELD_KEY`	A `fieldValues` key is not a coach field. `details` also carries `key` and `validKeys`
`BAD_REQUEST`	400	`INVALID_FIELD_VALUE`	A value is not a string, number or boolean
`BAD_REQUEST`	400	`FIELD_VALUE_TOO_LONG`	A value is longer than 500 characters
`BAD_REQUEST`	400	`MISSING_FIELD_VALUE`	A required coach field has no value. `details.keys` lists them
`VALIDATION`	422		Body failed the Zod schema

`GET /v1/web/forms/assignments`

Lists the studio’s assignments, newest first. Auth: web lane, any role.

string

Only assignments of this trainee.

string

PENDING, COMPLETED or CANCELLED.

number

default:"1"

Positive integer.

number

default:"20"

Positive integer, maximum 500.

Response: items, total, page, pageSize. Each item is a presented assignment (no signToken, prefill or signSchema, with signingUrl) and includes the full formTemplate row.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cmf2assign0002",
        "formTemplateId": "cmf1pdf0001",
        "clientId": "cmf0client0009",
        "formVersion": 1,
        "status": "PENDING",
        "dueAt": null,
        "completedAt": null,
        "createdAt": "2026-10-07T09:20:00.000Z",
        "formTemplate": { "id": "cmf1pdf0001", "name": "Health declaration", "type": "PDF_SIGNATURE", "status": "PUBLISHED", "active": true },
        "signingUrl": "https://app.byperform.co.il/sign/SIGN_TOKEN"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "requestId": "req_03"
}

Errors: VALIDATION.

`DELETE /v1/web/forms/assignments/:id`

Cancels a pending assignment. The row is deleted with deleteMany filtered on studioId and status: "PENDING". It is not moved to CANCELLED. Auth: web lane, any role.

string

required

FormAssignment.id.

For a PDF_SIGNATURE assignment this also removes the signToken, so the public signing link answers 404 from then on. Response:

{ "ok": true, "data": { "canceled": true }, "requestId": "req_04" }

Errors: NOT_FOUND (404, assignment not found or already handled) when no pending assignment with that id exists in the studio.

Responses

`GET /v1/web/forms/responses`

Lists submitted responses for the studio’s templates, newest first. Auth: web lane, any role.

string

Only responses to this template.

string

Only responses from this trainee.

number

default:"1"

Positive integer.

number

default:"20"

Positive integer, maximum 500.

Response: items, total, page, pageSize. Items are raw FormResponse rows with no relations included.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cmf3resp0001",
        "formTemplateId": "cmf1x2abc0001xyz",
        "assignmentId": "cmf2assign0001",
        "clientId": "cmf0client0009",
        "formVersion": 2,
        "answers": { "weight": 78.4 },
        "schemaSnapshot": { "schemaVersion": 2, "fields": [], "settings": { "rtl": true, "pages": [{ "id": "p1" }] } },
        "handledNote": null,
        "handledById": null,
        "handledByName": null,
        "handledAt": null,
        "documentUrl": null,
        "signingAudit": null,
        "submittedAt": "2026-10-07T11:02:40.000Z",
        "createdAt": "2026-10-07T11:02:40.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "requestId": "req_05"
}

Errors: VALIDATION.

`GET /v1/web/forms/responses/:id`

Returns one response with its template and trainee. Auth: web lane, any role.

string

required

FormResponse.id.

Response: the FormResponse row plus:

formTemplate: id, name, type, schema.
client: id, name, avatarUrl.
aiSummary: an array of bullet strings when a summary is already cached on one of the tasks this submission raised, otherwise null. This endpoint never calls the model.

{
  "ok": true,
  "data": {
    "id": "cmf3resp0001",
    "formTemplateId": "cmf1x2abc0001xyz",
    "assignmentId": "cmf2assign0001",
    "clientId": "cmf0client0009",
    "formVersion": 2,
    "answers": { "weight": 78.4 },
    "documentUrl": null,
    "signingAudit": null,
    "submittedAt": "2026-10-07T11:02:40.000Z",
    "createdAt": "2026-10-07T11:02:40.000Z",
    "formTemplate": { "id": "cmf1x2abc0001xyz", "name": "Weekly check-in", "type": "CHECK_IN", "schema": { "schemaVersion": 2, "fields": [], "settings": { "rtl": true, "pages": [{ "id": "p1" }] } } },
    "client": { "id": "cmf0client0009", "name": "Dana Levi", "avatarUrl": null },
    "aiSummary": ["Weight is down 0.6 kg since last week", "Reports low energy on training days"]
  },
  "requestId": "req_06"
}

Errors: NOT_FOUND (404, form response not found).

`GET /v1/web/forms/responses/:id/summary`

Returns the AI summary of one submission, generating it on first request. Auth: web lane, any role.

string

required

FormResponse.id.

How getResponseSummary works:

It loads up to 10 tasks (SUMMARY_TASK_LIMIT) from InboxItem that belong to the submission. summaryTaskWhere in summary-cache.ts matches tasks of type FORM_RESPONSE, FORM_FILLED, FORM_FILLED_OVERDUE, FORM_RATING_BELOW, FORM_SENT or FORM_FEEDBACK_SENT whose refId, metadata.responseId or metadata.formResponseId is the response id, or whose metadata.assignmentId is the response’s assignment.
If any of those tasks has metadata.aiSummary, that cached value is returned.
A PDF_SIGNATURE response is never summarized and returns null.
Otherwise createFormSummarizer (ai/form-summarizer.ts, configured from OPENAI_API_KEY and OPENAI_FORM_SUMMARY_MODEL) summarizes the answers paired with schemaSnapshot (or the template schema when there is no snapshot).
The bullets are written as a JSON string to metadata.aiSummary on every matched task. Write failures are ignored.

When the submission raised no task there is nowhere to cache the result, so each call asks the model again. Response:

{
  "ok": true,
  "data": { "summary": ["Weight is down 0.6 kg since last week", "Reports low energy on training days"] },
  "requestId": "req_07"
}

summary is null for a signed document or when the summarizer returns nothing. Errors: NOT_FOUND (404, form response not found).

`GET /v1/web/forms/responses/:id/document`

Streams the signed PDF of a PDF_SIGNATURE response. The handler is coachSignedDocumentHandler in form-sign/form-sign.routes.ts. Auth: web lane, any role.

string

required

FormResponse.id.

The stored documentUrl must resolve to forms/<studioId>/signed/<24 hex chars>.pdf in the media bucket. The object is read up to 30 MB and must start with the %PDF magic bytes. Response: the raw PDF bytes with Content-Type: application/pdf, Cache-Control: private, no-store and X-Robots-Tag: noindex. Errors:

Code	Status	When
`UNAUTHORIZED`	401	No studio on the request
`NOT_FOUND`	404	Response not in this studio, no `documentUrl`, a URL that is not this studio’s signed copy, or an object that is too large or not a PDF (`this response has no signed document`)

What a submission triggers

Submissions enter through the trainee app router or the public signing lane, not through the endpoints on this page. Both end in the same formSubmittedHandler (forms.wiring.ts), which is why a coach sees the same downstream effects for either path:

dispatchFormFilled queues the studio’s FORM_FILLED webhooks on the hook delivery queue. It runs first and is not awaited. See Automation hooks.
startFormFilledFlowRuns starts FORM_FILLED automation flows. When no flow handles the event, createFormFilledTask creates the legacy task instead.
startFormRatingBelowFlowRuns starts rating-below flows. When none handles the event, createFormRatingBelowTask creates the legacy task.

Before those hooks, an app submission also:

marks the assignment COMPLETED and stores schemaSnapshot on the response,
calls the subscription starter with INTAKE_FORM for INTAKE forms,
copies answers from fields flagged saveToClient onto the trainee: email, phone (through normalizePhone), israeliId, age, heightCm, birthDate, weightKg and goal on Client, a WeightEntry per weight answer, a ClientPhoto per image upload (with the field’s config.pose), and body circumferences merged into DailyMetric.measurements for the trainee’s local day. This step is best effort and never fails the submission.

Admin default form templates

DefaultFormTemplate rows are global, not per studio. The schema allows INTAKE, CHECK_IN and ONE_TIME only. All five routes are defined inline in default-forms.routes.ts with a small Prisma service, and they return raw rows with no computed fields.

{
  "id": "cmf9default0001",
  "key": "custom_1759830000000_k3x9ab",
  "type": "INTAKE",
  "name": "Standard onboarding",
  "description": "Default intake questions",
  "schema": { "schemaVersion": 2, "fields": [], "settings": { "rtl": true, "pages": [{ "id": "p1" }] } },
  "active": true,
  "order": 0,
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z"
}

`GET /v1/admin/default-forms/templates`

Lists every default template ordered by order ascending, then createdAt ascending. No pagination and no filters. Auth: service auth only. Response: data is an array of DefaultFormTemplate rows. Errors: none thrown by the service.

`POST /v1/admin/default-forms/templates`

Creates a default template. Responds with 201. Auth: service auth only.

string

required

INTAKE, CHECK_IN or ONE_TIME.

string

required

At least 1 character.

object

required

Normalized with normalizeFormSchema before saving.

string

Optional description.

boolean

default:"true"

Whether the template is offered.

number

default:"0"

Integer sort position, coerced from a string if needed.

The unique key is generated server side as custom_<timestamp>_<random>. Response: the created row. Errors: VALIDATION (422).

`GET /v1/admin/default-forms/templates/:id`

Returns one default template. Auth: service auth only.

string

required

DefaultFormTemplate.id.

Response: the row. Errors: NOT_FOUND (404, default form template not found).

`PATCH /v1/admin/default-forms/templates/:id`

Updates a default template. Only the fields you send change. key cannot be changed. Auth: service auth only.

string

required

DefaultFormTemplate.id.

string

INTAKE, CHECK_IN or ONE_TIME.

string

At least 1 character.

string | null

Send null to clear it.

object

Normalized before saving.

boolean

Whether the template is offered.

number

Integer sort position.

Response: the updated row. Errors: NOT_FOUND (404), VALIDATION (422).

`DELETE /v1/admin/default-forms/templates/:id`

Deletes a default template. Responds with 204 and no body. Auth: service auth only.

string

required

DefaultFormTemplate.id.

Errors: NOT_FOUND (404).

​Auth and guards

​Shared concepts

​Form types and status

​Form schema

​Template response shape

​Errors common to all endpoints

​Templates

​GET /v1/web/forms/templates

​POST /v1/web/forms/templates

​GET /v1/web/forms/templates/:id

​PATCH /v1/web/forms/templates/:id

​GET /v1/web/forms/templates/:id/document

​DELETE /v1/web/forms/templates/:id

​POST /v1/web/forms/templates/:id/duplicate

​Assignments

​POST /v1/web/forms/templates/:id/assign

​GET /v1/web/forms/assignments

​DELETE /v1/web/forms/assignments/:id

​Responses

​GET /v1/web/forms/responses

​GET /v1/web/forms/responses/:id

​GET /v1/web/forms/responses/:id/summary

​GET /v1/web/forms/responses/:id/document

​What a submission triggers

​Admin default form templates

​GET /v1/admin/default-forms/templates

​POST /v1/admin/default-forms/templates

​GET /v1/admin/default-forms/templates/:id

​PATCH /v1/admin/default-forms/templates/:id

​DELETE /v1/admin/default-forms/templates/:id

Auth and guards

Shared concepts

Form types and status

Form schema

Template response shape

Errors common to all endpoints

Templates

`GET /v1/web/forms/templates`

`POST /v1/web/forms/templates`

`GET /v1/web/forms/templates/:id`

`PATCH /v1/web/forms/templates/:id`

`GET /v1/web/forms/templates/:id/document`

`DELETE /v1/web/forms/templates/:id`

`POST /v1/web/forms/templates/:id/duplicate`

Assignments

`POST /v1/web/forms/templates/:id/assign`

`GET /v1/web/forms/assignments`

`DELETE /v1/web/forms/assignments/:id`

Responses

`GET /v1/web/forms/responses`

`GET /v1/web/forms/responses/:id`

`GET /v1/web/forms/responses/:id/summary`

`GET /v1/web/forms/responses/:id/document`

What a submission triggers

Admin default form templates

`GET /v1/admin/default-forms/templates`

`POST /v1/admin/default-forms/templates`

`GET /v1/admin/default-forms/templates/:id`

`PATCH /v1/admin/default-forms/templates/:id`

`DELETE /v1/admin/default-forms/templates/:id`