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