User Forms
Documentation for User Forms
Base path: /api/v1/user-forms
User forms are human-in-the-loop approval/review forms generated by workflow steps that require human review before proceeding. When a workflow step is configured as a human input step, it pauses execution and creates a form for review.
Endpoints Overview
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/v1/user-forms | JWT | List forms for the authenticated user |
| GET | /api/v1/user-forms/:formId | None | Get form HTML content |
| POST | /api/v1/user-forms/:activityRunId/:status | None | Submit a form approval/rejection |
GET /api/v1/user-forms
Lists all user forms for workflows owned by the authenticated user.
Authentication
Requires JWT (authMiddleware + activeOrgPreferenceMiddleware).
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number (min: 1) |
limit | number | 20 | Items per page (min: 1, max: 100) |
search | string | – | Search by workflow name (case-insensitive) |
sortBy | string | "createdAt" | Sort field: createdAt, updatedAt, workflowName, status |
sortOrder | string | "desc" | Sort direction: asc, desc |
status | string | – | Filter by status: pending, approved, rejected |
Response 200 OK
Form object fields:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Form ID |
workflowId | string (UUID) | Associated workflow ID |
workflowName | string | Workflow name |
workflowDescription | string | null | Workflow description |
workflowRunId | string (UUID) | The workflow run that created this form |
activityRunId | string (UUID) | The activity (step) run that paused for this form |
workflowStepName | string | Name of the step requiring approval |
workflowStepDescription | string | null | Step description |
status | "pending" | "approved" | "rejected" | Review status |
reviewedBy | string | null | User ID of reviewer (if reviewed) |
reviewedAt | string (ISO 8601) | null | When the form was reviewed |
createdAt | string (ISO 8601) | When the form was created |
updatedAt | string (ISO 8601) | Last update time |
GET /api/v1/user-forms/:formId
Returns the HTML content of a user form. This endpoint is public (no authentication required) — forms are accessed via a link sent to the reviewer.
Authentication
None required (publicly accessible via a unique form ID).
Path Parameters
| Parameter | Type | Description |
|---|---|---|
formId | string (UUID) | Form ID |
Response 200 OK
| Field | Type | Description |
|---|---|---|
html | string | The form's HTML definition, ready to be rendered in a browser |
Usage Pattern
Forms are typically rendered in an iframe or opened in a new browser tab. The HTML includes a form that submits to the approve/reject endpoint.
POST /api/v1/user-forms/:activityRunId/:status
Submits a form approval or rejection. This resumes the paused workflow with the form data. This endpoint is public — it is submitted by the reviewer clicking approve/reject in the form.
Authentication
None required (the form link serves as authorization).
Path Parameters
| Parameter | Type | Description |
|---|---|---|
activityRunId | string (UUID) | Activity run ID associated with the form |
status | "approve" | "reject" | The approval decision |
Request Body (multipart/form-data)
Any form field values filled in by the reviewer. File fields are automatically uploaded to object storage, and a presigned URL replaces the file in the submitted data.
Response
Returns an HTML page confirming submission:
- If successful: success page with "Form Submitted Successfully"
- If already submitted: info page with "Form Already Submitted"
The HTTP status is 200 OK in both cases (the response is HTML, suitable for browser navigation).
Errors
| Status | Reason |
|---|---|
404 Not Found | Activity run or workflow run not found |
500 Internal Server Error | Workflow has no Temporal workflow association |
Workflow Integration Notes
User forms appear during workflow execution when:
- A workflow step has
is_human_input_step: truein its definition - The executor pauses the Temporal workflow and creates a form record
- The form link is communicated to the reviewer (typically via email or notification)
- The reviewer submits the form, which sends a Temporal signal to resume execution
The form data (including reviewer inputs) is passed back to the workflow step as the step's input for subsequent processing.