Request Format

JSON Structure

API requests must contain JSON data that matches the workflow's form structure. The form builder configuration determines:

• Field Names: Must match the form field keys exactly
• Field Types: Data types must be compatible (string, number, date, etc.)
• Required Fields: Must be included in the request
• Validation Rules: Must pass all form validation rules

Field Type Mapping

Form Builder Type	JSON Data Type	Example
textfield	string	"Sample text"
textarea	string	"Multi-line\ntext content"
email	string	"user@example.com"
number	number	123
date	string (ISO date)	"2024-01-15"
datetime	string (ISO datetime)	"2024-01-15T10:30:00"
checkbox	boolean	true
select	string	"option1"
radio	string	"choice_a"
selectboxes	object	{"option1": true, "option2": false}
datagrid	array of objects	[{"field1": "value1", "field2": "value2"}]

Basic Field Examples

Text Fields

{
  "name": "John Doe",
  "description": "This is a sample description",
  "comments": "Multi-line\ncomment text"
}

Numeric Fields

{
  "age": 30,
  "salary": 75000.50,
  "quantity": 100
}

Date and Time Fields

{
  "birth_date": "1990-05-15",
  "appointment_datetime": "2024-01-15T14:30:00",
  "created_at": "2024-01-15T10:30:00Z"
}

Boolean Fields

{
  "is_active": true,
  "newsletter_subscription": false,
  "terms_accepted": true
}

Complex Field Examples

Select/Radio Fields

{
  "category": "electronics",
  "priority": "high",
  "status": "pending"
}

Selectboxes (Multiple Checkboxes)

{
  "preferences": {
    "email_notifications": true,
    "sms_notifications": false,
    "push_notifications": true
  },
  "features": {
    "feature_a": true,
    "feature_b": true,
    "feature_c": false
  }
}

Datagrid (Table Data)

{
  "line_items": [
    {
      "item_name": "Widget A",
      "quantity": 5,
      "unit_price": 10.50,
      "total": 52.50
    },
    {
      "item_name": "Widget B", 
      "quantity": 2,
      "unit_price": 25.00,
      "total": 50.00
    }
  ]
}

Nested Form Components

{
  "applicant_info": {
    "personal": {
      "name": "John Doe",
      "age": 30,
      "gender": "male"
    },
    "contact": {
      "email": "john@example.com",
      "phone": "+1234567890",
      "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "zip": "12345"
      }
    }
  }
}

Complete Request Example

Employee Onboarding Form

{
  "employee_name": "Jane Smith",
  "employee_id": "EMP001234",
  "department": "Engineering",
  "position": "Senior Developer",
  "start_date": "2024-02-01",
  "salary": 85000,
  "employment_type": "full_time",
  "manager_email": "john.manager@company.com",
  "benefits": {
    "health_insurance": true,
    "dental_insurance": true,
    "vision_insurance": false,
    "retirement_plan": true
  },
  "emergency_contacts": [
    {
      "name": "John Smith",
      "relationship": "spouse",
      "phone": "+1234567890"
    },
    {
      "name": "Mary Johnson",
      "relationship": "mother",
      "phone": "+0987654321"
    }
  ],
  "skills": ["JavaScript", "Python", "React", "Node.js"],
  "notes": "Experienced developer with strong background in web technologies"
}

Data Validation Rules

Required Fields

All fields marked as required in the form builder must be included:

{
  "name": "Required field - must be present",
  "email": "required@example.com"
  // Missing required field will cause validation error
}

Format Validation

Fields with specific formats must match expected patterns:

{
  "email": "valid@example.com",  // Must be valid email format
  "phone": "+1-234-567-8900",     // Must match phone pattern if specified
  "postal_code": "12345",         // Must match postal code pattern
  "website": "https://example.com" // Must be valid URL if URL field
}

Length Constraints

Respect minimum and maximum length limits:

{
  "short_text": "OK",                    // Meets minimum length
  "description": "This text is long enough", // Within max length
  "code": "ABC123"                       // Exact length if specified
}

Common Mistakes

❌ Incorrect Field Names

{
  "Name": "John Doe",        // Wrong: Capital 'N'
  "user_email": "john@...",  // Wrong: Field name doesn't match form
  "phoneNumber": "+123..."   // Wrong: CamelCase instead of snake_case
}

✅ Correct Field Names

{
  "name": "John Doe",        // Correct: Matches form field exactly
  "email": "john@...",       // Correct: Exact field name
  "phone_number": "+123..."  // Correct: Matches form configuration
}

❌ Wrong Data Types

{
  "age": "30",              // Wrong: String instead of number
  "is_active": "true",      // Wrong: String instead of boolean
  "start_date": 1642204800  // Wrong: Timestamp instead of ISO date
}

✅ Correct Data Types

{
  "age": 30,                // Correct: Number
  "is_active": true,        // Correct: Boolean
  "start_date": "2024-01-15" // Correct: ISO date string
}

Request Headers

Always include these headers with your JSON requests:

Content-Type: application/json
Authorization: Bearer your-api-token
Accept: application/json

Testing Your Request Format

1. Use Workflow Documentation

Access auto-generated documentation:

1. Navigate to Admin → API Documentation
2. Select your workflow
3. Review field requirements and examples

2. Start Simple

Begin with minimal required fields:

{
  "name": "Test User",
  "email": "test@example.com"
}

3. Add Complexity Gradually

Once basic submission works, add optional and complex fields:

{
  "name": "Test User",
  "email": "test@example.com",
  "preferences": {
    "notifications": true
  }
}

4. Validate Responses

Check API responses for validation errors and adjust format accordingly.