EC-PermitEC-Permit
Docs/API/Form Type Schema

Form Type JSON Schema

Create form types programmatically using the JSON schema. This reference documents the complete structure for form type definitions.

Schema Overview

{
  "name": "Hot Work Permit",
  "code": "HWP",
  "description": "Permit for welding, cutting, and grinding",
  "icon": "flame",
  "color": "#f97316",
  "questions": [...],
  "workflow": {...},
  "settings": {...}
}

Questions Array

Each question in the array defines a form field:

{
  "questions": [
    {
      "id": "q_work_location",
      "type": "text",
      "label": "Work Location",
      "description": "Enter the specific area where work will occur",
      "required": true,
      "placeholder": "e.g., Building A, Level 3"
    },
    {
      "id": "q_work_date",
      "type": "date_range",
      "label": "Work Period",
      "required": true
    },
    {
      "id": "q_fire_extinguisher",
      "type": "boolean",
      "label": "Fire extinguisher present?",
      "required": true
    },
    {
      "id": "q_signature",
      "type": "signature",
      "label": "Applicant Signature",
      "required": true
    }
  ]
}

Question Types

  • text — Single line text
  • textarea — Multi-line text
  • number — Numeric input
  • date — Date picker
  • datetime — Date and time
  • date_range — Start and end dates
  • boolean — Yes/No toggle
  • single_choice — Radio buttons/dropdown
  • multiple_choice — Checkboxes
  • file — File upload
  • signature — Signature pad
  • user_picker — Select users
  • location — Map pin

Workflow Object

{
  "workflow": {
    "statuses": [
      { "id": "draft", "name": "Draft", "color": "#gray", "type": "initial" },
      { "id": "pending", "name": "Pending Approval", "color": "#yellow" },
      { "id": "approved", "name": "Approved", "color": "#green", "type": "final" },
      { "id": "rejected", "name": "Rejected", "color": "#red", "type": "final" }
    ],
    "actions": [
      {
        "id": "submit",
        "name": "Submit",
        "from": "draft",
        "to": "pending",
        "allowed_roles": ["user", "admin"]
      },
      {
        "id": "approve",
        "name": "Approve",
        "from": "pending",
        "to": "approved",
        "allowed_roles": ["manager", "admin"],
        "require_comment": false
      },
      {
        "id": "reject",
        "name": "Reject",
        "from": "pending",
        "to": "rejected",
        "allowed_roles": ["manager", "admin"],
        "require_comment": true
      }
    ]
  }
}

Question Visibility

Control when questions are visible and editable:

{
  "id": "q_approval_notes",
  "type": "textarea",
  "label": "Approval Notes",
  "visibility": {
    "statuses": ["pending", "approved"],
    "roles": ["manager", "admin"]
  },
  "editable": {
    "statuses": ["pending"],
    "roles": ["manager", "admin"]
  }
}

Validation

Use the POST /form-types/validate endpoint to validate your schema before creating a form type.
WebhooksBest Practices