openapi: 3.0.3
info:
  title: 123FormBuilder REST API v2 Accounts Groups API
  description: REST API v2 for 123FormBuilder. Manage forms, retrieve and update submissions, list fields, administer users, groups, and accounts. Authenticate by exchanging credentials at /token for a JWT, then pass the token on subsequent requests.
  version: 2.0.0
  contact:
    name: 123FormBuilder Developer Support
    url: https://www.123formbuilder.com/developer/contact-us/
  license:
    name: Proprietary
    url: https://www.123formbuilder.com/terms-of-service/
servers:
- url: https://api.123formbuilder.com/v2
  description: US regional endpoint
- url: https://eu-api.123formbuilder.com/v2
  description: EU regional endpoint
security:
- JWTQuery: []
tags:
- name: Groups
  description: Organize forms into groups and share groups with subusers.
paths:
  /groups:
    get:
      summary: Get All User Groups
      description: Get all user groups
      tags:
      - Groups
      operationId: groups-get-all-user-groups
      parameters:
      - name: JWT
        in: query
        required: true
        description: JWT authentication token
        schema:
          type: string
      - name: per_page
        in: query
        required: false
        description: The number of groups to get per page in a request. Default is 100 and the maximum number is 1000.
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
      responses:
        '200':
          description: Lists all user groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/definitions/Group'
                  meta:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                            description: Indicates the total number of groups.
                          count:
                            type: integer
                            description: Indicates how many groups are diplayed on the current page.
                          per_page:
                            type: integer
                            description: Indicates how many groups are displayed per page.
                          current_page:
                            type: integer
                            description: Indicates the number of the current page.
                          total_pages:
                            type: integer
                            description: Indicates the total number of pages.
                          links:
                            type: object
                            properties:
                              next:
                                type: string
                                description: URL to the next page
                              previous:
                                type: string
                                description: URL to the previous page
                  status_code:
                    type: integer
              example:
                page: 1
                per_page: 25
                total: 3
                groups:
                - id: 412
                  name: Sales Forms
                  parent_id: 0
                  webhook_url: https://example.com/webhooks/123fb
                  created_at: '2026-04-01T08:00:00Z'
        '400':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: &id001
                status_code: 400
                error: Bad Request
                message: Invalid or missing parameter.
        '401':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id001
    post:
      summary: Create a New Group
      description: Create a new group
      tags:
      - Groups
      operationId: groups-create-a-new-group
      parameters: []
      responses:
        '201':
          description: The group was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/definitions/Group'
                  status_code:
                    type: integer
              example:
                status_code: 201
                group:
                  id: 412
                  name: Sales Forms
                  parent_id: 0
                  webhook_url: https://example.com/webhooks/123fb
                  created_at: '2026-04-01T08:00:00Z'
        '400':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: &id002
                status_code: 400
                error: Bad Request
                message: Invalid or missing parameter.
        '401':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id002
        '422':
          description: Validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          $ref: '#/definitions/GroupCreateValidationError'
                      status_code:
                        type: integer
              example: *id002
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                JWT:
                  type: string
                  description: JWT authentication token
                name:
                  type: string
                  description: Form name
                webhook_url:
                  type: string
                  description: The URL of the WebHook
                parent_id:
                  type: integer
                  description: Indicates the ID of the parent group. Default value is -1, wich means that the group is in the root.
              required:
              - JWT
              - name
  /groups/{group_id}:
    get:
      summary: Get Group Details
      description: Get information about a specific group.
      tags:
      - Groups
      operationId: groups-get-group-details
      parameters:
      - name: JWT
        in: query
        required: true
        description: JWT authentication token
        schema:
          type: string
      - name: group_id
        in: path
        required: true
        description: The ID of the group
        schema:
          type: integer
      responses:
        '200':
          description: Details about the group
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/definitions/Group'
                  status_code:
                    type: integer
                    description: Status code
              example:
                id: 412
                name: Sales Forms
                parent_id: 0
                webhook_url: https://example.com/webhooks/123fb
                created_at: '2026-04-01T08:00:00Z'
        '400':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: &id003
                status_code: 400
                error: Bad Request
                message: Invalid or missing parameter.
        '401':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id003
        '403':
          description: Access Denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id003
    put:
      summary: Update Group Data
      description: Updates the details of a group.
      tags:
      - Groups
      operationId: groups-update-group-data
      parameters:
      - name: group_id
        in: path
        required: true
        description: The ID of the group you want to edit
        schema:
          type: integer
      responses:
        '200':
          description: The group was updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/definitions/Group'
                  status_code:
                    type: integer
              example:
                status_code: 200
                group:
                  id: 412
                  name: Sales Forms
                  parent_id: 0
                  webhook_url: https://example.com/webhooks/123fb
                  created_at: '2026-04-01T08:00:00Z'
        '400':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: &id004
                status_code: 400
                error: Bad Request
                message: Invalid or missing parameter.
        '401':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id004
        '403':
          description: Access was denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id004
        '422':
          description: Validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          $ref: '#/definitions/GroupUpdateValidationError'
                      status_code:
                        type: integer
              example: *id004
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                JWT:
                  type: string
                  description: JWT authentication token
                name:
                  type: string
                  description: This is required when the webhook_url or parent_id is missing.
                webhook_url:
                  type: string
                  description: This is required when the name or parent_id is missing.
                parent_id:
                  type: integer
                  description: Indicates the ID of the parent group. Default value is -1, wich means that the group is in the root. This field is required when the name or the webhook_url are missing.
              required:
              - JWT
  /groups/{group_id}/forms:
    get:
      summary: Get All Forms in a Group
      description: Displays a list of all of the forms within a specific group.
      tags:
      - Groups
      operationId: groups-get-all-forms-in-a-group
      parameters:
      - name: JWT
        in: query
        required: true
        description: JWT authentication token
        schema:
          type: string
      - name: group_id
        in: path
        required: true
        description: The ID of the group
        schema:
          type: integer
      responses:
        '200':
          description: List all user groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/definitions/GroupWithForms'
                  status_code:
                    type: integer
              example:
              - id: 5837291
                name: Customer Feedback Survey
                active: 1
                created_at: '2026-05-12T09:33:00Z'
                modified_at: '2026-05-20T14:18:00Z'
                submissions_count: 1284
                group_id: 412
                url: https://form.jotform.com/5837291
        '400':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: &id005
                status_code: 400
                error: Bad Request
                message: Invalid or missing parameter.
        '401':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id005
        '403':
          description: Access was denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id005
  /groups/{group_id}/share:
    post:
      summary: Share a Group with a User
      description: This may not be available for your account. It is specific to certain users.
      tags:
      - Groups
      operationId: groups-share-a-group-with-a-user
      parameters:
      - name: group_id
        in: path
        required: true
        description: The ID of the group you want to share
        schema:
          type: integer
      responses:
        '200':
          description: Group was shared.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status_code:
                    type: integer
              example:
                status_code: 200
                message: Group shared with subuser
        '400':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: &id006
                status_code: 400
                error: Bad Request
                message: Invalid or missing parameter.
        '401':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id006
        '403':
          description: Access was denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id006
        '422':
          description: Validation errors occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id006
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                JWT:
                  type: string
                  description: JWT authentication token
                subuser_id:
                  type: integer
                  description: The ID of the user with whom you want to share this group. This is required when subuser_email is missing.
                subuser_email:
                  type: string
                  description: The username with whom you want to share this group. This is required when subuser_id is missing.
              required:
              - JWT
  /groups/{group_id}/unshare:
    post:
      summary: Unshare a Group From a User
      description: This may not be available for your account. It is specific to certain users.
      tags:
      - Groups
      operationId: groups-unshare-a-group-from-a-user
      parameters:
      - name: group_id
        in: path
        required: true
        description: The ID of the group you want to unshare
        schema:
          type: integer
      responses:
        '201':
          description: Group was unshared.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status_code:
                    type: integer
              example:
                status_code: 201
                message: Group unshared from subuser
        '400':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: &id007
                status_code: 400
                error: Bad Request
                message: Invalid or missing parameter.
        '401':
          description: Token is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id007
        '403':
          description: Access was denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id007
        '422':
          description: Validation errors occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example: *id007
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                JWT:
                  type: string
                  description: JWT authentication token
                subuser_id:
                  type: integer
                  description: The ID of the subuser from whom you want to unshare the group. This is required when subuser_email is missing.
                subuser_email:
                  type: string
                  description: The username from whom you want to unshare the group. This is required when subuser_id is missing.
              required:
              - JWT
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Details about the error
            status_code:
              type: integer
              description: The status code of the request
  securitySchemes:
    JWTQuery:
      type: apiKey
      in: query
      name: JWT
      description: JWT token obtained from POST /token, supplied as the JWT query parameter.