openapi: 3.0.3
info:
  title: FormAssembly REST Admin Connectors 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: Connectors
  description: Manage integrations (Salesforce, etc.) attached to forms
paths:
  /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
      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
      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
      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
      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
components:
  schemas:
    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
    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
        message:
          type: string
  parameters:
    connectorName:
      name: connectorName
      in: path
      description: Name of the connector type to create
      required: true
      schema:
        type: string
    connectorId:
      name: connectorId
      in: path
      description: Unique identifier of the connector
      required: true
      schema:
        type: integer
    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