Forms API
Multi-page form builder with public submissions, conditional logic, and analytics.
Forms API
ProBeya includes a built-in multi-page form builder for data collection, surveys, and intake workflows. Forms support conditional logic, public submission URLs, auto-ticket creation, and submission analytics. The forms system is currently tRPC-only (no REST endpoints), accessible from the ProBeya web client and through direct tRPC calls.
Architecture
Forms follow a hierarchical structure:
Form
|-- FormPage (ordered by sortOrder)
| |-- FormField (ordered by sortOrder)
|-- FormSubmission
|-- FormSubmissionValue (one per field)
Each form belongs to an organization and optionally links to a board for auto-creating items from submissions.
Procedures
forms.create
Create a new form definition. Automatically creates the first page (“Page 1”).
Type: Mutation Auth: Authenticated user with org context
Input:
| Name | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Form display title |
slug | string | Yes | URL-safe slug (unique within org) |
description | string | No | Form description shown to respondents |
boardId | string | No | Link to a board for item auto-creation |
forms.update
Update form settings, status, metadata, or linked board.
Type: Mutation Auth: Authenticated user with org context
Input:
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Form ID |
title | string | No | New title |
slug | string | No | New slug (uniqueness checked) |
description | string | No | New description |
boardId | string | No | New linked board ID |
status | string | No | draft, published, closed |
settings | object | No | Form settings (see below) |
forms.delete
Delete a form and all its pages, fields, and submissions (cascade).
Type: Mutation Auth: Authenticated user with org context
forms.getById
Get a form with all pages, fields, and creator info.
Type: Query Auth: Authenticated user with org context
forms.list
List forms with filtering and pagination.
Type: Query Auth: Authenticated user with org context
Input:
| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter by form status |
boardId | string | No | Filter by linked board |
sortBy | string | No | createdAt, updatedAt, title (default: createdAt) |
sortOrder | string | No | asc or desc (default: desc) |
page | number | No | Page number (default: 1) |
limit | number | No | Results per page (default: 25, max: 100) |
forms.publish
Publish a draft form, making it live and accepting submissions. Validates that the form has at least one field.
Type: Mutation
Auth: Authenticated user with org context
Precondition: Form status must be draft or closed
forms.close
Close a published form, stopping new submissions.
Type: Mutation
Auth: Authenticated user with org context
Precondition: Form status must be published
forms.submit (Public)
Submit a form response. This is a public endpoint — no authentication required. The organization is resolved from the organizationSlug parameter.
Type: Mutation Auth: Public (no authentication required)
Input:
| Name | Type | Required | Description |
|---|---|---|---|
organizationSlug | string | Yes | Organization slug (from subdomain) |
formSlug | string | Yes | Form URL slug |
values | array | Yes | Array of { fieldId, value } objects |
respondentEmail | string | No | Respondent email |
respondentName | string | No | Respondent name |
isComplete | boolean | No | Whether submission is final (validates required fields) |
Response:
{
"submissionId": "clx9fs001",
"message": "Thank you for your submission!",
"redirectUrl": "https://acme.com/thank-you"
}
forms.getSubmissions
List submissions for a form with pagination.
Type: Query Auth: Authenticated user with org context
forms.getAnalytics
Get form analytics including submission counts by status, completion rate, and daily submission trends (last 30 days).
Type: Query Auth: Authenticated user with org context
Response shape:
{
"totalSubmissions": 156,
"completeCount": 142,
"partialCount": 14,
"completionRate": 91.0,
"recentDaily": [
{ "day": "2026-03-29", "count": 8 },
{ "day": "2026-03-30", "count": 12 }
]
}
Page and Field Management
| Procedure | Description |
|---|---|
forms.upsertPage | Create or update a form page |
forms.deletePage | Remove a page from a form |
forms.upsertField | Create or update a field on a page |
forms.deleteField | Remove a field from a page |
forms.getPublicForm | Get form structure for public rendering (no auth) |
Form Settings
The settings JSONB field supports:
| Key | Type | Description |
|---|---|---|
maxSubmissions | number | Maximum allowed submissions |
closedMessage | string | Message when max reached |
confirmationMessage | string | Thank you message after submit |
redirectUrl | string | URL to redirect after submit |
createTicketOnSubmit | boolean | Auto-create a support ticket |
Field Types
Supported form field types: text, textarea, number, email, phone, url, date, datetime, select, multiselect, checkbox, radio, rating, file, signature, section_header.
Was this page helpful?