P
ProFormsDocs

Create Form

Create a new form with fields, settings, theme, and conditions.

forms.create
POST/v1/forms

Request Body

name*string

Form name (max 255 chars)

siteId*string

UUID of the site this form belongs to

titlestring

Public-facing form title

descriptionstring

Form description

fieldsarray

Array of field objects (see below)

conditionsarray

Conditional logic rules

settingsobject

Form settings (submit button text, success action, etc.)

themeobject

Visual theme overrides (colors, fonts, spacing)

Field Object

Each field in the fields array requires:

key*string

Unique field identifier

type*string

Field type: text, textarea, email, phone, number, select, multiselect, radio, checkbox, date, time, file, hidden, name, company, address, url, signature, rating, scale, nps, matrix, heading, paragraph, divider, calculated

label*string

Field label shown to user

required*boolean

Whether field is required

width*string

Layout width: full, half, or third

order*integer

Display order (0-based)

placeholderstring

Placeholder text

helpTextstring

Help text shown below field

defaultValuestring

Pre-filled value

optionsarray

For select/radio/checkbox: [{label, value, score?, calcValue?}]

validationobject

Validation rules (minLength, maxLength, pattern, etc.)

formulastring

For calculated fields: math formula referencing other fields by key (e.g. 'price * quantity * tax_rate')

numberFormatstring

For calculated fields: 'number', 'currency', or 'percentage'

currencySymbolstring

For calculated fields: currency symbol (default '$')

decimalPlacesinteger

For calculated fields: decimal precision (default 2)

Markdown support: Field labels, option labels, help text, and disclaimer text support inline markdown: **bold**, *italic*, [link](url), ~~strikethrough~~. Raw HTML is stripped for security. See Update Form for details.

Example Request

curl
curl -X POST "https://proforms.io/api/v1/forms" \
  -H "Authorization: Bearer pf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Form",
    "siteId": "s_xyz789",
    "title": "Get in Touch",
    "fields": [
      {
        "key": "name",
        "type": "name",
        "label": "Your Name",
        "required": true,
        "width": "full",
        "order": 0
      },
      {
        "key": "email",
        "type": "email",
        "label": "Email Address",
        "required": true,
        "width": "half",
        "order": 1,
        "placeholder": "you@example.com"
      },
      {
        "key": "phone",
        "type": "phone",
        "label": "Phone Number",
        "required": false,
        "width": "half",
        "order": 2
      },
      {
        "key": "message",
        "type": "textarea",
        "label": "Message",
        "required": true,
        "width": "full",
        "order": 3,
        "placeholder": "How can we help?"
      },
      {
        "key": "service",
        "type": "select",
        "label": "Service Needed",
        "required": false,
        "width": "full",
        "order": 4,
        "options": [
          { "label": "Web Design", "value": "web-design" },
          { "label": "SEO", "value": "seo" },
          { "label": "Other", "value": "other" }
        ]
      }
    ]
  }'

Response

200 OK
{
  "success": true,
  "data": {
    "id": "f_abc123",
    "name": "Contact Form",
    "title": "Get in Touch",
    "status": "draft",
    "createdAt": "2026-02-17T10:00:00.000Z"
  }
}

Calculated Fields

Add type: "calculated" fields to build cost estimators, order forms, and ROI calculators. Formulas reference other fields by key and support + - * / % () operators. Select/radio fields resolve to their option's calcValue.

Calculated field with dropdown multiplier
{
  "fields": [
    {
      "key": "sqft", "type": "number", "label": "Square Footage",
      "required": true, "width": "half", "order": 0
    },
    {
      "key": "material", "type": "select", "label": "Material",
      "required": true, "width": "half", "order": 1,
      "options": [
        { "label": "Standard", "value": "standard", "calcValue": 4.50 },
        { "label": "Premium", "value": "premium", "calcValue": 7.25 }
      ]
    },
    {
      "key": "total", "type": "calculated", "label": "Estimated Cost",
      "required": false, "width": "full", "order": 2,
      "formula": "sqft * material * 1.12",
      "numberFormat": "currency",
      "currencySymbol": "$",
      "decimalPlaces": 0
    }
  ]
}

Quiz Mode

Enable quiz scoring by setting quizMode: true in settings and adding score values to correct options.

Quiz settings + scored options
{
  "settings": {
    "quizMode": true,
    "quizConfig": {
      "showScore": true,
      "showCorrect": true,
      "passingScore": 70,
      "passMessage": "Great job! You passed!",
      "failMessage": "Keep studying and try again."
    }
  },
  "fields": [
    {
      "key": "q1", "type": "radio", "label": "What is 2 + 2?",
      "required": true, "width": "full", "order": 0,
      "options": [
        { "label": "3", "value": "3", "score": 0 },
        { "label": "4", "value": "4", "score": 10 },
        { "label": "5", "value": "5", "score": 0 }
      ]
    }
  ]
}
💡
Forms are created as draft by default. Use the Publish endpoint to make them live.