REST API for managing FormAssembly forms, responses, themes, connectors, and account data. Supports JSON, XML, CSV, and ZIP response formats. OAuth2 authentication is required for all requests. Endpoints vary by deployment edition including Developer Sandbox, FormAssembly.com cloud, and self-hosted Enterprise instances.
openapi: 3.0.3
info:
title: FormAssembly REST API
description: >
REST API for managing FormAssembly forms, responses, themes, connectors,
form elements, and account data. Supports JSON, XML, CSV, and ZIP response
formats. OAuth2 authentication is required for all requests. Endpoints vary
by deployment edition including Developer Sandbox, FormAssembly.com cloud,
and self-hosted Enterprise instances.
version: 1.0.0
contact:
name: FormAssembly Developer Hub
url: https://help.formassembly.com/help/working-with-the-formassembly-api
termsOfService: https://www.formassembly.com/terms-of-service/
license:
name: Proprietary
servers:
- url: https://app.formassembly.com
description: FormAssembly.com Cloud
- url: https://developer.formassembly.com
description: Developer Sandbox
- url: https://{instance_name}.tfaforms.net
description: Enterprise / Teams / Government Instance
variables:
instance_name:
default: yourinstance
description: Your FormAssembly enterprise instance name
security:
- oauth2: []
components:
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.formassembly.com/oauth/login
tokenUrl: https://app.formassembly.com/oauth/access_token
scopes: {}
parameters:
formatJson:
name: format
in: path
description: Response format (json or xml)
required: true
schema:
type: string
enum: [json, xml]
default: json
formId:
name: formId
in: path
description: Unique identifier of the form
required: true
schema:
type: integer
connectorId:
name: connectorId
in: path
description: Unique identifier of the connector
required: true
schema:
type: integer
themeId:
name: themeId
in: path
description: Unique identifier of the theme
required: true
schema:
type: integer
elementId:
name: elementId
in: path
description: Unique identifier of the form element
required: true
schema:
type: integer
connectorName:
name: connectorName
in: path
description: Name of the connector type to create
required: true
schema:
type: string
schemas:
Form:
type: object
properties:
id:
type: integer
description: Unique identifier of the form
name:
type: string
description: Display name of the form
language:
type: string
description: Language code of the form
builder_version:
type: string
description: Version of the form builder used
xml_data:
type: string
description: XML definition of the form structure
required:
- id
- name
FormList:
type: object
properties:
forms:
type: array
items:
$ref: '#/components/schemas/Form'
Response:
type: object
properties:
id:
type: integer
description: Unique identifier of the response
form_id:
type: integer
description: ID of the form this response belongs to
date_created:
type: string
format: date-time
description: Timestamp when the response was submitted
flag:
type: integer
description: Flag status of the response
Connector:
type: object
properties:
id:
type: integer
description: Unique identifier of the connector
form_id:
type: integer
description: ID of the form this connector is attached to
name:
type: string
description: Name/type of the connector
event:
type: string
enum: [beforerender, before_save, interactive, background]
description: Trigger event for the connector
mapping:
type: string
description: Field mapping configuration
login:
type: string
description: Login credential for connector
password:
type: string
description: Password credential for connector
Theme:
type: object
properties:
id:
type: integer
description: Unique identifier of the theme
name:
type: string
description: Display name of the theme
css_data:
type: string
description: CSS stylesheet content of the theme
ThemeList:
type: object
properties:
themes:
type: array
items:
$ref: '#/components/schemas/Theme'
FormElement:
type: object
properties:
id:
type: integer
description: Unique identifier of the form element
name:
type: string
description: Display name of the element
comments:
type: string
description: Notes or comments about the element
category:
type: string
description: Category the element belongs to
subcategory:
type: string
description: Subcategory of the element
xml_data:
type: string
description: XML definition of the element
batch:
type: string
description: Batch identifier for bulk operations
SuccessResponse:
type: object
properties:
status:
type: string
enum: [success]
message:
type: string
ErrorResponse:
type: object
properties:
status:
type: string
enum: [error]
message:
type: string
paths:
# ─── OAuth2 ────────────────────────────────────────────────────────────────
/oauth/login:
get:
operationId: initiateOAuth2Login
summary: Initiate OAuth2 authorization
description: Redirect users here to begin the OAuth2 authorization code flow.
tags:
- OAuth2
parameters:
- name: type
in: query
required: true
schema:
type: string
enum: [web]
- name: client_id
in: query
required: true
schema:
type: string
description: Your registered OAuth2 client ID
- name: redirect_uri
in: query
required: true
schema:
type: string
format: uri
description: Callback URI registered with your application
- name: response_type
in: query
required: true
schema:
type: string
enum: [code]
responses:
'302':
description: Redirect to FormAssembly login page
security: []
/oauth/access_token:
post:
operationId: requestAccessToken
summary: Exchange authorization code for access token
description: Exchange the authorization code received after login for an OAuth2 access token.
tags:
- OAuth2
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- grant_type
- type
- client_id
- client_secret
- redirect_uri
- code
properties:
grant_type:
type: string
enum: [authorization_code]
type:
type: string
enum: [web_server]
client_id:
type: string
client_secret:
type: string
redirect_uri:
type: string
format: uri
code:
type: string
description: Authorization code from callback
responses:
'200':
description: Access token issued
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
expires_in:
type: integer
scope:
type: string
refresh_token:
type: string
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security: []
# ─── Forms ─────────────────────────────────────────────────────────────────
/api_v1/forms/index.{format}:
get:
operationId: listForms
summary: List user's forms
description: Returns a list of all forms belonging to the authenticated user.
tags:
- Forms
parameters:
- $ref: '#/components/parameters/formatJson'
responses:
'200':
description: List of forms
content:
application/json:
schema:
$ref: '#/components/schemas/FormList'
application/xml:
schema:
$ref: '#/components/schemas/FormList'
/admin/api_v1/forms/index.{format}:
get:
operationId: adminListForms
summary: List all forms (Admin)
description: Admin-only endpoint that returns all forms across all users in the account.
tags:
- Forms
- Admin
parameters:
- $ref: '#/components/parameters/formatJson'
responses:
'200':
description: List of all forms
content:
application/json:
schema:
$ref: '#/components/schemas/FormList'
application/xml:
schema:
$ref: '#/components/schemas/FormList'
/api_v1/forms/view/{formId}.{format}:
get:
operationId: getForm
summary: View form definition
description: Returns the full definition of a specific form including its XML structure.
tags:
- Forms
parameters:
- $ref: '#/components/parameters/formId'
- $ref: '#/components/parameters/formatJson'
responses:
'200':
description: Form definition
content:
application/json:
schema:
$ref: '#/components/schemas/Form'
application/xml:
schema:
$ref: '#/components/schemas/Form'
'404':
description: Form not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api_v1/forms/create.{format}:
post:
operationId: createForm
summary: Create a new form
description: Creates a new form with the provided XML definition and metadata.
tags:
- Forms
parameters:
- $ref: '#/components/parameters/formatJson'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
xml_data:
type: string
description: XML definition of the form structure
builder_version:
type: string
description: Version of the form builder
language:
type: string
description: Language code (e.g., en_US)
name:
type: string
description: Display name for the form
responses:
'200':
description: Form created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Form'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api_v1/forms/edit/{formId}.{format}:
post:
operationId: updateForm
summary: Update an existing form
description: Updates the definition and metadata of an existing form.
tags:
- Forms
parameters:
- $ref: '#/components/parameters/formId'
- $ref: '#/components/parameters/formatJson'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
xml_data:
type: string
description: Updated XML definition of the form
builder_version:
type: string
language:
type: string
name:
type: string
responses:
'200':
description: Form updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Form'
'404':
description: Form not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api_v1/forms/delete/{formId}.{format}:
post:
operationId: deleteForm
summary: Delete a form
description: Permanently deletes the specified form and all associated data.
tags:
- Forms
parameters:
- $ref: '#/components/parameters/formId'
- $ref: '#/components/parameters/formatJson'
responses:
'200':
description: Form deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'404':
description: Form not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# ─── Responses ─────────────────────────────────────────────────────────────
/api_v1/responses/export/{formId}.{format}:
get:
operationId: exportResponses
summary: Export form responses
description: >
Exports submitted responses for a form. Supports JSON, XML, CSV, and ZIP
formats. Filtering by date range, specific response IDs, and flag status
is supported.
tags:
- Responses
parameters:
- $ref: '#/components/parameters/formId'
- name: format
in: path
required: true
schema:
type: string
enum: [json, xml, csv, zip]
description: Export format
- name: date_from
in: query
schema:
type: string
format: date
description: Filter responses submitted on or after this date
- name: date_to
in: query
schema:
type: string
format: date
description: Filter responses submitted on or before this date
- name: filter
in: query
schema:
type: string
enum: [all]
default: all
description: Filter preset
- name: response_ids
in: query
schema:
type: string
description: Comma-delimited list of specific response IDs to export
- name: flag
in: query
schema:
type: integer
description: Filter by flag status
- name: unlock
in: query
schema:
type: boolean
description: Include locked responses
- name: page
in: query
schema:
type: integer
default: 1
description: Page number for paginated results
- name: page_size
in: query
schema:
type: integer
default: 200
description: Number of responses per page (default 200)
responses:
'200':
description: Exported responses
content:
application/json:
schema:
type: object
properties:
responses:
type: array
items:
$ref: '#/components/schemas/Response'
application/xml:
schema:
type: object
text/csv:
schema:
type: string
format: binary
application/zip:
schema:
type: string
format: binary
'404':
description: Form not found
# ─── Connectors ────────────────────────────────────────────────────────────
/api_v1/connectors/index/{formId}.{format}:
get:
operationId: listConnectors
summary: List connectors for a form
description: Returns all connectors attached to the specified form.
tags:
- Connectors
parameters:
- $ref: '#/components/parameters/formId'
- $ref: '#/components/parameters/formatJson'
responses:
'200':
description: List of connectors
content:
application/json:
schema:
type: object
properties:
connectors:
type: array
items:
$ref: '#/components/schemas/Connector'
application/xml:
schema:
type: object
/admin/api_v1/connectors/view/{connectorId}.{format}:
get:
operationId: getConnector
summary: View connector definition (Admin)
description: Returns the full definition of a specific connector.
tags:
- Connectors
- Admin
parameters:
- $ref: '#/components/parameters/connectorId'
- $ref: '#/components/parameters/formatJson'
responses:
'200':
description: Connector definition
content:
application/json:
schema:
$ref: '#/components/schemas/Connector'
application/xml:
schema:
$ref: '#/components/schemas/Connector'
'404':
description: Connector not found
/admin/api_v1/connectors/create/{formId}/{connectorName}.{format}:
post:
operationId: createConnector
summary: Create a connector (Admin)
description: Creates a new connector for the specified form and connector type.
tags:
- Connectors
- Admin
parameters:
- $ref: '#/components/parameters/formId'
- $ref: '#/components/parameters/connectorName'
- $ref: '#/components/parameters/formatJson'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
event:
type: string
enum: [beforerender, before_save, interactive, background]
description: Trigger event for the connector
mapping:
type: string
description: Field mapping configuration
login:
type: string
description: Login credential for the connector service
password:
type: string
description: Password credential for the connector service
responses:
'200':
description: Connector created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Connector'
'400':
description: Invalid request
/admin/api_v1/connectors/edit/{connectorId}.{format}:
post:
operationId: updateConnector
summary: Update a connector (Admin)
description: Updates the configuration of an existing connector.
tags:
- Connectors
- Admin
parameters:
- $ref: '#/components/parameters/connectorId'
- $ref: '#/components/parameters/formatJson'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
event:
type: string
enum: [beforerender, before_save, interactive, background]
mapping:
type: string
login:
type: string
password:
type: string
responses:
'200':
description: Connector updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Connector'
'404':
description: Connector not found
/admin/api_v1/connectors/delete/{connectorId}.{format}:
post:
operationId: deleteConnector
summary: Delete a connector (Admin)
description: Permanently removes the specified connector from a form.
tags:
- Connectors
- Admin
parameters:
- $ref: '#/components/parameters/connectorId'
- $ref: '#/components/parameters/formatJson'
responses:
'200':
description: Connector deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'404':
description: Connector not found
# ─── Themes ────────────────────────────────────────────────────────────────
/api_v1/themes/index.json:
get:
operationId: listThemes
summary: List user themes
description: Returns all themes belonging to the authenticated user.
tags:
- Themes
responses:
'200':
description: List of themes
content:
application/json:
schema:
$ref: '#/components/schemas/ThemeList'
/admin/api_v1/themes/view/{themeId}.json:
get:
operationId: getTheme
summary: View theme CSS (Admin)
description: Returns the CSS content and metadata for the specified theme.
tags:
- Themes
- Admin
parameters:
- $ref: '#/components/parameters/themeId'
responses:
'200':
description: Theme definition
content:
application/json:
schema:
$ref: '#/components/schemas/Theme'
'404':
description: Theme not found
/admin/api_v1/themes/create.json:
post:
operationId: createTheme
summary: Create a theme (Admin)
description: Creates a new CSS theme for use with forms.
tags:
- Themes
- Admin
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
description: Display name for the theme
css_data:
type: string
description: Full CSS stylesheet content
responses:
'200':
description: Theme created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Theme'
/admin/api_v1/themes/edit/{themeId}.json:
post:
operationId: updateTheme
summary: Update a theme (Admin)
description: Updates the name and/or CSS of an existing theme.
tags:
- Themes
- Admin
parameters:
- $ref: '#/components/parameters/themeId'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
css_data:
type: string
responses:
'200':
description: Theme updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Theme'
'404':
description: Theme not found
/admin/api_v1/themes/delete/{themeId}.json:
post:
operationId: deleteTheme
summary: Delete a theme (Admin)
description: Permanently removes the specified theme.
tags:
- Themes
- Admin
parameters:
- $ref: '#/components/parameters/themeId'
responses:
'200':
description: Theme deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'404':
description: Theme not found
# ─── Form Elements ─────────────────────────────────────────────────────────
/api_v1/form_elements/index.xml:
get:
operationId: listFormElements
summary: List available form elements
description: Returns a list of all available form element types in XML format.
tags:
- Form Elements
responses:
'200':
description: List of form elements
content:
application/xml:
schema:
type: object
properties:
elements:
type: array
items:
$ref: '#/components/schemas/FormElement'
/admin/api_v1/form_elements/view/{elementId}.xml:
get:
operationId: getFormElement
summary: View form element definition (Admin)
description: Returns the full XML definition of the specified form element type.
tags:
- Form Elements
- Admin
parameters:
- $ref: '#/components/parameters/elementId'
responses:
'200':
description: Form element definition
content:
application/xml:
schema:
$ref: '#/components/schemas/FormElement'
'404':
description: Element not found
/admin/api_v1/form_elements/create.json:
post:
operationId: createFormElement
summary: Create a form element (Admin)
description: Creates a new custom form element type.
tags:
- Form Elements
- Admin
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
xml_data:
type: string
description: XML definition of the element
name:
type: string
description: Display name for the element
comments:
type: string
description: Notes about the element
category:
type: string
description: Category for organizing elements
subcategory:
type: string
description: Subcategory for further organization
batch:
type: string
description: Batch identifier for bulk operations
responses:
'200':
description: Form element created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FormElement'
/admin/api_v1/form_elements/edit/{elementId}.json:
post:
operationId: updateFormElement
summary: Update a form element (Admin)
description: Updates an existing custom form element type.
tags:
- Form Elements
- Admin
parameters:
- $ref: '#/components/parameters/elementId'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
xml_data:
type: string
name:
type: string
comments:
type: string
category:
type: string
subcategory:
type: string
batch:
type: string
responses:
'200':
description: Form element updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FormElement'
'404':
description: Element not found
/admin/api_v1/form_elements/delete/{elementId}.json:
post:
operationId: deleteFormElement
summary: Delete a form element (Admin)
description: Permanently removes a custom form element type.
tags:
- Form Elements
- Admin
parameters:
- $ref: '#/components/parameters/elementId'
responses:
'200':
description: Form element deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'404':
description: Element not found
# ─── Aggregates ────────────────────────────────────────────────────────────
/admin/api_v1/aggregates/reset_counters/{formId}.json:
post:
operationId: resetFormCounters
summary: Reset form counters (Admin)
description: Resets submission counters and aggregated statistics for the specified form.
tags:
- Aggregates
- Admin
parameters:
- $ref: '#/components/parameters/formId'
responses:
'200':
description: Counters reset successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'404':
description: Form not found
tags:
- name: OAuth2
description: OAuth2 authorization code flow for obtaining access tokens
- name: Forms
description: Create, read, update, and delete form definitions
- name: Responses
description: Export and manage form submission responses
- name: Connectors
description: Manage integrations (Salesforce, etc.) attached to forms
- name: Themes
description: Manage CSS themes applied to forms
- name: Form Elements
description: Manage custom reusable form element types
- name: Aggregates
description: Manage aggregated statistics and counters for forms
- name: Admin
description: Admin-only endpoints requiring elevated permissions
externalDocs:
description: FormAssembly API Documentation
url: https://help.formassembly.com/help/working-with-the-formassembly-api