Request Format

JSON Structure

API requests must contain JSON data that matches the workflow's form structure.

What the API validates:

• Required fields — fields marked required in the form builder must be present
• Input masks — values must match the mask pattern if one is configured
• Basic type rules — textfield/textarea must be strings; number must be numeric; email must be a valid email address; date must be a valid date

What the API does NOT validate: min/max length, numeric min/max ranges, URL format, regex pattern rules, or custom JS validation. Those are only enforced by the browser on the web form.

Payload limits: Maximum 100 fields in a single payload and maximum 5 levels of nesting. Payloads exceeding these limits return a 422 error.

HTML sanitization: String values have HTML tags stripped before storage (strip_tags). This removes the tags but leaves the inner text — do not rely on it as a security boundary. Do not send HTML in field values.

Finding the Workflow ID

Open the workflow in OSPROV. The ID is in the URL: /workflows/42/edit → the ID is 42.

Finding Field Keys

Field keys are the Property Names in each component's Technical Properties tab in the Form Builder. They are case-sensitive. The fastest way to confirm them: run the Query Builder on that workflow and inspect the keys in the JSON response — they appear exactly as they should in your API payload.

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	Not available in the OSPROV form builder
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"
}

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

Required headers:

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

The Accept: application/json header is optional but recommended as a convention:

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.