Create Form

The form creation system allows you to create customizable data collection forms in your workspace. When you create a form, the system automatically handles form registration, unique identifier generation, file uploads for branding, and data storage structure setup.

API Endpoint

Endpoint: POST /api/common/create-object Content-Type: multipart/form-data Authentication: Required (Token header: token or api_access_token)

Request Structure

The endpoint accepts a multipart/form-data request with the following structure:

{
  "object_name": "Contact Form",           // Required
  "object_type": 1,                        // Optional: Defaults to 1
  "folder_id": 5,                          // Optional: ID of folder to organize form
  "form_banner": "image_file_or_path",     // Optional: Banner image file
  "form_logo": "image_file_or_path",      // Optional: Logo image file
  "form_description": "Form description",  // Optional: Text description
  "rating": 0.00                          // Optional: Rating value (0.00-5.00), defaults to 0.00
}

File Uploads:

form_banner - Banner image file (PNG, JPG, JPEG, SVG, GIF)
form_logo - Logo image file (PNG, JPG, JPEG, SVG, GIF)

cURL Example

curl -X POST "https://your-api-domain.com/api/common/create-object" \
  -H "token: YOUR_AUTH_TOKEN" \
  -F "object_name=Contact Form" \
  -F "form_description=Customer contact information collection form" \
  -F "object_type=1" \
  -F "folder_id=5" \
  -F "form_banner=@/path/to/banner.png" \
  -F "form_logo=@/path/to/logo.png" \
  -F "rating=0.00"

Note: Remove any fields you don’t need. Only object_name is required.

Response

Success Response

Status Code: 200 OK

{
  "message": "OBJECT_CREATED_SUCCESSFULLY",
  "object": {
    "ID": 123,
    "OBJECT_NAME": "Contact Form",
    "OBJECT_SLUG": "contactform123456",
    "WORKSPACE_ID": 1,
    "PRIMARY_TABLE": "company_acme_123",
    "SECONDARY_TABLE": "company_acme_123_data",
    "FOLDER_ID": 5,
    "FORM_BANNER": "1/forms/banner/banner.png",
    "FORM_LOGO": "1/forms/logo/logo.png",
    "FORM_DESCRIPTION": "Customer contact information collection form",
    "RATING": 0.00,
    "OBJECT_TYPE": 1,
    "STATUS": 1,
    "CREATED_ON": "2024-01-15T10:30:00.000Z",
    "UPDATED_ON": "2024-01-15T10:30:00.000Z"
  }
}

Response Fields

Field	Type	Description
`ID`	integer	Unique identifier for the created form
`OBJECT_NAME`	string	Name of the form
`OBJECT_SLUG`	string	Unique URL-friendly identifier generated from the form name
`WORKSPACE_ID`	integer	ID of the workspace this form belongs to
`PRIMARY_TABLE`	string	Internal table name for storing form submission metadata
`SECONDARY_TABLE`	string	Internal table name for storing form field data
`FOLDER_ID`	integer or null	ID of the folder containing this form, if organized
`FORM_BANNER`	string or null	Path to the uploaded banner image
`FORM_LOGO`	string or null	Path to the uploaded logo image
`FORM_DESCRIPTION`	string or null	Description of the form
`RATING`	decimal	Average rating value
`OBJECT_TYPE`	integer	Type of form object
`STATUS`	integer	Status of the form (1 = active)
`CREATED_ON`	datetime	Timestamp when the form was created
`UPDATED_ON`	datetime	Timestamp when the form was last updated

Error Responses

422 - Validation Error

Status Code: 422 Unprocessable Entity

{
  "error": true,
  "code": 422,
  "message": "Object Name is missing",
  "data": {}
}

Common Error Messages:

"Object Name is missing" - Required field object_name is missing
"Object Name is invalid" - Invalid format for object_name
"INVALID_FORM_BANNER_FILE_TYPE" - Banner file type is not supported (use PNG, JPG, JPEG, SVG, or GIF)
"INVALID_FORM_LOGO_FILE_TYPE" - Logo file type is not supported (use PNG, JPG, JPEG, SVG, or GIF)
"FORM_BANNER_FILE_REQUIRED" - Banner file field is present but empty
"FORM_LOGO_FILE_REQUIRED" - Logo file field is present but empty

401 - Authentication Error

Status Code: 401 Unauthorized

{
  "error": true,
  "code": 401,
  "message": "Invalid Auth Key or Session Expired",
  "data": {}
}

500 - Server Error

Status Code: 500 Internal Server Error

{
  "error": true,
  "code": 500,
  "message": "Internal server error",
  "data": {}
}

Error Codes

Status Code	Error Code	Description
200	-	Success
401	AUTH_REQUIRED	Authentication required - Missing or invalid token
401	AUTH_INVALID	Invalid authentication token or session expired
422	VALIDATION_ERROR	Validation failed - Check required fields and data format
422	MISSING_FIELD	Required field missing
422	INVALID_FORMAT	Invalid data format or type
422	INVALID_FORM_BANNER_FILE_TYPE	Banner file type not supported
422	INVALID_FORM_LOGO_FILE_TYPE	Logo file type not supported
422	FORM_BANNER_FILE_REQUIRED	Banner file field is empty
422	FORM_LOGO_FILE_REQUIRED	Logo file field is empty
422	OBJECT_ALREADY_EXISTS	Form with same slug already exists (rare, handled automatically)
422	COMPANY_NOT_FOUND	Company details not found
500	SERVER_ERROR	Internal server error

Automatic Features

Name Uniqueness

If a form with the same name already exists in your workspace, the system automatically appends a number suffix to ensure uniqueness:

“Contact Form” → “Contact Form (1)” (if “Contact Form” exists)
“Contact Form” → “Contact Form (2)” (if both exist)

Slug Generation

A unique slug is automatically generated from the form name:

Special characters are removed
Text is converted to lowercase
A random 6-digit number is appended for uniqueness
Example: “Contact Form” → “contactform123456”

Data Storage Setup

When you create a form, the system automatically sets up data storage structures:

Primary Table: Stores metadata for each form submission (one record per submission)
Secondary Table: Stores the actual form field data in a flexible key-value structure

These tables are created automatically when needed and are shared across all forms in your company for efficient data management.

File Upload Guidelines

Supported File Types

Banner and Logo: PNG, JPG, JPEG, SVG, GIF

File Upload Requirements

File Size: Ensure files are reasonably sized for web use
File Format: Only image formats listed above are accepted
Validation: The system validates both file extension and MIME type
Storage: Files are securely stored in workspace-specific directories:
- Banner images: {workspace_id}/forms/banner
- Logo images: {workspace_id}/forms/logo

Important Notes

object_name is required - all other fields are optional
File uploads are optional - you can create forms without banners or logos
Forms can be organized in folders using the folder_id parameter
The system automatically handles data storage structure setup
Form slugs are unique per workspace, not globally across all workspaces
All operations are transactional - if any step fails, the entire operation is rolled back
Duplicate names are automatically handled with number suffixes

API Documentation

Agents

Voice AI

Phone Numbers

Voices

Call Logs

Chatbots

Forms

Workflows

Workspaces

Users

API Endpoint

Request Structure

cURL Example

Response

Success Response

Response Fields

Error Responses

422 - Validation Error

401 - Authentication Error

500 - Server Error

Error Codes

Automatic Features

Name Uniqueness

Slug Generation

Data Storage Setup

File Upload Guidelines

Supported File Types

File Upload Requirements

Important Notes

API Documentation

Agents

Voice AI

Phone Numbers

Voices

Call Logs

Chatbots

Forms

Workflows

Workspaces

Users

​API Endpoint

​Request Structure

​cURL Example

​Response

​Success Response

​Response Fields

​Error Responses

​422 - Validation Error

​401 - Authentication Error

​500 - Server Error

​Error Codes

​Automatic Features

​Name Uniqueness

​Slug Generation

​Data Storage Setup

​File Upload Guidelines

​Supported File Types

​File Upload Requirements

​Important Notes

API Endpoint

Request Structure

cURL Example

Response

Success Response

Response Fields

Error Responses

422 - Validation Error

401 - Authentication Error

500 - Server Error

Error Codes

Automatic Features

Name Uniqueness

Slug Generation

Data Storage Setup

File Upload Guidelines

Supported File Types

File Upload Requirements

Important Notes