{ "openapi": "3.0.1", "info": { "title": "OpenAPI", "description": "Tally's API", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.tally.so" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/forms": { "get": { "summary": "Retrieve a list of forms", "description": "Returns a paginated array of form objects.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default: 1)", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of forms per page (default: 50, max: 500)", "schema": { "type": "number", "minimum": 1, "maximum": 500 } }, { "name": "workspaceIds", "in": "query", "required": false, "description": "Filter forms by specific workspace IDs (encoded strings)", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "A paginated list of forms", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Form" } }, "page": { "type": "number", "description": "Current page number" }, "limit": { "type": "number", "description": "Number of items per page" }, "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more pages available" } }, "required": ["items", "page", "limit", "total", "hasMore"] } } } } } }, "post": { "summary": "Create a new form", "description": "Creates a new form, optionally based on a template or within a specific workspace.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "description": "ID of the workspace to create the form in. If not provided, uses the user's default workspace" }, "templateId": { "type": "string", "description": "ID of the template to base the form on" }, "folderId": { "type": "string", "description": "ID of the folder to place the form in. Must belong to the target workspace." }, "status": { "$ref": "#/components/schemas/FormStatus", "description": "Initial status of the form" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/Block" } }, "settings": { "$ref": "#/components/schemas/FormSettings" } }, "required": ["blocks", "status"] } } } }, "responses": { "201": { "description": "Form created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/forms/{formId}": { "get": { "summary": "Retrieve a form", "description": "Returns a single form by its ID with all its blocks and settings.", "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Form retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Form" }, { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/FormSettings" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/Block" } } } } ] } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Form not found" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete a form", "description": "Deletes a form by its ID and moves it to the trash.", "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Form successfully deleted" }, "401": { "description": "Unauthorized" }, "404": { "description": "Form not found" } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update a form", "description": "Updates a form's settings, blocks, or status.", "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the form" }, "status": { "$ref": "#/components/schemas/FormStatus", "description": "New status for the form" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/Block" }, "description": "Updated blocks for the form" }, "settings": { "$ref": "#/components/schemas/FormSettings", "description": "Updated settings for the form" } } } } } }, "responses": { "200": { "description": "Form updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Form not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/users/me": { "get": { "summary": "Retrieve current user information", "description": "Returns information about the current authenticated user.", "parameters": [ { "name": "timezone", "in": "query", "required": false, "description": "IANA timezone identifier (e.g., Europe/Brussels). When provided, updates the user's stored timezone.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "allOf": [{ "$ref": "#/components/schemas/User" }], "properties": { "subscriptionPlan": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/workspaces": { "get": { "summary": "Retrieve a list of workspaces", "description": "Returns a paginated array of workspace objects with associated users and pending invites.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default: 1)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "A paginated list of workspaces", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "page": { "type": "number", "description": "Current page number" }, "limit": { "type": "number", "description": "Number of items per page" }, "total": { "type": "number", "description": "Total number of items" }, "hasMore": { "type": "boolean", "description": "Whether there are more pages available" } }, "required": ["items", "page", "limit", "total", "hasMore"] } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create a new workspace", "description": "Creates a new workspace and assigns the authenticated user as a member. Requires a Pro subscription.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the workspace" } }, "required": ["name"] } } } }, "responses": { "201": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - User doesn't have a Pro subscription" } }, "security": [ { "bearerAuth": [] } ] } }, "/workspaces/{workspaceId}": { "get": { "summary": "Retrieve a workspace", "description": "Returns a single workspace by its ID with associated members.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "The ID of the workspace to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Workspace not found" } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update a workspace", "description": "Updates a workspace's information by its ID.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "The ID of the workspace to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the workspace" } }, "required": ["name"] } } } }, "responses": { "204": { "description": "Workspace updated successfully" }, "400": { "description": "Invalid request body" }, "401": { "description": "Unauthorized" }, "404": { "description": "Workspace not found" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete a workspace", "description": "Deletes a workspace and all its associated forms. The workspace and forms are moved to trash and can be restored later. Forms in DRAFT or PUBLISHED state will be marked as DELETED.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "The ID of the workspace to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Workspace successfully deleted" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - User doesn't have required permissions or Pro subscription" }, "404": { "description": "Workspace not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/workspaces/{workspaceId}/folders": { "get": { "summary": "List folders", "description": "Returns the folders in a workspace. Requires a Pro subscription.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "The ID of the workspace to list folders for", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Folders retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Folder" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Workspace not found" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create a new folder", "description": "Creates a folder in a workspace. Pass parentId to nest it inside another folder. Requires a Pro subscription.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "The ID of the workspace to create the folder in", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the folder" }, "parentId": { "type": "string", "description": "The ID of the parent folder to nest this folder under" } }, "required": ["name"] } } } }, "responses": { "201": { "description": "Folder created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "400": { "description": "Invalid request body or maximum folder nesting depth exceeded" }, "401": { "description": "Unauthorized" }, "404": { "description": "Workspace or parent folder not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/workspaces/{workspaceId}/folders/{id}": { "patch": { "summary": "Update a folder", "description": "Renames a folder by its ID. Requires a Pro subscription.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "The ID of the workspace the folder belongs to", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The ID of the folder to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the folder" } }, "required": ["name"] } } } }, "responses": { "204": { "description": "Folder updated successfully" }, "400": { "description": "Invalid request body" }, "401": { "description": "Unauthorized" }, "404": { "description": "Folder not found" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete a folder", "description": "Deletes a folder and its entire subtree by its ID, moving any contained forms to trash. Requires a Pro subscription.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "The ID of the workspace the folder belongs to", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The ID of the folder to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Folder deleted successfully" }, "401": { "description": "Unauthorized" }, "404": { "description": "Folder not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/organizations/{organizationId}/users": { "get": { "summary": "List organization users", "description": "Returns a list of all users in your organization.", "tags": ["Organization"], "responses": { "200": { "description": "A list of organization users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "403": { "description": "Forbidden - User doesn't have required permissions" } }, "security": [ { "bearerAuth": [] } ] } }, "/organizations/{organizationId}/users/{userId}": { "delete": { "summary": "Remove user from organization", "description": "Removes a user from your organization. Only the organization creator can remove other members, or users can remove themselves.", "tags": ["Organization"], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "The ID of the organization", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "The ID of the user to remove from the organization", "schema": { "type": "string" } } ], "responses": { "204": { "description": "User removed from organization successfully" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "403": { "description": "Forbidden - User doesn't have permission to remove this member or user doesn't exist in organization" }, "404": { "description": "Organization not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/organizations/{organizationId}/invites": { "get": { "summary": "List organization invites", "description": "Returns a list of all invites in your organization.", "tags": ["Organization"], "responses": { "200": { "description": "A list of organization invites", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "403": { "description": "Forbidden - User doesn't have required permissions" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create organization invites", "description": "Invites users to join specific workspaces within your organization.", "tags": ["Organization"], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "The ID of the organization", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceIds": { "type": "array", "items": { "type": "string" }, "description": "Array of workspace IDs to invite users to" }, "emails": { "type": "string", "description": "Comma or semicolon separated list of email addresses to invite" } }, "required": ["workspaceIds", "emails"] } } } }, "responses": { "204": { "description": "Invites created successfully. Existing users were added to workspaces and new users received invitation emails." }, "400": { "description": "Invalid request body - Invalid email format or missing required fields" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "403": { "description": "Forbidden - User doesn't have required permissions or Pro subscription" } }, "security": [ { "bearerAuth": [] } ] } }, "/organizations/{organizationId}/invites/{inviteId}": { "delete": { "summary": "Cancel an organization invite", "description": "Cancels a pending invitation to join workspaces within your organization. Only the user who created the invite can cancel it.", "tags": ["Organization"], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "description": "The ID of the organization", "schema": { "type": "string" } }, { "name": "inviteId", "in": "path", "required": true, "description": "The ID of the invite to cancel", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Invite cancelled successfully" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "403": { "description": "Forbidden - User doesn't have permission to cancel this invite or invite doesn't exist" } }, "security": [ { "bearerAuth": [] } ] } }, "/forms/{formId}/questions": { "get": { "summary": "List form questions", "description": "Returns a list of all questions in a form.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of questions", "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } }, "hasResponses": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found - Form not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/forms/{formId}/questions/{questionId}": { "patch": { "summary": "Update a form question", "description": "Updates a specific question in a form.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } }, { "name": "questionId", "in": "path", "required": true, "description": "The ID of the question", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The new title for the question" } } } } } }, "responses": { "200": { "description": "Question updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found - Form or question not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/forms/{formId}/blocks": { "get": { "summary": "List form blocks", "description": "Returns a list of all blocks in a form.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of blocks", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/Block" } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found - Form not found" } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "summary": "Update form blocks", "description": "Updates blocks in a form.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/Block" } }, "settings": { "allOf": [{ "$ref": "#/components/schemas/FormSettings" }], "nullable": true } }, "required": ["blocks"] } } } }, "responses": { "200": { "description": "Blocks updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Block" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found - Form not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/forms/{formId}/submissions": { "get": { "summary": "List form submissions", "description": "Returns a paginated list of form submissions with their responses.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default: 1)", "schema": { "type": "number" } }, { "name": "filter", "in": "query", "required": false, "description": "Filter submissions by status", "schema": { "type": "string", "enum": ["all", "completed", "partial"] } }, { "name": "startDate", "in": "query", "required": false, "description": "Filter submissions submitted on or after this date (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "required": false, "description": "Filter submissions submitted on or before this date (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "afterId", "in": "query", "required": false, "description": "Get submissions that came after a specific submission ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of submissions to return per page (default: 50, max: 500)", "schema": { "type": "number", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "List of form submissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number" }, "limit": { "type": "number", "description": "Number of submissions per page" }, "hasMore": { "type": "boolean", "description": "Whether there are more pages available" }, "totalNumberOfSubmissionsPerFilter": { "type": "object", "properties": { "all": { "type": "number", "description": "Total number of all submissions" }, "completed": { "type": "number", "description": "Total number of completed submissions" }, "partial": { "type": "number", "description": "Total number of partial submissions" } } }, "questions": { "type": "array", "description": "List of form questions", "items": { "$ref": "#/components/schemas/Question" } }, "submissions": { "type": "array", "description": "List of form submissions", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Submission ID" }, "formId": { "type": "string", "description": "Form ID" }, "isCompleted": { "type": "boolean", "description": "Whether the submission is completed" }, "submittedAt": { "type": "string", "format": "date-time", "description": "When the submission was submitted" }, "previewUrl": { "type": "string", "format": "uri", "description": "Signed URL to view the submission in a browser. Includes an access token, no expiry." }, "pdfUrl": { "type": "string", "format": "uri", "description": "Signed URL to download the submission as a PDF. Includes an access token, no expiry." }, "responses": { "type": "array", "description": "List of responses to form questions. Note: Only questions that have been answered will appear in this array.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Response ID" }, "formId": { "type": "string", "description": "Form ID" }, "questionId": { "type": "string", "description": "Question ID" }, "respondentId": { "type": "string", "description": "Respondent ID" }, "submissionId": { "type": "string", "nullable": true, "description": "Submission ID" }, "sessionUuid": { "type": "string", "format": "uuid", "description": "Session UUID" }, "answer": { "description": "The answer value for this question. Type varies based on question type.", "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object" } ] }, "formattedAnswer": { "type": "string", "description": "Formatted answer (e.g., for number inputs with custom formatting)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the response was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the response was last updated" } }, "required": [ "id", "formId", "questionId", "respondentId", "sessionUuid", "answer", "createdAt", "updatedAt" ] } } } } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Form not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/forms/{formId}/submissions/{submissionId}": { "get": { "summary": "Retrieve a form submission", "description": "Returns a specific form submission with all its responses and the form questions.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } }, { "name": "submissionId", "in": "path", "required": true, "description": "The ID of the submission to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Form submission retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "description": "List of form questions with their fields", "items": { "$ref": "#/components/schemas/Question" } }, "submission": { "type": "object", "description": "The form submission with responses", "properties": { "id": { "type": "string", "description": "Submission ID" }, "formId": { "type": "string", "description": "Form ID" }, "isCompleted": { "type": "boolean", "description": "Whether the submission is completed" }, "submittedAt": { "type": "string", "format": "date-time", "description": "When the submission was submitted" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the submission was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the submission was last updated" }, "previewUrl": { "type": "string", "format": "uri", "description": "Signed URL to view the submission in a browser. Includes an access token, no expiry." }, "pdfUrl": { "type": "string", "format": "uri", "description": "Signed URL to download the submission as a PDF. Includes an access token, no expiry." }, "responses": { "type": "array", "description": "List of responses to form questions. Note: Only questions that have been answered will appear in this array.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Response ID" }, "formId": { "type": "string", "description": "Form ID" }, "questionId": { "type": "string", "description": "Question ID" }, "respondentId": { "type": "string", "description": "Respondent ID" }, "submissionId": { "type": "string", "nullable": true, "description": "Submission ID" }, "sessionUuid": { "type": "string", "format": "uuid", "description": "Session UUID" }, "answer": { "description": "The answer value for this question. Type varies based on question type.", "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object" } ] }, "formattedAnswer": { "type": "string", "description": "Formatted answer (e.g., for number inputs with custom formatting)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the response was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the response was last updated" } }, "required": [ "id", "formId", "questionId", "respondentId", "sessionUuid", "answer", "createdAt", "updatedAt" ] } } } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Form or submission not found" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete a form submission", "description": "Deletes a specific submission from a form.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } }, { "name": "submissionId", "in": "path", "required": true, "description": "The ID of the submission to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Submission deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Form or submission not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/forms/{formId}/analytics/metrics": { "get": { "summary": "Retrieve form metrics", "description": "Returns aggregate metrics for a form (visits, submissions, completion rate, and more).", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": true, "description": "Time period for the analytics data", "schema": { "type": "string", "enum": [ "today", "yesterday", "24h", "7d", "30d", "3m", "6m", "12m", "all" ] } } ], "responses": { "200": { "description": "Form metrics analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "visits": { "type": "number" }, "visitDuration": { "type": "number" }, "submissions": { "type": "number" }, "uniqueRespondents": { "type": "number" }, "totalViews": { "type": "number" }, "starts": { "type": "number" }, "completions": { "type": "number" }, "completionDuration": { "type": "number" }, "completionRate": { "type": "number" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Form not found" } } } }, "/forms/{formId}/analytics/visits": { "get": { "summary": "Retrieve form visits", "description": "Returns visit counts for a form over time.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": true, "description": "Time period for the analytics data", "schema": { "type": "string", "enum": [ "today", "yesterday", "24h", "7d", "30d", "3m", "6m", "12m", "all" ] } } ], "responses": { "200": { "description": "Form visits analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "totalVisits": { "type": "number" } } } }, "interval": { "type": "number" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Form not found" } } } }, "/forms/{formId}/analytics/submissions": { "get": { "summary": "Retrieve form submission analytics", "description": "Returns completed and partial submission counts for a form over time.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": true, "description": "Time period for the analytics data", "schema": { "type": "string", "enum": [ "today", "yesterday", "24h", "7d", "30d", "3m", "6m", "12m", "all" ] } } ], "responses": { "200": { "description": "Form submissions analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "completed": { "type": "number" }, "partial": { "type": "number" } } } }, "interval": { "type": "number" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Form not found" } } } }, "/forms/{formId}/analytics/dimensions": { "get": { "summary": "Retrieve form dimensions", "description": "Returns visitor breakdowns by source, browser, OS, device, and location.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": true, "description": "Time period for the analytics data", "schema": { "type": "string", "enum": [ "today", "yesterday", "24h", "7d", "30d", "3m", "6m", "12m", "all" ] } } ], "responses": { "200": { "description": "Form dimensions analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "object", "additionalProperties": { "type": "number" } }, "browser": { "type": "object", "additionalProperties": { "type": "number" } }, "os": { "type": "object", "additionalProperties": { "type": "number" } }, "device": { "type": "object", "additionalProperties": { "type": "number" } }, "country": { "type": "object", "additionalProperties": { "type": "number" } }, "city": { "type": "object", "additionalProperties": { "type": "number" } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Form not found" } } } }, "/forms/{formId}/analytics/drop-off": { "get": { "summary": "Retrieve form drop-off", "description": "Returns per-question drop-off statistics for a form.", "tags": ["Forms"], "parameters": [ { "name": "formId", "in": "path", "required": true, "description": "The ID of the form", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": true, "description": "Time period for the analytics data", "schema": { "type": "string", "enum": [ "today", "yesterday", "24h", "7d", "30d", "3m", "6m", "12m", "all" ] } } ], "responses": { "200": { "description": "Form drop-off analytics", "content": { "application/json": { "schema": { "type": "object", "nullable": true, "properties": { "stats": { "type": "object", "properties": { "totalVisitors": { "type": "number" }, "formStarts": { "type": "number" }, "formCompletes": { "type": "number" }, "completionRate": { "type": "number" }, "completionTimeInSeconds": { "type": "number" }, "visitDurationInSeconds": { "type": "number" } } }, "dataAvailableSince": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "type": "object", "properties": { "blockGroupUuid": { "type": "string" }, "views": { "type": "number" }, "startedViews": { "type": "number" }, "answers": { "type": "number" }, "drops": { "type": "number" }, "title": { "type": "string" }, "type": { "type": "string" }, "answerRate": { "type": "number" }, "dropRate": { "type": "number" }, "isRequired": { "type": "boolean" } } } }, "hasConditionalLogic": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Form not found" } } } }, "/webhooks": { "get": { "summary": "List webhooks", "description": "Returns a paginated list of all webhooks across your accessible forms and workspaces.", "tags": ["Webhooks"], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default: 1)", "schema": { "type": "number", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of webhooks per page (default: 25, max: 100)", "schema": { "type": "number", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "description": "List of webhooks", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook ID" }, "formId": { "type": "string", "description": "Form ID the webhook is attached to" }, "url": { "type": "string", "description": "The webhook endpoint URL" }, "signingSecret": { "type": "string", "nullable": true, "description": "Secret used to sign webhook payloads" }, "httpHeaders": { "type": "array", "nullable": true, "description": "Custom HTTP headers to include in webhook requests", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Header name" }, "value": { "type": "string", "description": "Header value" } } } }, "eventTypes": { "type": "array", "description": "Types of events this webhook subscribes to", "items": { "$ref": "#/components/schemas/EventType" } }, "externalSubscriber": { "type": "string", "nullable": true, "description": "External subscriber identifier" }, "isEnabled": { "type": "boolean", "description": "Whether the webhook is enabled" }, "lastSyncedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the webhook was last synced" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the webhook was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the webhook was last updated" } } } }, "page": { "type": "number", "description": "Current page number" }, "limit": { "type": "number", "description": "Number of webhooks per page" }, "hasMore": { "type": "boolean", "description": "Whether there are more pages available" }, "totalCount": { "type": "number", "description": "Total number of webhooks" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "summary": "Create a webhook", "description": "Creates a new webhook for a form to receive form events.", "tags": ["Webhooks"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "formId": { "type": "string", "description": "The ID of the form to create the webhook for" }, "url": { "type": "string", "description": "The URL to send webhook events to" }, "signingSecret": { "type": "string", "description": "Optional secret used to sign webhook payloads", "nullable": true }, "httpHeaders": { "type": "array", "description": "Optional custom HTTP headers to include in webhook requests", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The header name" }, "value": { "type": "string", "description": "The header value" } }, "required": ["name", "value"] } }, "eventTypes": { "type": "array", "description": "Types of events to receive", "items": { "$ref": "#/components/schemas/EventType" } }, "externalSubscriber": { "type": "string", "description": "Optional identifier for the external subscriber" } }, "required": ["formId", "url", "eventTypes"] } } } }, "responses": { "201": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "eventTypes": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "isEnabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{webhookId}": { "patch": { "summary": "Update a webhook", "description": "Updates an existing webhook configuration.", "tags": ["Webhooks"], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "The ID of the webhook to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "formId": { "type": "string", "description": "The ID of the form the webhook is for" }, "url": { "type": "string", "description": "The URL to send webhook events to" }, "signingSecret": { "type": "string", "description": "Optional secret used to sign webhook payloads", "nullable": true }, "httpHeaders": { "type": "array", "description": "Optional custom HTTP headers to include in webhook requests", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The header name" }, "value": { "type": "string", "description": "The header value" } }, "required": ["name", "value"] } }, "eventTypes": { "type": "array", "description": "Types of events to receive", "items": { "$ref": "#/components/schemas/EventType" } }, "isEnabled": { "type": "boolean", "description": "Whether the webhook is enabled" } }, "required": ["formId", "url", "eventTypes", "isEnabled"] } } } }, "responses": { "204": { "description": "Webhook updated successfully" }, "400": { "description": "Invalid request body" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Webhook not found" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "summary": "Delete a webhook", "description": "Deletes a webhook. If this is the last webhook for a form, the webhooks integration will also be marked as deleted.", "tags": ["Webhooks"], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "The ID of the webhook to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Webhook deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Webhook not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{webhookId}/events": { "get": { "summary": "List webhook events", "description": "Returns a paginated list of webhook delivery events for a specific webhook, including delivery status, response codes, and retry information.", "tags": ["Webhooks"], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "The ID of the webhook", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (default: 1)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of webhook events", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number" }, "limit": { "type": "number", "description": "Number of events per page (25)" }, "hasMore": { "type": "boolean", "description": "Whether there are more pages available" }, "totalNumberOfEvents": { "type": "number", "description": "Total number of webhook events" }, "events": { "type": "array", "description": "List of webhook events", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Event ID" }, "webhookId": { "type": "string", "description": "Webhook ID" }, "webhookUrl": { "type": "string", "description": "The URL the webhook was sent to" }, "eventType": { "type": "string", "enum": ["FORM_RESPONSE"], "description": "Type of event" }, "deliveryStatus": { "type": "string", "enum": [ "QUEUED", "SUCCEEDED", "FAILED", "DROPPED" ], "description": "Delivery status of the webhook" }, "statusCode": { "type": "number", "nullable": true, "description": "HTTP status code returned by the webhook endpoint" }, "response": { "type": "string", "nullable": true, "description": "Response body from the webhook endpoint" }, "retry": { "type": "number", "description": "Number of retry attempts" }, "payload": { "type": "object", "description": "The webhook payload that was sent" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the event was last updated" } } } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Webhook not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{webhookId}/events/{eventId}": { "post": { "summary": "Retry webhook event", "description": "Retries sending a failed webhook event. This will attempt to deliver the webhook payload again to the configured endpoint.", "tags": ["Webhooks"], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "The ID of the webhook", "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "required": true, "description": "The ID of the webhook event to retry", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Webhook event retry initiated successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - User doesn't have access to this webhook or event" }, "404": { "description": "Webhook or event not found" } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "FormStatus": { "type": "string", "enum": ["BLANK", "DRAFT", "PUBLISHED"], "description": "Deleting a form is done through DELETE /forms/{formId}, which moves it to the trash so it can be restored." }, "BlockUuid": { "type": "string", "format": "uuid", "description": "Unique identifier for this block." }, "GroupUuid": { "type": "string", "format": "uuid", "description": "Groups related blocks together. For standalone blocks, use the block's own uuid. For child blocks (e.g., dropdown options, multiple choice options), use the parent block's uuid so all children share the same groupUuid." }, "IsHidden": { "type": "boolean", "description": "When true, hides the field from respondents. Hidden fields don't appear on the form but can be shown via conditional logic." }, "IsFolded": { "type": "boolean", "description": "When true, collapses the question group in the form builder UI, hiding child blocks while showing a count indicator. Only applies to Title and Label blocks." }, "IsRequired": { "type": "boolean", "description": "When true, the field must be filled out before the form can be submitted. Respondents will see a required indicator." }, "HasDefaultAnswer": { "type": "boolean", "description": "When true, the field is pre-populated with the value from defaultAnswer when the form loads." }, "HasMinCharacters": { "type": "boolean", "description": "Set to true to enable minCharacters validation. When true, minCharacters must be provided." }, "MinCharacters": { "type": "number", "description": "The minimum number of characters allowed. Required when hasMinCharacters is true." }, "HasMaxCharacters": { "type": "boolean", "description": "Set to true to enable maxCharacters validation. When true, maxCharacters must be provided." }, "MaxCharacters": { "type": "number", "description": "The maximum number of characters allowed. Required when hasMaxCharacters is true." }, "HasMinChoices": { "type": "boolean", "description": "Set to true to enable minChoices validation. When true, minChoices must be provided." }, "MinChoices": { "type": "number", "minimum": 0, "description": "Minimum number of selections required. Required when hasMinChoices is true." }, "HasMaxChoices": { "type": "boolean", "description": "Set to true to enable maxChoices validation. When true, maxChoices must be provided." }, "MaxChoices": { "type": "number", "minimum": 0, "description": "Maximum number of selections allowed. Required when hasMaxChoices is true." }, "OptionIndex": { "type": "number", "description": "Position of this option within the group (0-indexed)." }, "IsFirstOption": { "type": "boolean", "description": "True if this is the first option in the group." }, "IsLastOption": { "type": "boolean", "description": "True if this is the last option in the group." }, "AllowMultiple": { "type": "boolean", "description": "Allow selecting multiple options. Only needs to be set on the first option in the group." }, "ColorCodeOptions": { "type": "boolean", "description": "Enable color-coded options display. Only needs to be set on the first option in the group." }, "OptionColor": { "type": "string", "enum": [ "red", "orange", "yellow", "green", "blue", "purple", "pink", "gray" ], "description": "Color name for this option when colorCodeOptions is enabled." }, "DefaultAnswerString": { "description": "The default value for this field. Can be either a raw string value or a Field reference to dynamically populate from another field's answer.", "oneOf": [ { "$ref": "#/components/schemas/Field" }, { "type": "string" } ] }, "DefaultAnswerNumber": { "description": "The default value for this field. Can be either a raw number value or a Field reference to dynamically populate from another field's answer.", "oneOf": [ { "$ref": "#/components/schemas/Field" }, { "type": "number" } ] }, "Button": { "type": "object", "description": "Customizes the button text for form navigation.", "properties": { "label": { "type": "string", "description": "The text displayed on the button (e.g., \"Start\", \"Next\", \"Submit\")." } } }, "Name": { "type": "string", "description": "Optional identifier for this block. Can be used to reference the block in integrations or conditional logic." }, "Html": { "type": "string", "description": "Rich text content. Supports basic formatting: bold, italic, underline, links, and mentions." }, "RichText": { "type": "object", "nullable": true, "description": "Rich text value represented as HTML with optional field mentions.", "properties": { "html": { "$ref": "#/components/schemas/Html" }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" } } }, "required": ["html"] }, "EmbedProvider": { "type": "string", "description": "The name of the content provider. Auto-detected from the URL via oEmbed protocol or pattern matching. Common values include: YouTube, Loom, Twitch, Twitter, Canva, Google Maps, Imgur, JSFiddle, GitHub Gist, Video, Audio, Image, PDF. May also be any other oEmbed-supported provider." }, "EmbedUrl": { "type": "string", "format": "uri", "description": "The URL of the content to embed. Supports video platforms (YouTube, Loom, Twitch, etc.) and audio platforms. The URL is used to auto-detect the provider and fetch embed data via oEmbed." }, "FormSettings": { "type": "object", "properties": { "language": { "type": "string", "maxLength": 12, "nullable": true }, "isClosed": { "type": "boolean", "default": false }, "closeMessageTitle": { "type": "string", "nullable": true }, "closeMessageDescription": { "type": "string", "nullable": true }, "closeTimezone": { "type": "string", "maxLength": 256, "nullable": true }, "closeDate": { "type": "string", "maxLength": 12, "nullable": true }, "closeTime": { "type": "string", "maxLength": 12, "nullable": true }, "submissionsLimit": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true }, "uniqueSubmissionKey": { "$ref": "#/components/schemas/RichText" }, "redirectOnCompletion": { "$ref": "#/components/schemas/RichText" }, "hasSelfEmailNotifications": { "type": "boolean", "default": false }, "selfEmailTo": { "$ref": "#/components/schemas/RichText" }, "selfEmailReplyTo": { "$ref": "#/components/schemas/RichText" }, "selfEmailSubject": { "$ref": "#/components/schemas/RichText" }, "selfEmailFromName": { "$ref": "#/components/schemas/RichText" }, "selfEmailBody": { "$ref": "#/components/schemas/RichText" }, "hasRespondentEmailNotifications": { "type": "boolean", "default": false }, "respondentEmailTo": { "$ref": "#/components/schemas/RichText" }, "respondentEmailReplyTo": { "$ref": "#/components/schemas/RichText" }, "respondentEmailSubject": { "$ref": "#/components/schemas/RichText" }, "respondentEmailFromName": { "$ref": "#/components/schemas/RichText" }, "respondentEmailBody": { "$ref": "#/components/schemas/RichText" }, "hasProgressBar": { "type": "boolean", "default": false }, "hasPartialSubmissions": { "type": "boolean", "default": false }, "pageAutoJump": { "type": "boolean", "default": false }, "saveForLater": { "type": "boolean", "default": true }, "styles": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true }, "submissionsDataRetentionDuration": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true }, "submissionsDataRetentionUnit": { "type": "string", "maxLength": 12, "nullable": true } } }, "Form": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "workspaceId": { "type": "string" }, "status": { "$ref": "#/components/schemas/FormStatus" }, "numberOfSubmissions": { "type": "number" }, "isClosed": { "type": "boolean" }, "payments": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "workspaceId", "status", "numberOfSubmissions", "isClosed", "createdAt", "updatedAt" ] }, "Block": { "oneOf": [ { "$ref": "#/components/schemas/FormTitleBlock" }, { "$ref": "#/components/schemas/TitleBlock" }, { "$ref": "#/components/schemas/TextBlock" }, { "$ref": "#/components/schemas/LabelBlock" }, { "$ref": "#/components/schemas/Heading1Block" }, { "$ref": "#/components/schemas/Heading2Block" }, { "$ref": "#/components/schemas/Heading3Block" }, { "$ref": "#/components/schemas/ImageBlock" }, { "$ref": "#/components/schemas/EmbedBlock" }, { "$ref": "#/components/schemas/EmbedVideoBlock" }, { "$ref": "#/components/schemas/EmbedAudioBlock" }, { "$ref": "#/components/schemas/DividerBlock" }, { "$ref": "#/components/schemas/PageBreakBlock" }, { "$ref": "#/components/schemas/InputTextBlock" }, { "$ref": "#/components/schemas/TextareaBlock" }, { "$ref": "#/components/schemas/InputNumberBlock" }, { "$ref": "#/components/schemas/InputEmailBlock" }, { "$ref": "#/components/schemas/InputLinkBlock" }, { "$ref": "#/components/schemas/InputPhoneNumberBlock" }, { "$ref": "#/components/schemas/InputDateBlock" }, { "$ref": "#/components/schemas/InputTimeBlock" }, { "$ref": "#/components/schemas/MultipleChoiceOptionBlock" }, { "$ref": "#/components/schemas/CheckboxBlock" }, { "$ref": "#/components/schemas/DropdownOptionBlock" }, { "$ref": "#/components/schemas/RankingOptionBlock" }, { "$ref": "#/components/schemas/MultiSelectOptionBlock" }, { "$ref": "#/components/schemas/LinearScaleBlock" }, { "$ref": "#/components/schemas/RatingBlock" }, { "$ref": "#/components/schemas/MatrixBlock" }, { "$ref": "#/components/schemas/MatrixRowBlock" }, { "$ref": "#/components/schemas/MatrixColumnBlock" }, { "$ref": "#/components/schemas/FileUploadBlock" }, { "$ref": "#/components/schemas/SignatureBlock" }, { "$ref": "#/components/schemas/PaymentBlock" }, { "$ref": "#/components/schemas/HiddenFieldsBlock" }, { "$ref": "#/components/schemas/ConditionalLogicBlock" }, { "$ref": "#/components/schemas/CalculatedFieldsBlock" }, { "$ref": "#/components/schemas/CaptchaBlock" }, { "$ref": "#/components/schemas/RespondentCountryBlock" } ], "discriminator": { "propertyName": "type" } }, "CalculatedField": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "$ref": "#/components/schemas/Name", "description": "Name your calculated field to easily retrieve it in calculations later on." }, "type": { "$ref": "#/components/schemas/CalculatedFieldType" }, "value": { "oneOf": [{ "type": "string" }, { "type": "number" }], "description": "An initial value as a starting point of your calculation. This can be zero (for numbers) or left blank (for text)." } }, "required": ["uuid"] }, "HiddenField": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "$ref": "#/components/schemas/Name" } }, "required": ["uuid"] }, "EventType": { "type": "string", "enum": ["FORM_RESPONSE"] }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "fullName": { "type": "string" }, "email": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri", "nullable": true }, "organizationId": { "type": "string" }, "isDeleted": { "type": "boolean" }, "hasTwoFactorEnabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subscriptionPlan": { "type": "string", "enum": ["FREE", "PRO", "BUSINESS"] } } }, "Folder": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "workspaceId": { "type": "string" }, "parentId": { "type": "string", "nullable": true }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "workspaceId", "parentId", "createdByUserId", "createdAt", "updatedAt" ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "index": { "type": "integer" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "invites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "workspaceIds": { "type": "array", "items": { "type": "string" } } } } }, "folders": { "type": "array", "items": { "$ref": "#/components/schemas/Folder" } }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "index", "createdByUserId", "createdAt", "updatedAt" ] }, "Invite": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": ["id", "email", "createdAt", "updatedAt"] }, "QuestionField": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/BlockType" }, "blockGroupUuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } }, "Question": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/BlockType" }, "title": { "type": "string" }, "isTitleModifiedByUser": { "type": "boolean" }, "formId": { "type": "string" }, "isDeleted": { "type": "boolean" }, "numberOfResponses": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionField" } } } }, "Field": { "type": "object", "description": "A reference to a form field, used to dynamically access another field's value (e.g., for default answers or mentions).", "properties": { "uuid": { "oneOf": [ { "type": "string", "format": "uuid" }, { "$ref": "#/components/schemas/UtilityUuid" } ], "description": "Unique identifier of the referenced field. A UUID for regular fields, or a UtilityUuid value when type is UTILITY." }, "type": { "allOf": [{ "$ref": "#/components/schemas/FieldType" }], "description": "The category of field being referenced." }, "questionType": { "allOf": [{ "$ref": "#/components/schemas/FieldQuestionType" }], "description": "The block type of the referenced field." }, "blockGroupUuid": { "oneOf": [ { "type": "string", "format": "uuid" }, { "$ref": "#/components/schemas/UtilityUuid" } ], "description": "Identifier of the block group containing the referenced field. A UUID for regular fields, or a UtilityUuid value when type is UTILITY." }, "title": { "type": "string", "description": "Display title of the referenced field." }, "calculatedFieldType": { "allOf": [{ "$ref": "#/components/schemas/CalculatedFieldType" }], "description": "For calculated fields, specifies whether the result is NUMBER or TEXT." }, "payload": { "type": "object", "description": "Additional configuration for utility fields. Only present when type is UTILITY." } }, "required": ["uuid", "type", "questionType", "blockGroupUuid", "title"] }, "FieldType": { "type": "string", "description": "The category of a field reference.", "enum": [ "INPUT_FIELD", "CALCULATED_FIELD", "HIDDEN_FIELD", "UTILITY", "PLACEHOLDER", "METADATA" ] }, "UtilityUuid": { "type": "string", "description": "Identifier used as uuid and blockGroupUuid for utility field references.", "enum": ["utility::today()"] }, "FieldQuestionType": { "type": "string", "description": "Block types that produce answer values and can be referenced as field sources.", "enum": [ "INPUT_TEXT", "INPUT_NUMBER", "INPUT_EMAIL", "INPUT_LINK", "INPUT_PHONE_NUMBER", "INPUT_DATE", "INPUT_TIME", "TEXTAREA", "RATING", "LINEAR_SCALE", "CHECKBOX", "MULTIPLE_CHOICE_OPTION", "DROPDOWN_OPTION", "RANKING_OPTION", "MULTI_SELECT_OPTION", "HIDDEN_FIELDS", "CALCULATED_FIELDS" ] }, "CalculatedFieldType": { "type": "string", "enum": ["NUMBER", "TEXT"], "description": "Choose whether the value will be text or a numeric value (number)." }, "Mention": { "type": "object", "description": "A dynamic placeholder that references another field's value. Used to personalize form content (e.g., \"Hello @name\").", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Unique identifier for this mention." }, "field": { "allOf": [{ "$ref": "#/components/schemas/Field" }], "description": "The field being referenced. Its value replaces the mention placeholder at runtime." }, "defaultValue": { "description": "Fallback value displayed when the referenced field has no data.", "nullable": true } }, "required": ["uuid", "field"] }, "BlockType": { "type": "string", "enum": [ "FORM_TITLE", "TEXT", "LABEL", "TITLE", "HEADING_1", "HEADING_2", "HEADING_3", "DIVIDER", "PAGE_BREAK", "IMAGE", "EMBED", "EMBED_VIDEO", "EMBED_AUDIO", "QUESTION", "MATRIX", "INPUT_TEXT", "INPUT_NUMBER", "INPUT_EMAIL", "INPUT_LINK", "INPUT_PHONE_NUMBER", "INPUT_DATE", "INPUT_TIME", "TEXTAREA", "FILE_UPLOAD", "LINEAR_SCALE", "RATING", "HIDDEN_FIELDS", "MULTIPLE_CHOICE_OPTION", "CHECKBOX", "DROPDOWN_OPTION", "RANKING_OPTION", "MULTI_SELECT_OPTION", "PAYMENT", "SIGNATURE", "MATRIX_ROW", "MATRIX_COLUMN", "CONDITIONAL_LOGIC", "CALCULATED_FIELDS", "CAPTCHA", "RESPONDENT_COUNTRY" ] }, "DisableDays": { "type": "string", "description": "Days or date ranges to disable in the date picker.", "enum": [ "IN_THE_PAST", "IN_THE_FUTURE", "MONDAYS", "TUESDAYS", "WEDNESDAYS", "THURSDAYS", "FRIDAYS", "SATURDAYS", "SUNDAYS" ] }, "DecimalSeparator": { "type": "string", "enum": [".", ","], "description": "The literal character used as decimal separator." }, "ThousandsSeparator": { "type": "string", "enum": ["", ".", ",", " "], "description": "The literal character used as thousands separator. An empty string means no separator." }, "NumberFormat": { "type": "string", "enum": ["NUMBER", "PERCENT", "US_DOLLAR", "EURO", "POUND", "CUSTOM"] }, "Currency": { "type": "string", "enum": [ "AED", "AUD", "BGN", "BRL", "CAD", "CHF", "CNY", "CZK", "DKK", "EUR", "GBP", "HKD", "HRK", "HUF", "IDR", "ILS", "INR", "ISK", "JPY", "KRW", "MAD", "MXN", "MYR", "NOK", "NZD", "PHP", "PLN", "RON", "RSD", "RUB", "SAR", "SEK", "SGD", "THB", "TRY", "TWD", "UAH", "USD", "VND", "ZAR" ] }, "AllowedFiles": { "type": "object", "description": "Allowed file types for upload. Keys are MIME type categories, values are arrays of file extensions or ['*'] for all types in that category.", "properties": { "image/*": { "type": "array", "items": { "type": "string", "enum": [ "*", ".jpg", ".jpeg", ".png", ".gif", ".svg", ".heic", ".webp", ".bmp", ".psd" ] }, "description": "Image file extensions or ['*'] for all image types." }, "video/*": { "type": "array", "items": { "type": "string", "enum": ["*", ".mp4", ".mov", ".webm"] }, "description": "Video file extensions or ['*'] for all video types." }, "audio/*": { "type": "array", "items": { "type": "string", "enum": ["*", ".mp3", ".wav", ".m4a"] }, "description": "Audio file extensions or ['*'] for all audio types." }, "text/*": { "type": "array", "items": { "type": "string", "enum": ["*", ".txt", ".csv", ".html", ".xml"] }, "description": "Text file extensions or ['*'] for all text types." }, "application/*": { "type": "array", "items": { "type": "string", "enum": [ "*", ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".zip", ".rar", ".json", ".gzip", ".odt" ] }, "description": "Application/document file extensions or ['*'] for all application types." } }, "additionalProperties": false, "example": { "image/*": [".png", ".jpg", ".gif"], "application/*": [".pdf"] } }, "SingleConditional": { "type": "object", "required": ["uuid", "type", "payload"], "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": ["SINGLE"] }, "payload": { "type": "object", "description": "Single condition comparing one field to a value.", "properties": { "field": { "$ref": "#/components/schemas/Field" }, "comparison": { "type": "string", "enum": [ "IS", "IS_NOT", "IS_ANY_OF", "IS_NOT_ANY_OF", "IS_EVERY_OF", "CONTAINS", "DOES_NOT_CONTAIN", "STARTS_WITH", "DOES_NOT_START_WITH", "ENDS_WITH", "DOES_NOT_END_WITH", "IS_EMPTY", "IS_NOT_EMPTY", "EQUAL", "NOT_EQUAL", "GREATER_THAN", "LESS_THAN", "GREATER_OR_EQUAL_THAN", "LESS_OR_EQUAL_THAN", "IS_BEFORE", "IS_AFTER" ], "description": "Comparison operator for the condition." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } }, { "$ref": "#/components/schemas/Field" } ], "nullable": true, "description": "Comparison value or field reference. Nullable for empty checks." } }, "required": ["field", "comparison", "value"] } } }, "GroupConditional": { "type": "object", "required": ["uuid", "type", "payload"], "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": ["GROUP"] }, "payload": { "type": "object", "description": "Group of conditions combined with AND/OR.", "properties": { "logicalOperator": { "type": "string", "enum": ["AND", "OR"], "description": "How to combine child conditions (AND/OR)." }, "conditionals": { "type": "array", "items": { "$ref": "#/components/schemas/Conditional" }, "description": "Child conditions in this group." } }, "required": ["logicalOperator", "conditionals"] } } }, "Conditional": { "description": "Union of single and group conditionals.", "oneOf": [ { "$ref": "#/components/schemas/SingleConditional" }, { "$ref": "#/components/schemas/GroupConditional" } ], "discriminator": { "propertyName": "type", "mapping": { "SINGLE": "#/components/schemas/SingleConditional", "GROUP": "#/components/schemas/GroupConditional" } } }, "ConditionalAction": { "type": "object", "description": "Conditional action wrapper.", "required": ["uuid", "type"], "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "JUMP_TO_PAGE", "CALCULATE", "REQUIRE_ANSWER", "SHOW_BLOCKS", "HIDE_BLOCKS", "HIDE_BUTTON_TO_DISABLE_COMPLETION" ], "description": "Action type; determines which payload fields are relevant." }, "payload": { "type": "object", "description": "Action details executed when conditions match.", "properties": { "jumpToPage": { "oneOf": [{ "type": "string" }, { "type": "number" }], "description": "Target page number or page UUID to jump to." }, "showBlocks": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Block UUIDs to show when condition matches." }, "hideBlocks": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Block UUIDs to hide when condition matches." }, "requireAnswer": { "type": "string", "format": "uuid", "description": "Block UUID to mark as required when condition matches." }, "calculate": { "type": "object", "properties": { "field": { "$ref": "#/components/schemas/Field" }, "operator": { "type": "string", "enum": [ "ADDITION", "SUBTRACTION", "MULTIPLICATION", "DIVISION", "ASSIGNMENT" ], "description": "Math or assignment operator." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } }, { "$ref": "#/components/schemas/Field" } ], "description": "Value or field reference used in the calculation." } }, "required": ["field", "operator", "value"], "description": "Calculation to apply when condition matches." } } } } }, "BlockPayload": { "oneOf": [ { "$ref": "#/components/schemas/FormTitlePayload" }, { "$ref": "#/components/schemas/TextPayload" }, { "$ref": "#/components/schemas/LabelPayload" }, { "$ref": "#/components/schemas/TitlePayload" }, { "$ref": "#/components/schemas/Heading1Payload" }, { "$ref": "#/components/schemas/Heading2Payload" }, { "$ref": "#/components/schemas/Heading3Payload" }, { "$ref": "#/components/schemas/DividerPayload" }, { "$ref": "#/components/schemas/PageBreakPayload" }, { "$ref": "#/components/schemas/ImagePayload" }, { "$ref": "#/components/schemas/EmbedPayload" }, { "$ref": "#/components/schemas/EmbedVideoPayload" }, { "$ref": "#/components/schemas/EmbedAudioPayload" }, { "$ref": "#/components/schemas/MatrixPayload" }, { "$ref": "#/components/schemas/InputTextPayload" }, { "$ref": "#/components/schemas/InputNumberPayload" }, { "$ref": "#/components/schemas/InputEmailPayload" }, { "$ref": "#/components/schemas/InputLinkPayload" }, { "$ref": "#/components/schemas/InputPhoneNumberPayload" }, { "$ref": "#/components/schemas/InputDatePayload" }, { "$ref": "#/components/schemas/InputTimePayload" }, { "$ref": "#/components/schemas/TextareaPayload" }, { "$ref": "#/components/schemas/FileUploadPayload" }, { "$ref": "#/components/schemas/LinearScalePayload" }, { "$ref": "#/components/schemas/RatingPayload" }, { "$ref": "#/components/schemas/HiddenFieldsPayload" }, { "$ref": "#/components/schemas/MultipleChoiceOptionPayload" }, { "$ref": "#/components/schemas/CheckboxPayload" }, { "$ref": "#/components/schemas/DropdownOptionPayload" }, { "$ref": "#/components/schemas/RankingOptionPayload" }, { "$ref": "#/components/schemas/MultiSelectOptionPayload" }, { "$ref": "#/components/schemas/PaymentPayload" }, { "$ref": "#/components/schemas/SignaturePayload" }, { "$ref": "#/components/schemas/MatrixRowPayload" }, { "$ref": "#/components/schemas/MatrixColumnPayload" }, { "$ref": "#/components/schemas/ConditionalLogicPayload" }, { "$ref": "#/components/schemas/CalculatedFieldsPayload" }, { "$ref": "#/components/schemas/CaptchaPayload" }, { "$ref": "#/components/schemas/RespondentCountryPayload" } ] }, "FormTitlePayload": { "type": "object", "title": "FormTitlePayload", "description": "Payload for FORM_TITLE block type. Used for the main form title with optional logo and cover image.", "properties": { "html": { "$ref": "#/components/schemas/Html" }, "title": { "type": "string", "nullable": true, "description": "Plain-text form title. Used as the form name when provided." }, "logo": { "type": "string", "format": "uri", "description": "URL of the logo image displayed as form branding. Recommended size: 200x200 pixels. Rendered as a circular image." }, "cover": { "type": "string", "format": "uri", "description": "URL of a full-width cover image displayed at the top of the form. Recommended minimum width: 1500 pixels." }, "coverSettings": { "type": "object", "properties": { "objectPositionYPercent": { "type": "number", "minimum": 0, "maximum": 100, "default": 50, "description": "Vertical position of the cover image as a percentage. Controls the CSS object-position property. 0 shows the top edge, 50 centers the image, and 100 shows the bottom edge." } } }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" } }, "button": { "$ref": "#/components/schemas/Button" } } }, "TextPayload": { "type": "object", "title": "TextPayload", "description": "Payload for TEXT block type. Used for text content blocks.", "properties": { "html": { "$ref": "#/components/schemas/Html" }, "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "LabelPayload": { "type": "object", "title": "LabelPayload", "description": "Payload for LABEL block type. Used for label elements.", "properties": { "html": { "$ref": "#/components/schemas/Html" }, "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isFolded": { "$ref": "#/components/schemas/IsFolded" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "TitlePayload": { "type": "object", "title": "TitlePayload", "description": "Payload for TITLE block type. Used for title elements.", "properties": { "html": { "$ref": "#/components/schemas/Html" }, "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isFolded": { "$ref": "#/components/schemas/IsFolded" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "Heading1Payload": { "type": "object", "title": "Heading1Payload", "description": "Payload for HEADING_1 block type. Used for H1 headings.", "properties": { "html": { "$ref": "#/components/schemas/Html" }, "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "Heading2Payload": { "type": "object", "title": "Heading2Payload", "description": "Payload for HEADING_2 block type. Used for H2 headings.", "properties": { "html": { "$ref": "#/components/schemas/Html" }, "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "Heading3Payload": { "type": "object", "title": "Heading3Payload", "description": "Payload for HEADING_3 block type. Used for H3 headings.", "properties": { "html": { "$ref": "#/components/schemas/Html" }, "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "DividerPayload": { "type": "object", "title": "DividerPayload", "description": "Payload for DIVIDER block type. Used for visual separators.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "PageBreakPayload": { "type": "object", "title": "PageBreakPayload", "description": "Payload for PAGE_BREAK block type. Used for multi-page form navigation.", "properties": { "index": { "type": "number", "description": "Sequential position of this page break within the form, starting from 0." }, "isFirst": { "type": "boolean", "description": "When true, indicates this is the first page break in the form." }, "isLast": { "type": "boolean", "description": "When true, indicates this is the last page break in the form." }, "name": { "$ref": "#/components/schemas/Name" }, "isThankYouPage": { "type": "boolean", "description": "When true, indicates this page break represents a custom thank-you page shown after form submission." }, "isFolded": { "type": "boolean", "description": "When true, indicates this page is collapsed in the form builder." }, "isQualifiedForThankYouPage": { "type": "boolean", "description": "When true, this page qualifies as the thank-you page target." }, "button": { "type": "object", "description": "Customizes the button text for form navigation. When provided, label is required.", "properties": { "label": { "type": "string", "description": "The text displayed on the button (e.g., \"Start\", \"Next\", \"Submit\")." } }, "required": ["label"] } } }, "ImagePayload": { "type": "object", "title": "ImagePayload", "description": "Payload for IMAGE block type. Used for displaying images.", "properties": { "images": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": ["name", "url"], "properties": { "name": { "type": "string", "description": "The filename of the image." }, "url": { "type": "string", "format": "uri" } } } }, "hasCaption": { "type": "boolean", "description": "Set to true to enable caption; caption must be present if hasCaption is true." }, "caption": { "type": "string", "description": "The caption text to display below the image." }, "hasLink": { "type": "boolean", "description": "Set to true to enable link; link must be present if hasLink is true." }, "link": { "type": "string", "format": "uri", "description": "The URL to link to when the image is clicked." }, "hasAltText": { "type": "boolean", "description": "Set to true to enable alt text; altText must be present if hasAltText is true." }, "altText": { "type": "string", "description": "The alternative text for the image." }, "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "EmbedPayload": { "type": "object", "title": "EmbedPayload", "description": "Payload for EMBED block type. Used for embedding external content.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "type": { "type": "string", "enum": [ "rich", "video", "photo", "link", "pdf", "gist", "image/*", "video/*", "audio/*" ] }, "provider": { "$ref": "#/components/schemas/EmbedProvider" }, "title": { "type": "string" }, "inputUrl": { "type": "string", "format": "uri" }, "display": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } }, "width": { "oneOf": [{ "type": "string" }, { "type": "number" }] }, "height": { "oneOf": [{ "type": "string" }, { "type": "number" }] }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } }, "required": ["provider", "title", "inputUrl", "display", "type"] }, "EmbedVideoPayload": { "type": "object", "title": "EmbedVideoPayload", "description": "Payload for EMBED_VIDEO block type. Used for embedding video content.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "type": { "type": "string", "enum": ["video", "video/*"] }, "provider": { "$ref": "#/components/schemas/EmbedProvider" }, "title": { "type": "string" }, "inputUrl": { "$ref": "#/components/schemas/EmbedUrl" }, "display": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } }, "width": { "oneOf": [{ "type": "string" }, { "type": "number" }] }, "height": { "oneOf": [{ "type": "string" }, { "type": "number" }] }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } }, "required": ["provider", "title", "inputUrl", "display", "type"] }, "EmbedAudioPayload": { "type": "object", "title": "EmbedAudioPayload", "description": "Payload for EMBED_AUDIO block type. Used for embedding audio content.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "type": { "type": "string", "enum": ["audio/*"] }, "provider": { "$ref": "#/components/schemas/EmbedProvider" }, "title": { "type": "string" }, "inputUrl": { "$ref": "#/components/schemas/EmbedUrl" }, "display": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } }, "width": { "oneOf": [{ "type": "string" }, { "type": "number" }] }, "height": { "oneOf": [{ "type": "string" }, { "type": "number" }] }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } }, "required": ["provider", "title", "inputUrl", "display", "type"] }, "MatrixPayload": { "type": "object", "title": "MatrixPayload", "description": "Payload for MATRIX block type. Used for matrix/grid questions.", "properties": { "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "name": { "$ref": "#/components/schemas/Name" } } }, "InputTextPayload": { "type": "object", "title": "InputTextPayload", "description": "Payload for INPUT_TEXT block type. Used for short text input fields.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "placeholder": { "type": "string" }, "hasMinCharacters": { "$ref": "#/components/schemas/HasMinCharacters" }, "minCharacters": { "$ref": "#/components/schemas/MinCharacters" }, "hasMaxCharacters": { "$ref": "#/components/schemas/HasMaxCharacters" }, "maxCharacters": { "$ref": "#/components/schemas/MaxCharacters" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "InputNumberPayload": { "type": "object", "title": "InputNumberPayload", "description": "Payload for INPUT_NUMBER block type. Used for numeric input fields.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerNumber" }, "placeholder": { "type": "string" }, "hasMinNumber": { "type": "boolean", "description": "Set to true to enable minNumber; minNumber must be present if hasMinNumber is true." }, "minNumber": { "type": "number", "description": "The minimum allowed value (required if hasMinNumber is true)." }, "hasMaxNumber": { "type": "boolean", "description": "Set to true to enable maxNumber; maxNumber must be present if hasMaxNumber is true." }, "maxNumber": { "type": "number", "description": "The maximum allowed value (required if hasMaxNumber is true)." }, "decimalSeparator": { "$ref": "#/components/schemas/DecimalSeparator" }, "thousandsSeparator": { "$ref": "#/components/schemas/ThousandsSeparator" }, "format": { "$ref": "#/components/schemas/NumberFormat" }, "prefix": { "type": "string", "description": "Custom prefix to display before the number (e.g., currency symbol). Used with NumberFormat.Custom." }, "suffix": { "type": "string", "description": "Custom suffix to display after the number (e.g., unit). Used with NumberFormat.Custom." }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "InputEmailPayload": { "type": "object", "title": "InputEmailPayload", "description": "Payload for INPUT_EMAIL block type. Used for email input fields.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "requireVerification": { "type": "boolean", "description": "When true, respondents must verify their email address before submitting." }, "placeholder": { "type": "string" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "InputLinkPayload": { "type": "object", "title": "InputLinkPayload", "description": "Payload for INPUT_LINK block type. Used for URL input fields.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "placeholder": { "type": "string" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "InputPhoneNumberPayload": { "type": "object", "title": "InputPhoneNumberPayload", "description": "Payload for INPUT_PHONE_NUMBER block type. Used for phone number input fields.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "placeholder": { "type": "string" }, "internationalFormat": { "type": "boolean", "description": "When true, allows international phone numbers from any country. When false, restricts input to the default country." }, "defaultCountryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE') that sets the default country for the phone number input." }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "InputDatePayload": { "type": "object", "title": "InputDatePayload", "description": "Payload for INPUT_DATE block type. Used for date picker fields.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "placeholder": { "type": "string" }, "disableDays": { "type": "array", "description": "Array of days or date ranges to disable in the date picker.", "items": { "$ref": "#/components/schemas/DisableDays" } }, "format": { "type": "string", "description": "Display format for the date.", "enum": [ "MM/dd/yyyy", "dd/MM/yyyy", "yyyy/MM/dd", "dd.MM.yyyy", "yyyy-MM-dd" ] }, "beforeDate": { "type": "string", "format": "date", "description": "Disable dates before this date." }, "afterDate": { "type": "string", "format": "date", "description": "Disable dates after this date." }, "dateRange": { "type": "object", "description": "Restrict selectable dates to a specific range.", "properties": { "from": { "type": "string", "format": "date", "description": "Start date of the allowed range." }, "to": { "type": "string", "format": "date", "description": "End date of the allowed range." } } }, "specificDates": { "type": "array", "description": "Array of specific dates to disable.", "items": { "type": "string", "format": "date" } }, "startWeekOn": { "type": "string", "description": "Day the week starts on in the calendar view. 0=Sunday, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday.", "enum": ["0", "1", "2", "3", "4", "5", "6"] }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "InputTimePayload": { "type": "object", "title": "InputTimePayload", "description": "Payload for INPUT_TIME block type. Used for time picker fields.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "placeholder": { "type": "string" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "TextareaPayload": { "type": "object", "title": "TextareaPayload", "description": "Payload for TEXTAREA block type. Used for long text input fields.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "placeholder": { "type": "string" }, "hasMinCharacters": { "$ref": "#/components/schemas/HasMinCharacters" }, "minCharacters": { "$ref": "#/components/schemas/MinCharacters" }, "hasMaxCharacters": { "$ref": "#/components/schemas/HasMaxCharacters" }, "maxCharacters": { "$ref": "#/components/schemas/MaxCharacters" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "FileUploadPayload": { "type": "object", "title": "FileUploadPayload", "description": "Payload for FILE_UPLOAD block type. Used for file upload fields.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasMultipleFiles": { "type": "boolean", "description": "When true, allows uploading multiple files." }, "hasMinFiles": { "type": "boolean", "description": "Set to true to enable minFiles validation. When true, minFiles must be provided." }, "minFiles": { "type": "integer", "minimum": 1, "description": "Minimum number of files required. Required when hasMinFiles is true." }, "hasMaxFiles": { "type": "boolean", "description": "Set to true to enable maxFiles validation. When true, maxFiles must be provided." }, "maxFiles": { "type": "integer", "minimum": 1, "description": "Maximum number of files allowed. Required when hasMaxFiles is true." }, "hasMaxFileSize": { "type": "boolean", "description": "Set to true to enable maxFileSize validation. When true, maxFileSize and maxFileSizeUnit must be provided." }, "maxFileSize": { "type": "number", "minimum": 0, "description": "Maximum file size. Required when hasMaxFileSize is true." }, "maxFileSizeUnit": { "type": "string", "enum": ["KB", "MB", "GB"], "description": "Unit for maxFileSize. Required when hasMaxFileSize is true." }, "allowedFiles": { "$ref": "#/components/schemas/AllowedFiles" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "LinearScalePayload": { "type": "object", "title": "LinearScalePayload", "description": "Payload for LINEAR_SCALE block type. Used for scale/slider questions.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "type": "integer", "description": "Default selected value. Must be within the start-end range." }, "start": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Starting value of the scale (0-100). Defaults to 0." }, "end": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Ending value of the scale (0-100). Must be >= start. Defaults to 10." }, "step": { "type": "integer", "minimum": 1, "description": "Step increment between scale values. Must be >= 1. Defaults to 1." }, "hasLeftLabel": { "type": "boolean", "description": "When true, leftLabel must be provided." }, "leftLabel": { "type": "string", "description": "Label displayed at the start of the scale. Required when hasLeftLabel is true." }, "hasCenterLabel": { "type": "boolean", "description": "When true, centerLabel must be provided." }, "centerLabel": { "type": "string", "description": "Label displayed at the center of the scale. Required when hasCenterLabel is true." }, "hasRightLabel": { "type": "boolean", "description": "When true, rightLabel must be provided." }, "rightLabel": { "type": "string", "description": "Label displayed at the end of the scale. Required when hasRightLabel is true." }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "RatingPayload": { "type": "object", "title": "RatingPayload", "description": "Payload for RATING block type. Used for star rating questions.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerNumber" }, "stars": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of stars for the rating scale (1-10). Defaults to 5." }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "HiddenFieldsPayload": { "type": "object", "title": "HiddenFieldsPayload", "description": "Payload for HIDDEN_FIELDS block type. Used for hidden form fields.", "required": ["hiddenFields"], "properties": { "hiddenFields": { "type": "array", "description": "Array of hidden fields. Each hidden field captures a value from URL query parameters matching the field name.", "items": { "$ref": "#/components/schemas/HiddenField" } } } }, "MultipleChoiceOptionPayload": { "type": "object", "title": "MultipleChoiceOptionPayload", "description": "Payload for MULTIPLE_CHOICE_OPTION block type. Used for single-select radio questions.", "required": ["index", "isFirst", "isLast"], "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "index": { "$ref": "#/components/schemas/OptionIndex" }, "isFirst": { "$ref": "#/components/schemas/IsFirstOption" }, "isLast": { "$ref": "#/components/schemas/IsLastOption" }, "allowMultiple": { "$ref": "#/components/schemas/AllowMultiple" }, "hasMinChoices": { "$ref": "#/components/schemas/HasMinChoices" }, "minChoices": { "$ref": "#/components/schemas/MinChoices" }, "hasMaxChoices": { "$ref": "#/components/schemas/HasMaxChoices" }, "maxChoices": { "$ref": "#/components/schemas/MaxChoices" }, "colorCodeOptions": { "$ref": "#/components/schemas/ColorCodeOptions" }, "color": { "$ref": "#/components/schemas/OptionColor" }, "hasBadge": { "type": "boolean", "description": "Enable option badges (numbers or letters). Only needs to be set on the first option in the group." }, "badgeType": { "type": "string", "enum": ["OFF", "NUMBERS", "LETTERS"], "description": "Badge display type. Only needs to be set on the first option in the group." }, "hasOtherOption": { "type": "boolean", "description": "True if the question group has an 'Other' option enabled." }, "isOtherOption": { "type": "boolean", "description": "True if this specific option is the 'Other' free-text field." }, "randomize": { "type": "boolean", "description": "Randomize option order. Only needs to be set on the first option in the group." }, "lockInPlace": { "type": "array", "items": { "type": "string" }, "description": "Array of option UUIDs that should stay in their original position when randomize is enabled. Only needs to be set on the first option in the group." }, "image": { "type": "string", "description": "URL of an image to display alongside the option." }, "name": { "$ref": "#/components/schemas/Name" }, "text": { "type": "string", "description": "The display text of the option." }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "CheckboxPayload": { "type": "object", "title": "CheckboxPayload", "description": "Payload for CHECKBOX block type. Used for individual checkbox options within a checkbox group.", "required": ["index", "isFirst", "isLast"], "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "index": { "$ref": "#/components/schemas/OptionIndex" }, "isFirst": { "$ref": "#/components/schemas/IsFirstOption" }, "isLast": { "$ref": "#/components/schemas/IsLastOption" }, "image": { "type": "string", "format": "uri", "description": "URL of an image displayed alongside this checkbox option." }, "hasMinChoices": { "$ref": "#/components/schemas/HasMinChoices" }, "minChoices": { "$ref": "#/components/schemas/MinChoices" }, "hasMaxChoices": { "$ref": "#/components/schemas/HasMaxChoices" }, "maxChoices": { "$ref": "#/components/schemas/MaxChoices" }, "hasOtherOption": { "type": "boolean", "description": "True if the question group has an 'Other' option enabled." }, "isOtherOption": { "type": "boolean", "description": "True if this specific option is the 'Other' free-text field." }, "randomize": { "type": "boolean", "description": "Randomize option order. Only needs to be set on the first option in the group." }, "lockInPlace": { "type": "array", "items": { "type": "string" }, "description": "Array of option UUIDs that stay in their original position when randomize is enabled." }, "name": { "$ref": "#/components/schemas/Name" }, "text": { "type": "string", "description": "The display text of the checkbox option." }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "DropdownOptionPayload": { "type": "object", "title": "DropdownOptionPayload", "description": "Payload for DROPDOWN_OPTION block type. Used for dropdown select questions.", "required": ["index", "isFirst", "isLast"], "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "placeholder": { "type": "string" }, "index": { "$ref": "#/components/schemas/OptionIndex" }, "isFirst": { "$ref": "#/components/schemas/IsFirstOption" }, "isLast": { "$ref": "#/components/schemas/IsLastOption" }, "allowMultiple": { "$ref": "#/components/schemas/AllowMultiple" }, "hasMinChoices": { "$ref": "#/components/schemas/HasMinChoices" }, "minChoices": { "$ref": "#/components/schemas/MinChoices" }, "hasMaxChoices": { "$ref": "#/components/schemas/HasMaxChoices" }, "maxChoices": { "$ref": "#/components/schemas/MaxChoices" }, "hasOtherOption": { "type": "boolean", "description": "True if the question group has an 'Other' option enabled." }, "isOtherOption": { "type": "boolean", "description": "True if this specific option is the 'Other' free-text field." }, "randomize": { "type": "boolean", "description": "Randomize option order. Only needs to be set on the first option in the group." }, "lockInPlace": { "type": "array", "items": { "type": "string" }, "description": "Array of option UUIDs that should stay in their original position when randomize is enabled. Only needs to be set on the first option in the group." }, "name": { "$ref": "#/components/schemas/Name" }, "text": { "type": "string", "description": "The display text of the dropdown option." }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "RankingOptionPayload": { "type": "object", "title": "RankingOptionPayload", "description": "Payload for RANKING_OPTION block type. Used for ranking/ordering questions.", "required": ["index", "isFirst", "isLast"], "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "index": { "$ref": "#/components/schemas/OptionIndex" }, "isFirst": { "$ref": "#/components/schemas/IsFirstOption" }, "isLast": { "$ref": "#/components/schemas/IsLastOption" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" }, "html": { "$ref": "#/components/schemas/Html" }, "text": { "type": "string", "description": "The text of the ranking option." }, "image": { "type": "string", "description": "The image of the ranking option." }, "randomize": { "type": "boolean", "description": "Whether to randomize the ranking options. Only needs to be set on the first option in the group." }, "lockInPlace": { "type": "array", "items": { "type": "string" }, "description": "Array of option UUIDs that should stay in their original position when randomize is enabled. Only needs to be set on the first option in the group." } } }, "MultiSelectOptionPayload": { "type": "object", "title": "MultiSelectOptionPayload", "description": "Payload for MULTI_SELECT_OPTION block type. Used for multi-select checkbox questions.", "required": ["index", "isFirst", "isLast"], "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "hasDefaultAnswer": { "$ref": "#/components/schemas/HasDefaultAnswer" }, "defaultAnswer": { "$ref": "#/components/schemas/DefaultAnswerString" }, "index": { "$ref": "#/components/schemas/OptionIndex" }, "isFirst": { "$ref": "#/components/schemas/IsFirstOption" }, "isLast": { "$ref": "#/components/schemas/IsLastOption" }, "color": { "$ref": "#/components/schemas/OptionColor" }, "hasOtherOption": { "type": "boolean", "description": "True if the question group has an 'Other' option enabled." }, "isOtherOption": { "type": "boolean", "description": "True if this specific option is the 'Other' free-text field." }, "randomize": { "type": "boolean", "description": "Randomize option order. Only needs to be set on the first option in the group." }, "lockInPlace": { "type": "array", "items": { "type": "string" }, "description": "Array of option UUIDs that should stay in their original position when randomize is enabled. Only needs to be set on the first option in the group." }, "hasMinChoices": { "$ref": "#/components/schemas/HasMinChoices" }, "minChoices": { "$ref": "#/components/schemas/MinChoices" }, "hasMaxChoices": { "$ref": "#/components/schemas/HasMaxChoices" }, "maxChoices": { "$ref": "#/components/schemas/MaxChoices" }, "text": { "type": "string", "description": "Display text for this option." }, "placeholder": { "type": "string", "description": "Placeholder text for the 'Other' option input field." }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } } }, "PaymentPayload": { "type": "object", "title": "PaymentPayload", "description": "Payload for PAYMENT block type. Used for payment collection.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "amount": { "oneOf": [ { "type": "number", "minimum": 0, "description": "Fixed payment amount in the smallest currency unit (e.g., cents for USD)." }, { "$ref": "#/components/schemas/Field" } ], "description": "Payment amount. Can be a fixed number or a Field reference for dynamic pricing based on another form field's value." }, "currency": { "$ref": "#/components/schemas/Currency" }, "isConfigured": { "type": "boolean", "description": "True once the payment block is connected to a payment provider (e.g., Stripe)." }, "stateUuid": { "type": "string", "format": "uuid" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" } }, "required": ["isConfigured", "currency"] }, "SignaturePayload": { "type": "object", "title": "SignaturePayload", "description": "Payload for SIGNATURE block type. Used for signature collection.", "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" }, "name": { "$ref": "#/components/schemas/Name" }, "label": { "type": "string", "description": "Custom label text displayed below the signature pad." } } }, "MatrixRowPayload": { "type": "object", "title": "MatrixRowPayload", "description": "Payload for MATRIX_ROW block type. Used for matrix question rows.", "required": ["index", "isFirst", "isLast"], "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "index": { "$ref": "#/components/schemas/OptionIndex" }, "isFirst": { "$ref": "#/components/schemas/IsFirstOption" }, "isLast": { "$ref": "#/components/schemas/IsLastOption" }, "allowMultiple": { "type": "boolean", "description": "True if respondents can select multiple columns per row." }, "randomizeRows": { "type": "boolean", "description": "True if the matrix rows are shown in random order." }, "name": { "$ref": "#/components/schemas/Name" }, "html": { "$ref": "#/components/schemas/Html" }, "text": { "type": "string", "description": "Display text for this matrix row." } } }, "MatrixColumnPayload": { "type": "object", "title": "MatrixColumnPayload", "description": "Payload for MATRIX_COLUMN block type. Used for matrix question columns.", "required": ["index", "isFirst", "isLast"], "properties": { "isHidden": { "$ref": "#/components/schemas/IsHidden" }, "isRequired": { "$ref": "#/components/schemas/IsRequired" }, "index": { "$ref": "#/components/schemas/OptionIndex" }, "isFirst": { "$ref": "#/components/schemas/IsFirstOption" }, "isLast": { "$ref": "#/components/schemas/IsLastOption" }, "allowMultiple": { "type": "boolean", "description": "True if respondents can select multiple columns per row." }, "randomizeRows": { "type": "boolean", "description": "True if the matrix rows are shown in random order." }, "name": { "$ref": "#/components/schemas/Name" }, "html": { "$ref": "#/components/schemas/Html" }, "text": { "type": "string", "description": "Display text for this matrix column." } } }, "ConditionalLogicPayload": { "type": "object", "title": "ConditionalLogicPayload", "description": "Payload for CONDITIONAL_LOGIC block type. Used for form logic and branching.", "properties": { "conditionals": { "type": "array", "items": { "$ref": "#/components/schemas/Conditional" }, "description": "Conditions that must be satisfied before actions run." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionalAction" }, "description": "Actions executed when conditions are satisfied." }, "logicalOperator": { "type": "string", "enum": ["AND", "OR"], "description": "How to combine top-level conditions (AND/OR)." }, "updateUuid": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the logic block being updated; null when creating." } }, "required": ["actions", "conditionals", "logicalOperator"] }, "CalculatedFieldsPayload": { "type": "object", "title": "CalculatedFieldsPayload", "description": "Payload for CALCULATED_FIELDS block type. Used for computed/calculated values.", "properties": { "calculatedFields": { "type": "array", "items": { "$ref": "#/components/schemas/CalculatedField" } } }, "required": ["calculatedFields"] }, "CaptchaPayload": { "type": "object", "title": "CaptchaPayload", "description": "Payload for CAPTCHA block type. Used for bot protection.", "properties": { "columnListUuid": { "$ref": "#/components/schemas/ColumnListUuid" }, "columnUuid": { "$ref": "#/components/schemas/ColumnUuid" }, "columnRatio": { "$ref": "#/components/schemas/ColumnRatio" } } }, "RespondentCountryPayload": { "type": "object", "title": "RespondentCountryPayload", "description": "Payload for RESPONDENT_COUNTRY block type. Used for capturing respondent location.", "additionalProperties": false }, "ColumnRatio": { "type": "number", "minimum": 10, "maximum": 90, "description": "The width percentage of a column within a column layout row. Valid values range from 10 to 90, where the sum of all column ratios in a row should equal 100." }, "ColumnListUuid": { "type": "string", "format": "uuid", "description": "Groups blocks into a column layout row. Blocks sharing the same columnListUuid are displayed side-by-side." }, "ColumnUuid": { "type": "string", "format": "uuid", "description": "Identifies which column within a row this block belongs to. Blocks with the same columnUuid stack vertically within that column." }, "FormTitleBlock": { "type": "object", "title": "FormTitleBlock", "description": "A block with type FORM_TITLE. Used for the main form title with optional logo and cover image.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["FORM_TITLE"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["FORM_TITLE", "TEXT"] }, "payload": { "$ref": "#/components/schemas/FormTitlePayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "TitleBlock": { "type": "object", "title": "TitleBlock", "description": "A block with type TITLE. Used for section titles within the form.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["TITLE"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["TITLE", "QUESTION"] }, "payload": { "$ref": "#/components/schemas/TitlePayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "TextBlock": { "type": "object", "title": "TextBlock", "description": "A block with type TEXT. Used for rich text content within the form.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["TEXT"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["TEXT", "PAGE_BREAK", "DIVIDER"] }, "payload": { "$ref": "#/components/schemas/TextPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "LabelBlock": { "type": "object", "title": "LabelBlock", "description": "A block with type LABEL. Used for form field labels.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["LABEL"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["LABEL"] }, "payload": { "$ref": "#/components/schemas/LabelPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "Heading1Block": { "type": "object", "title": "Heading1Block", "description": "A block with type HEADING_1. Used for large headings.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["HEADING_1"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["HEADING_1"] }, "payload": { "$ref": "#/components/schemas/Heading1Payload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "Heading2Block": { "type": "object", "title": "Heading2Block", "description": "A block with type HEADING_2. Used for medium headings.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["HEADING_2"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["HEADING_2"] }, "payload": { "$ref": "#/components/schemas/Heading2Payload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "Heading3Block": { "type": "object", "title": "Heading3Block", "description": "A block with type HEADING_3. Used for small headings.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["HEADING_3"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["HEADING_3"] }, "payload": { "$ref": "#/components/schemas/Heading3Payload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "ImageBlock": { "type": "object", "title": "ImageBlock", "description": "A block with type IMAGE. Used for displaying images in the form.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["IMAGE"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["IMAGE"] }, "payload": { "$ref": "#/components/schemas/ImagePayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "EmbedBlock": { "type": "object", "title": "EmbedBlock", "description": "A block with type EMBED. Used for embedding external content.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["EMBED"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["EMBED"] }, "payload": { "$ref": "#/components/schemas/EmbedPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "EmbedVideoBlock": { "type": "object", "title": "EmbedVideoBlock", "description": "A block with type EMBED_VIDEO. Used for embedding video content.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["EMBED_VIDEO"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["EMBED_VIDEO"] }, "payload": { "$ref": "#/components/schemas/EmbedVideoPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "EmbedAudioBlock": { "type": "object", "title": "EmbedAudioBlock", "description": "A block with type EMBED_AUDIO. Used for embedding audio content.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["EMBED_AUDIO"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["EMBED_AUDIO"] }, "payload": { "$ref": "#/components/schemas/EmbedAudioPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "DividerBlock": { "type": "object", "title": "DividerBlock", "description": "A block with type DIVIDER. Used for visual separation between sections.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["DIVIDER"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["DIVIDER"] }, "payload": { "$ref": "#/components/schemas/DividerPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "PageBreakBlock": { "type": "object", "title": "PageBreakBlock", "description": "A block with type PAGE_BREAK. Used for creating multi-page forms.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["PAGE_BREAK"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["PAGE_BREAK"] }, "payload": { "$ref": "#/components/schemas/PageBreakPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "InputTextBlock": { "type": "object", "title": "InputTextBlock", "description": "A block with type INPUT_TEXT. Used for single-line text input.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["INPUT_TEXT"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["INPUT_TEXT"] }, "payload": { "$ref": "#/components/schemas/InputTextPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "TextareaBlock": { "type": "object", "title": "TextareaBlock", "description": "A block with type TEXTAREA. Used for multi-line text input.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["TEXTAREA"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["TEXTAREA"] }, "payload": { "$ref": "#/components/schemas/TextareaPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "InputNumberBlock": { "type": "object", "title": "InputNumberBlock", "description": "A block with type INPUT_NUMBER. Used for numeric input.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["INPUT_NUMBER"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["INPUT_NUMBER"] }, "payload": { "$ref": "#/components/schemas/InputNumberPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "InputEmailBlock": { "type": "object", "title": "InputEmailBlock", "description": "A block with type INPUT_EMAIL. Used for email address input.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["INPUT_EMAIL"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["INPUT_EMAIL"] }, "payload": { "$ref": "#/components/schemas/InputEmailPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "InputLinkBlock": { "type": "object", "title": "InputLinkBlock", "description": "A block with type INPUT_LINK. Used for URL input.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["INPUT_LINK"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["INPUT_LINK"] }, "payload": { "$ref": "#/components/schemas/InputLinkPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "InputPhoneNumberBlock": { "type": "object", "title": "InputPhoneNumberBlock", "description": "A block with type INPUT_PHONE_NUMBER. Used for phone number input.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["INPUT_PHONE_NUMBER"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["INPUT_PHONE_NUMBER"] }, "payload": { "$ref": "#/components/schemas/InputPhoneNumberPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "InputDateBlock": { "type": "object", "title": "InputDateBlock", "description": "A block with type INPUT_DATE. Used for date selection.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["INPUT_DATE"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["INPUT_DATE"] }, "payload": { "$ref": "#/components/schemas/InputDatePayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "InputTimeBlock": { "type": "object", "title": "InputTimeBlock", "description": "A block with type INPUT_TIME. Used for time selection.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["INPUT_TIME"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["INPUT_TIME"] }, "payload": { "$ref": "#/components/schemas/InputTimePayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "MultipleChoiceOptionBlock": { "type": "object", "title": "MultipleChoiceOptionBlock", "description": "A block with type MULTIPLE_CHOICE_OPTION. Individual option within a multiple choice question.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["MULTIPLE_CHOICE_OPTION"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["MULTIPLE_CHOICE"] }, "payload": { "$ref": "#/components/schemas/MultipleChoiceOptionPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "CheckboxBlock": { "type": "object", "title": "CheckboxBlock", "description": "A block with type CHECKBOX. Individual checkbox option within a checkboxes group.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["CHECKBOX"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["CHECKBOXES"] }, "payload": { "$ref": "#/components/schemas/CheckboxPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "DropdownOptionBlock": { "type": "object", "title": "DropdownOptionBlock", "description": "A block with type DROPDOWN_OPTION. Individual option within a dropdown.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["DROPDOWN_OPTION"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["DROPDOWN"] }, "payload": { "$ref": "#/components/schemas/DropdownOptionPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "RankingOptionBlock": { "type": "object", "title": "RankingOptionBlock", "description": "A block with type RANKING_OPTION. Individual option within a ranking question.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["RANKING_OPTION"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["RANKING"] }, "payload": { "$ref": "#/components/schemas/RankingOptionPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "MultiSelectOptionBlock": { "type": "object", "title": "MultiSelectOptionBlock", "description": "A block with type MULTI_SELECT_OPTION. Individual option within a multi-select dropdown.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["MULTI_SELECT_OPTION"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["MULTI_SELECT"] }, "payload": { "$ref": "#/components/schemas/MultiSelectOptionPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "LinearScaleBlock": { "type": "object", "title": "LinearScaleBlock", "description": "A block with type LINEAR_SCALE. Used for numeric scale ratings (e.g., 1-10).", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["LINEAR_SCALE"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["LINEAR_SCALE"] }, "payload": { "$ref": "#/components/schemas/LinearScalePayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "RatingBlock": { "type": "object", "title": "RatingBlock", "description": "A block with type RATING. Used for star/emoji ratings.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["RATING"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["RATING"] }, "payload": { "$ref": "#/components/schemas/RatingPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "MatrixBlock": { "type": "object", "title": "MatrixBlock", "description": "A block with type MATRIX. Container for matrix/grid questions.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["MATRIX"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["MATRIX"] }, "payload": { "$ref": "#/components/schemas/MatrixPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "MatrixRowBlock": { "type": "object", "title": "MatrixRowBlock", "description": "A block with type MATRIX_ROW. Row within a matrix question.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["MATRIX_ROW"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["MATRIX"] }, "payload": { "$ref": "#/components/schemas/MatrixRowPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "MatrixColumnBlock": { "type": "object", "title": "MatrixColumnBlock", "description": "A block with type MATRIX_COLUMN. Column within a matrix question.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["MATRIX_COLUMN"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["MATRIX"] }, "payload": { "$ref": "#/components/schemas/MatrixColumnPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "FileUploadBlock": { "type": "object", "title": "FileUploadBlock", "description": "A block with type FILE_UPLOAD. Used for file upload input.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["FILE_UPLOAD"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["FILE_UPLOAD"] }, "payload": { "$ref": "#/components/schemas/FileUploadPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "SignatureBlock": { "type": "object", "title": "SignatureBlock", "description": "A block with type SIGNATURE. Used for capturing signatures.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["SIGNATURE"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["SIGNATURE"] }, "payload": { "$ref": "#/components/schemas/SignaturePayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "PaymentBlock": { "type": "object", "title": "PaymentBlock", "description": "A block with type PAYMENT. Used for payment collection.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["PAYMENT"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["PAYMENT"] }, "payload": { "$ref": "#/components/schemas/PaymentPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "HiddenFieldsBlock": { "type": "object", "title": "HiddenFieldsBlock", "description": "A block with type HIDDEN_FIELDS. Used for hidden form fields.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["HIDDEN_FIELDS"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["HIDDEN_FIELDS"] }, "payload": { "$ref": "#/components/schemas/HiddenFieldsPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "ConditionalLogicBlock": { "type": "object", "title": "ConditionalLogicBlock", "description": "A block with type CONDITIONAL_LOGIC. Used for form branching logic.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["CONDITIONAL_LOGIC"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["CONDITIONAL_LOGIC"] }, "payload": { "$ref": "#/components/schemas/ConditionalLogicPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "CalculatedFieldsBlock": { "type": "object", "title": "CalculatedFieldsBlock", "description": "A block with type CALCULATED_FIELDS. Used for computed/calculated values.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["CALCULATED_FIELDS"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["CALCULATED_FIELDS"] }, "payload": { "$ref": "#/components/schemas/CalculatedFieldsPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "CaptchaBlock": { "type": "object", "title": "CaptchaBlock", "description": "A block with type CAPTCHA. Used for bot protection.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["CAPTCHA"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["CAPTCHA"] }, "payload": { "$ref": "#/components/schemas/CaptchaPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] }, "RespondentCountryBlock": { "type": "object", "title": "RespondentCountryBlock", "description": "A block with type RESPONDENT_COUNTRY. Used for capturing respondent location.", "properties": { "uuid": { "$ref": "#/components/schemas/BlockUuid" }, "type": { "type": "string", "enum": ["RESPONDENT_COUNTRY"] }, "groupUuid": { "$ref": "#/components/schemas/GroupUuid" }, "groupType": { "type": "string", "enum": ["RESPONDENT_COUNTRY"] }, "payload": { "$ref": "#/components/schemas/RespondentCountryPayload" } }, "required": ["uuid", "type", "groupUuid", "groupType", "payload"] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }