Beautiful Open-Source Form Builder
openapi: 3.0.1
info:
title: OpnForm API
description: API for interacting with OpnForm, primarily used for Zapier integration
version: 1.0.0
servers:
- url: https://api.opnform.com
security:
- bearerAuth: []
tags:
- name: Workspaces
description: Create and manage workspaces.
- name: Workspace Users
description: Manage users within a workspace.
- name: Forms
description: Manage and retrieve forms.
- name: Submissions
description: Access and manage form submissions.
- name: Integrations
description: Manage form integrations (webhooks) via API.
- name: Zapier
description: Legacy endpoints for the Zapier integration.
paths:
"/open/workspaces":
get:
tags:
- Workspaces
summary: List Workspaces
description: "Requires `workspaces-read`."
security:
- bearerAuth: []
responses:
"200":
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Workspace"
"403":
description: Forbidden
"/open/workspaces/create":
post:
tags:
- Workspaces
summary: Create Workspace
description: "Requires `workspaces-write`."
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
emoji:
type: string
description: Emoji or icon representing the workspace.
responses:
"200":
description: Created
content:
application/json:
schema:
type: object
properties:
message:
type: string
workspace_id:
type: number
workspace:
$ref: "#/components/schemas/Workspace"
"403":
description: Forbidden
"/open/workspaces/{workspaceId}":
put:
tags:
- Workspaces
summary: Update Workspace
description: "Update workspace name or icon. Requires `workspaces-write`."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: number
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Workspace"
responses:
"200":
description: Updated
content:
application/json:
schema:
$ref: "#/components/schemas/Workspace"
"403":
description: Forbidden
delete:
tags:
- Workspaces
summary: Delete Workspace
description: "Permanently delete a workspace. Requires `workspaces-write`."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: number
responses:
"204":
description: Deleted
"403":
description: Forbidden
"/open/workspaces/{workspaceId}/users":
get:
tags:
- Workspace Users
summary: List Workspace Users
description: "Requires `workspace-users-read`. Returns members with their role."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
responses:
"200":
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/UserWorkspaceMember"
"403":
description: Forbidden
"/open/workspaces/{workspaceId}/users/add":
post:
tags:
- Workspace Users
summary: Add Workspace User
description: "Requires `workspace-users-write`. Add an existing user or send an invite if the email is unknown. Self-hosted Community instances are limited to 2 users total across the instance; adding or inviting more users requires a self-hosted Enterprise license."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- role
properties:
email:
type: string
format: email
role:
type: string
enum: [admin, user, readonly]
responses:
"200":
description: User added
"403":
description: Forbidden, insufficient privileges, or self-hosted Community user limit reached
"/open/workspaces/{workspaceId}/users/{userId}/remove":
delete:
tags:
- Workspace Users
summary: Remove Workspace User
description: "Requires `workspace-users-write`. Removes a specified user from the workspace."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
- name: userId
in: path
required: true
schema:
type: string
responses:
"200":
description: User removed
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: User removed from workspace successfully.
"403":
description: Forbidden
"/open/workspaces/{workspaceId}/users/{userId}/update-role":
put:
tags:
- Workspace Users
summary: Update Workspace User Role
description: "Requires `workspace-users-write`. Update a member's role."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
- name: userId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- role
properties:
role:
type: string
enum: [admin, user, readonly]
description: New role for the user.
responses:
"200":
description: Role updated
"403":
description: Forbidden
"/open/workspaces/{workspaceId}/leave":
post:
tags:
- Workspace Users
summary: Leave Workspace
description: "Allows the current user to leave the workspace. Requires `workspace-users-write`."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
responses:
"204":
description: Left workspace
"403":
description: Forbidden
"/open/workspaces/{workspaceId}/invites":
get:
tags:
- Workspace Users
summary: List Workspace Invites
description: "Requires workspace admin access. Personal Access Tokens must include `workspaces-write` and belong to a workspace admin. Lists pending & accepted invites."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
responses:
"200":
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Invite"
"403":
description: Forbidden
"/open/workspaces/{workspaceId}/invites/{inviteId}/resend":
post:
tags:
- Workspace Users
summary: Resend Workspace Invite
description: "Requires `workspace-users-write`. Resend the invitation email for a pending invite."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
- name: inviteId
in: path
required: true
schema:
type: string
responses:
"200":
description: Invite resent
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Invite email resent successfully.
"403":
description: Forbidden
"/open/workspaces/{workspaceId}/invites/{inviteId}/cancel":
delete:
tags:
- Workspace Users
summary: Cancel Workspace Invite
description: "Requires `workspace-users-write`. Delete a pending invite."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
- name: inviteId
in: path
required: true
schema:
type: string
responses:
"200":
description: Invite canceled
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Invite deleted successfully.
"403":
description: Forbidden
"/open/workspaces/{workspaceId}/forms":
get:
tags:
- Forms
summary: List Workspace Forms
description: "Retrieve all forms within a specific workspace. Returns lightweight form summaries (excludes `properties`). Use the Get Form endpoint to retrieve the full form with all fields. Requires `forms-read` ability."
security:
- bearerAuth: []
parameters:
- name: workspaceId
in: path
required: true
schema:
type: number
description: ID of the workspace to retrieve forms from.
- name: page
in: query
required: false
schema:
type: number
minimum: 1
default: 1
description: "Pagination page number"
- name: per_page
in: query
required: false
schema:
type: number
minimum: 1
maximum: 100
default: 10
description: "Number of forms per page"
responses:
"200":
description: Successful
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/FormListItem"
links:
type: object
properties:
first:
type: string
last:
type: string
prev:
type: string
nullable: true
next:
type: string
nullable: true
meta:
type: object
properties:
current_page:
type: number
from:
type: number
last_page:
type: number
per_page:
type: number
to:
type: number
total:
type: number
"403":
description: "Forbidden – token lacks forms-read ability or you do not have access to the workspace"
"404":
description: "Workspace not found"
"/open/forms":
get:
tags:
- Forms
summary: List Forms
description: "Retrieve all forms accessible to the token holder across all workspaces. Returns lightweight form summaries (excludes `properties`). **Deprecated**: Use `/open/workspaces/{workspaceId}/forms` instead."
deprecated: true
security:
- bearerAuth: []
responses:
"200":
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/FormListItem"
"403":
description: Forbidden – token lacks forms-read ability
post:
tags:
- Forms
summary: Create Form
description: "Create a new form; requires forms-write ability."
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Form"
responses:
"201":
description: Form created
content:
application/json:
schema:
$ref: "#/components/schemas/Form"
"403":
description: Forbidden – token lacks forms-write ability
"/open/forms/{slug}":
get:
tags:
- Forms
summary: Get Form
description: Retrieve a single form.
security:
- bearerAuth: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
responses:
"200":
description: Successful
content:
application/json:
schema:
$ref: "#/components/schemas/Form"
"404":
description: Not Found
"403":
description: Forbidden
"/open/forms/{id}":
put:
tags:
- Forms
summary: Update Form
description: "Update an existing form. Requires `forms-write`."
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: number
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Form"
responses:
"200":
description: Updated
content:
application/json:
schema:
$ref: "#/components/schemas/Form"
"403":
description: Forbidden – token lacks forms-write ability
delete:
tags:
- Forms
summary: Delete Form
description: "Delete a form. Requires `forms-write`."
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: number
responses:
"204":
description: Deleted
"403":
description: Forbidden
"/forms/{slug}/answer":
post:
tags:
- Submissions
summary: Create Submission
description: "Create a new submission for a form. Public endpoint - no authentication required."
security: []
parameters:
- name: slug
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
completion_time:
type: number
description: "Time in seconds it took to complete the form"
is_partial:
type: boolean
description: "If you want to submit your form as partial"
tracking_parameters:
$ref: "#/components/schemas/SubmissionAttribution"
responses:
"200":
description: "Form submission saved successfully"
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: "success"
message:
type: string
example: "Form submission saved."
submission_id:
type: string
nullable: true
is_first_submission:
type: boolean
redirect:
type: boolean
"422":
description: "Validation error"
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "The Name field is required."
errors:
type: object
additionalProperties:
type: array
items:
type: string
"404":
description: "Form not found"
"/open/forms/{id}/submissions":
get:
tags:
- Submissions
summary: List Submissions
description: "Requires `forms-read`. Supports pagination, search, and status filtering."
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: number
- name: page
in: query
required: false
schema:
type: number
minimum: 1
default: 1
description: "Pagination page number"
- name: per_page
in: query
required: false
schema:
type: number
minimum: 1
maximum: 100
default: 100
description: "Number of results per page"
- name: search
in: query
required: false
schema:
type: string
description: "Search term to filter submissions by field values"
- name: status
in: query
required: false
schema:
type: string
enum: [completed, partial, all]
default: all
description: "Filter by submission status"
responses:
"200":
description: Successful
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Submission"
links:
type: object
properties:
first:
type: string
last:
type: string
prev:
type: string
nullable: true
next:
type: string
nullable: true
meta:
type: object
properties:
current_page:
type: number
from:
type: number
last_page:
type: number
per_page:
type: number
to:
type: number
total:
type: number
"403":
description: "Forbidden – token lacks forms-read ability"
"/open/forms/{id}/submissions/export":
post:
tags:
- Submissions
summary: Export Submissions (CSV)
description: "Export submissions as CSV. Large exports are processed asynchronously. Requires `forms-read`."
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: number
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- columns
properties:
columns:
type: object
additionalProperties:
type: boolean
description: "Object mapping field IDs, system columns, or namespaced attribution columns (for example meta.attribution.utm_source) to booleans."
responses:
"200":
description: "Synchronous export (CSV file) or asynchronous export (job status)"
content:
application/json:
schema:
oneOf:
- type: string
format: binary
description: "CSV file download for small forms"
- type: object
description: "Job status for large forms"
properties:
message:
type: string
example: "Export started. Large export will be processed in the background."
job_id:
type: string
example: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
is_async:
type: boolean
example: true
"403":
description: Forbidden
"/open/forms/{id}/submissions/export/status/{job_id}":
get:
tags:
- Submissions
summary: Check Export Status
description: "Check the status of an asynchronous export job. Requires `forms-read`."
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: number
- name: job_id
in: path
required: true
schema:
type: string
description: "Export job identifier"
responses:
"200":
description: Export job status
content:
application/json:
schema:
$ref: "#/components/schemas/ExportJobStatus"
"404":
description: "Export job not found, has expired, or belongs to another form"
"403":
description: Forbidden
"/open/forms/{id}/submissions/{submission_id}":
put:
tags:
- Submissions
summary: Update Submission
description: "Update a submission. Requires `forms-write` ability."
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: number
- name: submission_id
in: path
required: true
schema:
type: number
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Submission"
responses:
"200":
description: Updated
content:
application/json:
schema:
$ref: "#/components/schemas/Submission"
"403":
description: "Forbidden – token lacks forms-write ability"
delete:
tags:
- Submissions
summary: Delete Submission
description: "Requires `forms-write`."
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: number
description: The ID of the form.
- name: submission_id
in: path
required: true
schema:
type: number
description: The ID of the submission to delete.
responses:
"200":
description: Successful
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Record successfully removed.
"403":
description: "Forbidden – token lacks forms-write ability"
"/open/forms/{form}/integrations":
get:
tags:
- Integrations
summary: List Form Integrations
description: "List all integrations configured for a form. Requires `manage-integrations` ability."
security:
- bearerAuth: []
parameters:
- name: form
in: path
required: true
schema:
type: number
description: The ID of the form.
responses:
"200":
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/FormIntegration"
"403":
description: Forbidden – token lacks manage-integrations ability
"404":
description: Form not found
post:
tags:
- Integrations
summary: Create Webhook Integration
description: "Create a new generic webhook or provider-specific Make integration for a form. Requires `manage-integrations` ability."
security:
- bearerAuth: []
parameters:
- name: form
in: path
required: true
schema:
type: number
description: The ID of the form.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- integration_id
- data
properties:
integration_id:
type: string
enum: [webhook, make]
description: Use "webhook" for a generic webhook or "make" for the official OpnForm app on Make
status:
type: string
enum: [active, inactive]
default: active
description: The initial status of the webhook
data:
type: object
required:
- webhook_url
properties:
webhook_url:
type: string
format: uri
description: The URL where submissions will be sent
provider_url:
type: string
format: uri
nullable: true
description: Optional Make scenario URL stored with a Make integration
responses:
"200":
description: Webhook created successfully
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Form Integration was created."
form_integration:
$ref: "#/components/schemas/FormIntegration"
"403":
description: Forbidden – insufficient permissions
"404":
description: Form not found
"422":
description: Validation error
"/open/forms/{form}/integrations/{integrationid}":
put:
tags:
- Integrations
summary: Update Webhook Integration
description: "Update an existing webhook integration. Requires `manage-integrations` ability."
security:
- bearerAuth: []
parameters:
- name: form
in: path
required: true
schema:
type: number
description: The ID of the form.
- name: integrationid
in: path
required: true
schema:
type: number
description: The ID of the integration.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- integration_id
- data
properties:
integration_id:
type: string
enum: [webhook]
description: Must be "webhook"
status:
type: string
enum: [active, inactive]
description: The status of the webhook
data:
type: object
required:
- webhook_url
properties:
webhook_url:
type: string
format: uri
description: The URL where submissions will be sent
responses:
"200":
description: Webhook updated successfully
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Form Integration was updated."
form_integration:
$ref: "#/components/schemas/FormIntegration"
"403":
description: Forbidden – insufficient permissions
"404":
description: Form or integration not found
"422":
description: Validation error
delete:
tags:
- Integrations
summary: Delete Webhook Integration
description: "Delete a webhook integration. Requires `manage-integrations` ability."
security:
- bearerAuth: []
parameters:
- name: form
in: path
required: true
schema:
type: number
description: The ID of the form.
- name: integrationid
in: path
required: true
schema:
type: number
description: The ID of the integration.
responses:
"200":
description: Webhook deleted successfully
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Form Integration was deleted."
"403":
description: Forbidden – insufficient permissions
"404":
description: Form or integration not found
"/open/forms/{form}/integrations/{integrationid}/events":
get:
tags:
- Integrations
summary: List Webhook Events
description: "List past webhook dispatch events for an integration. Requires `manage-integrations` ability."
security:
- bearerAuth: []
parameters:
- name: form
in: path
required: true
schema:
type: number
description: The ID of the form.
- name: integrationid
in: path
required: true
schema:
type: number
description: The ID of the integration.
responses:
"200":
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/IntegrationEvent"
"403":
description: Forbidden – insufficient permissions
"404":
description: Form or integration not found
"/open/forms/{form}/integrations/{integrationid}/events/{event}/retry":
post:
tags:
- Integrations
summary: Retry an Integration Event
description: "Retry the latest eligible failed event with current settings and saved submission data. Requires manage-integrations and workspace write access. Limited to 10 requests per minute per user."
security:
- bearerAuth: []
parameters:
- name: form
in: path
required: true
schema:
type: integer
- name: integrationid
in: path
required: true
schema:
type: integer
- name: event
in: path
required: true
schema:
type: integer
responses:
"200":
description: Attempt completed. Inspect type and event.status for its delivery outcome.
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum: [success, error, warning]
message:
type: string
event:
$ref: "#/components/schemas/IntegrationEvent"
"401":
description: Authentication required
"403":
description: Insufficient permissions
"404":
description: Form, integration, or event not found in the requested scope
"422":
description: Event is no longer eligible for retry
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: object
properties:
event:
type: array
items:
type: string
"429":
description: Too many retry requests; wait for Retry-After
"/external/zapier/validate":
get:
tags:
- Zapier
summary: Validate API Key
description: This endpoint is used by Zapier to test the validity of the API key.
responses:
"200":
description: API key is valid
"401":
description: Invalid API key
"/external/zapier/forms":
get:
tags:
- Zapier
summary: List Forms
description: Retrieve a list of forms available in a specific workspace.
parameters:
- name: workspace_id
in: query
description: The ID of the workspace for which to list forms
required: true
schema:
type: number
responses:
"200":
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Form"
"/external/zapier/webhook":
post:
tags:
- Zapier
summary: New Submission Trigger
description: This endpoint is used to set up a webhook for new form submissions.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
hookUrl:
type: string
description: The URL provided by Zapier to send the submission data
form_id:
type: number
description: The ID of the form for which to trigger the webhook
required:
- hookUrl
- form_id
responses:
"200":
description: Webhook successfully set up
delete:
tags:
- Zapier
summary: Unsubscribe Webhook
description: This endpoint is used to unsubscribe from the webhook.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
hookUrl:
type: string
description: The URL provided by Zapier to stop sending the submission data
form_id:
type: number
description: The ID of the form for which to unsubscribe the webhook
required:
- hookUrl
- form_id
responses:
"200":
description: Webhook successfully unsubscribed
"/external/zapier/submissions/recent":
get:
tags:
- Zapier
summary: Sample Submission Polling
description: Retrieves the most recent submissions for a specified form.
parameters:
- name: form_id
in: query
description: The ID of the form to retrieve submissions for
required: true
schema:
type: number
responses:
"200":
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Submission"
"/users/{userId}":
get:
tags:
- Zapier
responses:
"200":
description: "Successful"
components:
schemas:
Workspace:
type: object
properties:
id:
type: number
description: The unique identifier for the workspace.
example: 1
readOnly: true
name:
type: string
description: The name of the workspace.
example: "My Marketing Team"
icon:
type: string
description: The emoji or icon representing the workspace.
example: "🚀"
settings:
type: object
description: General settings for the workspace.
Form:
type: object
properties:
# Core form identification
id:
type: number
description: The unique identifier for the form.
readOnly: true
slug:
type: string
description: The URL-friendly slug for the form.
readOnly: true
workspace_id:
type: number
description: ID of the workspace that owns the form.
writeOnly: true
title:
type: string
description: The title of the form.
visibility:
type: string
enum: [public, draft, closed]
description: The current visibility state of the form.
tags:
type: array
items:
type: string
nullable: true
language:
type: string
description: Two-letter ISO language code.
custom_domain:
type: string
nullable: true
# Visual appearance and styling
theme:
type: string
enum: [default, simple, notion]
font_family:
type: string
nullable: true
color:
type: string
dark_mode:
type: string
enum: [light, dark, auto]
width:
type: string
enum: [centered, full]
size:
type: string
enum: [sm, md, lg]
border_radius:
type: string
enum: [none, small, full]
layout_rtl:
type: boolean
uppercase_labels:
type: boolean
# Media and branding
cover_picture:
type: string
format: uri
nullable: true
logo_picture:
type: string
format: uri
nullable: true
no_branding:
type: boolean
description: Whether to hide the OpnForm branding.
transparent_background:
type: boolean
description: Transparent background when form is embedded.
# Form behavior and submission settings
submit_button_text:
type: string
maxLength: 50
submitted_text:
type: string
maxLength: 2000
redirect_url:
type: string
format: uri
nullable: true
re_fillable:
type: boolean
re_fill_button_text:
type: string
maxLength: 50
confetti_on_submission:
type: boolean
show_progress_bar:
type: boolean
submission_retention_value:
type: integer
minimum: 1
maximum: 3650
nullable: true
description: Number of retention units before a submission is permanently deleted. Set this and submission_retention_unit to null to disable automatic deletion.
submission_retention_unit:
type: string
enum: [day, week, month, year]
nullable: true
description: Calendar unit used by submission_retention_value. Both retention fields must be provided together.
# Form closure and limits
closes_at:
type: string
format: date-time
nullable: true
closed_text:
type: string
nullable: true
max_submissions_count:
type: integer
minimum: 1
nullable: true
max_submissions_reached_text:
type: string
nullable: true
# User experience features
auto_save:
type: boolean
auto_focus:
type: boolean
enable_partial_submissions:
type: boolean
editable_submissions:
type: boolean
editable_submissions_button_text:
type: string
maxLength: 50
# Security and validation
password:
type: string
nullable: true
use_captcha:
type: boolean
captcha_provider:
type: string
enum: [recaptcha, hcaptcha]
# SEO and indexing
can_be_indexed:
type: boolean
seo_meta:
type: object
nullable: true
description: Custom page title (page_title), description (page_description), link preview image (page_thumbnail), and favicon (page_favicon). Published on cloud Pro and higher plans, on both OpnForm URLs and custom domains.
# Advanced features
custom_code:
type: string
nullable: true
database_fields_update:
type: array
items: {}
nullable: true
properties:
type: array
description: An array of field and layout blocks that make up the form.
items:
$ref: "#/components/schemas/FormProperty"
FormListItem:
type: object
description: A lightweight form summary returned by list endpoints. Use the Get Form endpoint to retrieve full form details including properties.
properties:
id:
type: number
description: The unique identifier for the form.
readOnly: true
slug:
type: string
description: The URL-friendly slug for the form.
readOnly: true
title:
type: string
description: The title of the form.
visibility:
type: string
enum: [public, draft, closed]
description: The current visibility state of the form.
tags:
type: array
items:
type: string
nullable: true
views_count:
type: number
description: Total number of form views.
submissions_count:
type: number
description: Total number of completed submissions.
created_at:
type: string
format: date-time
description: ISO 8601 timestamp of when the form was created.
updated_at:
type: string
format: date-time
description: ISO 8601 timestamp of when the form was last modified.
last_edited_human:
type: string
description: Human-readable time since last edit (e.g., "2 hours ago").
closes_at:
type: string
format: date-time
nullable: true
description: When the form will close for submissions.
is_closed:
type: boolean
description: Whether the form is currently closed.
max_submissions_count:
type: integer
minimum: 1
nullable: true
description: Maximum number of submissions allowed.
max_number_of_submissions_reached:
type: boolean
description: Whether the submission limit has been reached.
is_pro:
type: boolean
description: Whether the form's workspace has a Pro subscription.
workspace_id:
type: number
description: ID of the workspace that owns the form.
share_url:
type: string
format: uri
description: Public URL to share the form.
FormProperty:
type: object
description: A single field or layout block within a form.
properties:
id:
type: string
description: A unique identifier for the block.
format: uuid
type:
type: string
description: The type of block.
name:
type: string
description: The label or name of the field.
help:
type: string
description: "Help text displayed with the field."
hidden:
type: boolean
description: Whether the field is hidden from view.
required:
type: boolean
description: "Whether the field is required."
placeholder:
type: string
description: Placeholder text for the input.
width:
type: string
enum: [full, "1/2", "1/3", "2/3", "1/4", "3/4"]
description: The width of the block in the form layout.
additionalProperties: true
Submission:
type: object
properties:
id:
type: number
description: "Unique submission ID"
readOnly: true
form_id:
type: number
description: "ID of the parent form"
readOnly: true
completion_time:
type: number
nullable: true
description: "Time taken to complete the form in seconds"
readOnly: true
data:
type: object
description: "Contains form field responses plus metadata (status, created_at, id)"
additionalProperties: true
readOnly: true
meta:
type: object
readOnly: true
properties:
attribution:
$ref: "#/components/schemas/SubmissionAttribution"
SubmissionAttribution:
type: object
description: "Allowlisted campaign attribution. Values are strings with a maximum length of 2,048 characters."
additionalProperties: false
properties:
utm_source: { type: string, maxLength: 2048 }
utm_medium: { type: string, maxLength: 2048 }
utm_campaign: { type: string, maxLength: 2048 }
utm_id: { type: string, maxLength: 2048 }
utm_term: { type: string, maxLength: 2048 }
utm_content: { type: string, maxLength: 2048 }
utm_source_platform: { type: string, maxLength: 2048 }
utm_creative_format: { type: string, maxLength: 2048 }
utm_marketing_tactic: { type: string, maxLength: 2048 }
gclid: { type: string, maxLength: 2048 }
gbraid: { type: string, maxLength: 2048 }
wbraid: { type: string, maxLength: 2048 }
dclid: { type: string, maxLength: 2048 }
fbclid: { type: string, maxLength: 2048 }
ttclid: { type: string, maxLength: 2048 }
msclkid: { type: string, maxLength: 2048 }
UserWorkspaceMember:
type: object
properties:
id:
type: number
name:
type: string
email:
type: string
format: email
role:
type: string
description: Role of the user inside the workspace (admin, member, viewer).
Invite:
type: object
properties:
id:
type: number
email:
type: string
format: email
role:
type: string
enum: [admin, user, readonly]
status:
type: string
enum: [pending, accepted]
valid_until:
type: string
format: date-time
description: Expiration timestamp for the invite
ExportJobStatus:
type: object
properties:
status:
type: string
enum: [queued, processing, completed, failed]
description: "Current status of the export job"
progress:
type: number
minimum: 0
maximum: 100
description: "Completion percentage (0-100)"
job_id:
type: string
description: "Export job identifier"
processed_submissions:
type: number
description: "Number of submissions processed so far"
nullable: true
total_submissions:
type: number
description: "Total number of submissions to process"
nullable: true
file_url:
type: string
format: uri
description: "Download URL for completed exports"
nullable: true
expires_at:
type: string
format: date-time
description: "File expiration timestamp (workspace policy, 24 hours by default)"
nullable: true
error_message:
type: string
description: "Error description for failed exports"
nullable: true
created_at:
type: string
format: date-time
description: "Job creation timestamp"
updated_at:
type: string
format: date-time
description: "Last update timestamp"
FormIntegration:
type: object
properties:
id:
type: number
description: Unique identifier for the integration.
readOnly: true
form_id:
type: number
description: The ID of the associated form.
readOnly: true
integration_id:
type: string
description: Type of integration exposed via API, including "webhook" and the provider-specific "make" integration.
example: "webhook"
status:
type: string
enum: [active, inactive]
description: Whether the integration is active.
data:
type: object
description: Integration-specific configuration. For webhooks, contains webhook_url.
example:
webhook_url: "https://example.com/opnform-hook"
IntegrationEvent:
type: object
properties:
id:
type: integer
readOnly: true
date:
type: string
description: Event date formatted as YYYY-MM-DD HH:mm.
status:
type: string
enum: [Success, Error, Skipped, Processing, Accepted, Delivered, Unknown]
tracking_id:
type: string
nullable: true
email_tracking:
type: boolean
legacy_email:
type: boolean
updated_at:
type: string
format: date-time
nullable: true
data:
type: object
nullable: true
additionalProperties: true
description: Submission ID, failure details, or email recipient outcomes.
can_retry:
type: boolean
description: Whether this is the latest eligible failed attempt for an available completed submission.
retry_unavailable_reason:
type: string
nullable: true
description: Why retry is unavailable; null when eligible.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: "Personal Access Token"
x-bearer-scopemap:
"workspaces-read": "Read access to workspaces"
"workspaces-write": "Write access to workspaces"
"workspace-users-read": "Read access to workspace users"
"workspace-users-write": "Write access to workspace users"
"forms-read": "Read access to forms"
"forms-write": "Write access to forms"
"manage-integrations": "Manage form integrations (webhooks)"