openapi: 3.0.3
info:
  title: FormAssembly REST Admin Form Elements 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: []
tags:
- name: Form Elements
  description: Manage custom reusable form element types
paths:
  /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
      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
      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
      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
      parameters:
      - $ref: '#/components/parameters/elementId'
      responses:
        '200':
          description: Form element deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '404':
          description: Element not found
components:
  schemas:
    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        message:
          type: string
    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
  parameters:
    elementId:
      name: elementId
      in: path
      description: Unique identifier of the form element
      required: true
      schema:
        type: integer
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.formassembly.com/oauth/login
          tokenUrl: https://app.formassembly.com/oauth/access_token
          scopes: {}
externalDocs:
  description: FormAssembly API Documentation
  url: https://help.formassembly.com/help/working-with-the-formassembly-api