# 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

`GET https://formpik.com/api/v1/forms`

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

## Read one form

`GET https://formpik.com/api/v1/forms/{id}`

*200 OK*

```json
{
  "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

`POST https://formpik.com/api/v1/forms`

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

**Body**

- `name` (string, required): Up to 120 characters.
- `description` (string): Up to 500 characters.
- `status` (string): `active` (the default), `paused` or `draft`. Only active forms take submissions.
- `fields` (array): The fields in order. See Fields. Leave it out for an empty form.
- `settings` (object): Any of the settings shown above. Leave out what you do not want to change. See Settings.

*cURL*

```bash
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

`PATCH https://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*

```bash
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*

```json
{
  "data": { "id": "frm_q8w2e4r6t1", "status": "paused", "...": "..." },
  "flows_updated": 0
}
```

## Delete a form

`DELETE https://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*

```json
{ "ok": true, "id": "frm_q8w2e4r6t1" }
```

## Publish a form

`POST https://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**

- `slug` (string): 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`.
- `indexable` (boolean): Let search engines list the page. `false` by default, so only people with the link find it.

*cURL*

```bash
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*

```json
{
  "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

`POST https://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*

```json
{
  "data": { "id": "frm_q8w2e4r6t1", "share_url": null, "...": "..." },
  "published": false,
  "share_url": null,
  "embed": null
}
```

## Duplicate a form

`POST https://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**

- `name` (string): 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.

- `type` (string, required): 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](https://formpik.com/docs/field-types).
- `id` (string): Only to keep an existing field when you change a form.
- `label` (string): The question. For a text block, the text itself.
- `key` (string): The name websites send the answer under. Letters, numbers, `_`, `-` and `.`. Made from the label when left out, and unique within the form.
- `required` (boolean): Whether a submission needs an answer. Layout blocks and hidden fields are never required.
- `placeholder, help_text, default_value` (string): The hint inside the input, the line under it, and the starting answer.
- `options` (array): 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.
- `validation` (object): 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](https://formpik.com/docs/field-types#rules) for every rule and the types that take it.
- `step` (number): Sliders: the size of one step.
- `low_label, high_label` (string): Opinion scales: the words under the two ends.
- `currency` (string): Amounts: an ISO code such as `USD` or `EUR`.
- `multiple, accept` (boolean, string): File uploads: allow several files, and the types to offer, such as `.pdf,image/*`.

## Settings

- `after_submit` (string): `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_message` (string): What people see after sending, and while they wait to go on to a page.
- `error_message` (string): Shown instead of the exact reason when a submission is refused. Empty shows the reason.
- `redirect_url` (string): The page for `redirect`. Answers in double curly braces after the website address, such as `?name={{name}}`, are filled in for each visitor.
- `redirect_rules` (object[]): 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_delay` (number): Seconds the success message shows before going to a page: `0`, `3` or `5`.
- `allowed_domains` (string[]): Websites browsers may post from. Empty allows any.
- `honeypot` (boolean): The `_gotcha` spam trap.
- `captcha` (string): `off`, `turnstile` or `recaptcha`.
- `rate_limit_per_hour` (number): Submissions one visitor may send an hour. 0 for no limit.
- `retention_days` (number): How long submissions are kept. `0` keeps them forever. Values above your plan are lowered to its limit.
- `learn_fields` (boolean): Add fields the form does not know yet when a website sends them.
- `embed` (object): How the share link page and embeds look: `theme` (`light` or `dark`), `accent` (a hex color), `radius` (`none`, `sm`, `md`, `lg`) and `button_label`.
- `page` (object): The share link: `published`, `slug` and `indexable`. See Publish a form.

## Draft a form with AI

`POST https://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**

- `prompt` (string, required): What the form is for, in a sentence or two. Up to 1,500 characters.
- `form_id` (string): Draft only the fields missing from this form.

*cURL*

```bash
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.

---

Source: https://formpik.com/docs/api/forms
