openapi: 3.0.3
info:
  title: FormAssembly REST Admin Forms 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: Forms
  description: Create, read, update, and delete form definitions
paths:
  /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
      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'
components:
  schemas:
    FormList:
      type: object
      properties:
        forms:
          type: array
          items:
            $ref: '#/components/schemas/Form'
    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
    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        message:
          type: string
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - error
        message:
          type: string
  parameters:
    formId:
      name: formId
      in: path
      description: Unique identifier of the form
      required: true
      schema:
        type: integer
    formatJson:
      name: format
      in: path
      description: Response format (json or xml)
      required: true
      schema:
        type: string
        enum:
        - json
        - xml
        default: json
  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