Skip to content

API reference

Forms

Read, create, change and delete forms with every field and setting, and draft new ones with AI. Everything the form builder does, from your own code.

List forms

GEThttps://formpik.modulify.website/api/v1/forms

Newest first. Filter with ?status=active, paused or draft.

Read one form

GEThttps://formpik.modulify.website/api/v1/forms/{id}
200 OK
{
  "data": {
    "id": "frm_q8w2e4r6t1",
    "name": "Contact",
    "description": "",
    "status": "active",
    "fields": [
      {
        "id": "fld_a1s2d3f4g5",
        "key": "email",
        "label": "Email",
        "type": "email",
        "required": true,
        "collects_answer": true,
        "multiple": false,
        "placeholder": "you@company.com"
      },
      {
        "id": "fld_h6j7k8l9z0",
        "key": "topic",
        "label": "What can we help with?",
        "type": "select",
        "required": true,
        "collects_answer": true,
        "multiple": false,
        "options": [
          { "id": "opt_x1c2v3b4n5", "label": "Sales", "value": "sales" },
          { "id": "opt_m6q7w8e9r0", "label": "Support", "value": "support" }
        ]
      },
      {
        "id": "fld_t1y2u3i4o5",
        "key": "heading",
        "label": "A few details",
        "type": "heading",
        "required": false,
        "collects_answer": false,
        "multiple": false
      }
    ],
    "settings": {
      "success_message": "Thanks, we've received your submission.",
      "error_message": "",
      "after_submit": "redirect",
      "redirect_url": "https://yourcompany.com/thanks?name={{name}}",
      "redirect_rules": [
        { "id": "rdr_k2m9x4q1w3", "field": "budget", "operator": "equals", "value": "50k_plus", "url": "https://cal.com/yourcompany/intro?email={{email}}" }
      ],
      "redirect_delay": 3,
      "allowed_domains": ["yourcompany.com"],
      "honeypot": true,
      "captcha": "off",
      "rate_limit_per_hour": 20,
      "retention_days": 365,
      "learn_fields": false,
      "embed": { "theme": "light", "accent": "#2647d9", "radius": "md", "button_label": "Send" }
    },
    "created_at": "2026-11-02T14:12:09.000Z",
    "updated_at": "2026-11-19T08:41:55.000Z"
  }
}
  • fields lists every field in order, layout blocks included. collects_answer is false for headings, text blocks and dividers, which send nothing.
  • multiple is true when the field sends a list of values.
  • options lists the values a choice field accepts. Yes or no fields list yes and no. Country fields accept any two letter ISO code and list no options.
  • Settings a field does not use are left out, so a text field has no step and a slider no placeholder.

Create a form

POSThttps://formpik.modulify.website/api/v1/forms

Answers 201 with the new form. Needs a key with full access.

Body

namestringrequired
Up to 120 characters.
descriptionstring
Up to 500 characters.
statusstring
active (the default), paused or draft. Only active forms take submissions.
fieldsarray
The fields in order. See Fields. Leave it out for an empty form.
settingsobject
Any of the settings shown above. Leave out what you do not want to change. See Settings.
cURL
curl -X POST "https://formpik.modulify.website/api/v1/forms" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Quote request", "fields": [{"label": "Email", "type": "email", "required": true}, {"label": "Budget", "type": "select", "options": ["Under 5k", "5k to 20k", "Over 20k"]}, {"label": "Details", "type": "textarea"}]}'

Change a form

PATCHhttps://formpik.modulify.website/api/v1/forms/{id}

Send only what changes. Needs a key with full access.

  • fields replaces the whole list. Repeat a field's id to keep it, with every setting you leave out. Fields without an id are added, and fields you leave out are removed.
  • When you change a field's key or an option's value, every flow of the form is rewritten to match, the same as in the builder. The answer tells you how many in flows_updated.
  • settings is merged into the current settings, so {"settings": {"redirect_url": "https://yourcompany.com/thanks"}} changes only the redirect and sends visitors there. Renaming a field key or an option value also rewrites the redirect_rules and redirect_url that use it.
cURL
curl -X PATCH "https://formpik.modulify.website/api/v1/forms/frm_q8w2e4r6t1" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'
200 OK
{
  "data": { "id": "frm_q8w2e4r6t1", "status": "paused", "...": "..." },
  "flows_updated": 0
}

Delete a form

DELETEhttps://formpik.modulify.website/api/v1/forms/{id}

Deletes the form with its sources, submissions and uploaded files, and pauses its flows. This cannot be undone. Needs a key with full access.

200 OK
{ "ok": true, "id": "frm_q8w2e4r6t1" }

Fields

Each field is an object. Names use snake_case, the same as in answers.

typestringrequired
One of text, textarea, email, phone, number, currency, url, address, date, time, datetime, select, multiselect, radio, checkbox, yesno, country, rating, scale, slider, consent, file, hidden, heading, paragraph, divider. See Field types.
idstring
Only to keep an existing field when you change a form.
labelstring
The question. For a text block, the text itself.
keystring
The name websites send the answer under. Letters, numbers, _, - and .. Made from the label when left out, and unique within the form.
requiredboolean
Whether a submission needs an answer. Layout blocks and hidden fields are never required.
placeholder, help_text, default_valuestring
The hint inside the input, the line under it, and the starting answer.
optionsarray
Needed for select, multiselect, radio and checkbox. Plain labels such as ["Sales", "Support"], or objects { "label": "Sales", "value": "sales" }. Values are made from labels when left out.
validationobject
The field's rules, such as max_length, allowed_domains, block_free_email, countries with country_mode, min_date, weekdays or unique. A field type only keeps the rules it uses, null removes one, and an unknown name is refused. See Field rules for every rule and the types that take it.
stepnumber
Sliders: the size of one step.
low_label, high_labelstring
Opinion scales: the words under the two ends.
currencystring
Amounts: an ISO code such as USD or EUR.
multiple, acceptboolean, string
File uploads: allow several files, and the types to offer, such as .pdf,image/*.

Settings

after_submitstring
message keeps visitors on the page, redirect sends them to redirect_url. Setting only redirect_url picks redirect when it has an address and message when it is empty.
success_messagestring
What people see after sending, and while they wait to go on to a page.
error_messagestring
Shown instead of the exact reason when a submission is refused. Empty shows the reason.
redirect_urlstring
The page for redirect. Answers in double curly braces after the website address, such as ?name={{name}}, are filled in for each visitor.
redirect_rulesobject[]
Up to 10 rules of id, field, operator (the If / else operators, such as equals or is_any_of), value and url. The first rule that matches sends the visitor to its page, whatever after_submit says.
redirect_delaynumber
Seconds the success message shows before going to a page: 0, 3 or 5.
allowed_domainsstring[]
Websites browsers may post from. Empty allows any.
honeypotboolean
The _gotcha spam trap.
captchastring
off, turnstile or recaptcha.
rate_limit_per_hournumber
Submissions one visitor may send an hour. 0 for no limit.
retention_daysnumber
How long submissions are kept. 0 keeps them forever. Values above your plan are lowered to its limit.
learn_fieldsboolean
Add fields the form does not know yet when a website sends them.
embedobject
theme (light or dark), accent (a hex color), radius (none, sm, md, lg) and button_label.

Draft a form with AI

POSThttps://formpik.modulify.website/api/v1/ai/form-draft

Drafts fields from a description and saves nothing. Uses the same daily AI drafts as the dashboard, and at most 20 an hour per key. Needs a key with full access.

Body

promptstringrequired
What the form is for, in a sentence or two. Up to 1,500 characters.
form_idstring
Draft only the fields missing from this form.
cURL
curl -X POST "https://formpik.modulify.website/api/v1/ai/form-draft" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Booking form for a hair salon with service, stylist, date and time"}'

The answer has name, description and fields in exactly the shape POST /api/v1/forms takes, so you can send it on as it is, or add its fields to an existing form with PATCH.