Skip to content

API reference

Forms

Read, create, change, duplicate and delete forms with every field and setting, publish them on their own share link, and draft new ones with AI. Everything the form builder does, from your own code.

List forms

GEThttps://formpik.com/api/v1/forms

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

Read one form

GEThttps://formpik.com/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" },
      "page": { "published": true, "slug": "quote-request", "indexable": false, "published_at": "2026-11-03T10:20:00.000Z" }
    },
    "share_url": "https://formpik.com/f/quote-request",
    "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.
  • share_url is the form's public page while it is published, and null otherwise. See Publish a form.

Create a form

POSThttps://formpik.com/api/v1/forms

Answers 201 with the new form. Needs a key with full or admin 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.com/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.com/api/v1/forms/{id}

Send only what changes. Needs a key with full or admin 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.com/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.com/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 or admin access.

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

Publish a form

POSThttps://formpik.com/api/v1/forms/{id}/publish

Gives the form its own public page, its share link, and turns on its embeds. Call it again with another slug to move the link. Needs a key with full or admin access.

Body

slugstring
The end of the link, /f/{slug}: 3 to 60 lowercase letters, numbers and dashes, unique across Formpik. Left out, a first publish takes one made from the form's name when it is free, or a random one. A slug another form has answers 409 with slug-taken.
indexableboolean
Let search engines list the page. false by default, so only people with the link find it.
cURL
curl -X POST "https://formpik.com/api/v1/forms/frm_q8w2e4r6t1/publish" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug": "quote-request"}'
200 OK
{
  "data": { "id": "frm_q8w2e4r6t1", "name": "Quote request", "share_url": "https://formpik.com/f/quote-request", "...": "..." },
  "published": true,
  "share_url": "https://formpik.com/f/quote-request",
  "embed": {
    "inline": "<div data-formpik-form=\"frm_q8w2e4r6t1\"></div>\n<script src=\"https://formpik.com/embed.js\" async></script>",
    "popup": "<button type=\"button\" data-formpik-popup=\"frm_q8w2e4r6t1\">Open the form</button>\n<script src=\"https://formpik.com/embed.js\" async></script>",
    "iframe": "<iframe src=\"https://formpik.com/f/frm_q8w2e4r6t1?embed=1\" ...></iframe>"
  },
  "source_id": "hst_q8w2e4r6t1"
}
  • The page posts to the form's own Share link source (its id is in source_id), so its submissions run through the same checks, spam protection and flows as every website, and a flow can pick them out with its source filter. It never counts toward the plan's sources.
  • embed holds ready snippets for any website: inline draws the form where it sits, popup opens it from a button, iframe is for site builders that run no scripts. They use the form id, so they keep working when the slug changes.
  • Answers can be filled in from the link, such as https://formpik.com/f/quote-request?email=jane@example.com, hidden fields included. A paused form keeps its page, which then says it takes no answers.
  • The same settings live under settings.page (published, slug, indexable), so PATCH can change them too. published_at is set by Formpik.

Unpublish a form

POSThttps://formpik.com/api/v1/forms/{id}/unpublish

Takes the share link and every embed offline. The slug is kept, so publishing again brings the same link back. Websites connected as sources keep working. Needs a key with full or admin access.

200 OK
{
  "data": { "id": "frm_q8w2e4r6t1", "share_url": null, "...": "..." },
  "published": false,
  "share_url": null,
  "embed": null
}

Duplicate a form

POSThttps://formpik.com/api/v1/forms/{id}/duplicate

Copies the form's fields and settings into a new draft form, like Duplicate in the dashboard. Answers 201. The copy is not published and has no sources or flows. Counts toward the plan's forms. Needs a key with full or admin access.

Body

namestring
The copy's name. The original name with (copy) when left out.

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
How the share link page and embeds look: theme (light or dark), accent (a hex color), radius (none, sm, md, lg) and button_label.
pageobject
The share link: published, slug and indexable. See Publish a form.

Draft a form with AI

POSThttps://formpik.com/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 or admin 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.com/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. usage says how many of today's drafts are used and remaining, and resets_at when they come back. A draft AI could not finish is not counted, and the same request sent again within 10 minutes answers the same draft without using another one.