# API overview

Everything you do in the dashboard, from your own code: send submissions, read, create, change, publish and delete forms, sources, flows, destinations and submissions, and with an admin key run the team, API keys, settings and billing. Every endpoint speaks JSON over HTTPS.

**On this page you will learn**

- The base address and every endpoint at a glance
- How to create an API key and send it
- The difference between read only and full access keys
- What requests, answers and errors look like
- How paging and rate limits work
- A quickstart that creates a form, connects it and sends a submission

## Base address

*Base URL*

```
https://formpik.com
```

Every path on these pages starts from this address. Only HTTPS is supported.

## Endpoints

| Method and path | What it does | Signs in with |
| --- | --- | --- |
| `POST /api/in/{key}` | [Send a submission to a form](https://formpik.com/docs/api/submit) | The source key in the path |
| `GET /api/v1/workspace` | [Read the workspace, its plan, limits and usage](https://formpik.com/docs/api/workspace#read) | Any API key |
| `PATCH /api/v1/workspace` | [Change the name, timezone and preferences](https://formpik.com/docs/api/workspace#update) | Admin key |
| `POST /api/v1/workspace/logo` | [Set the workspace logo](https://formpik.com/docs/api/workspace#logo) | Admin key |
| `DELETE /api/v1/workspace/logo` | [Remove the workspace logo](https://formpik.com/docs/api/workspace#logo) | Admin key |
| `GET /api/v1/stats` | [Read the overview numbers for 7 to 90 days](https://formpik.com/docs/api/workspace#stats) | Any API key |
| `GET /api/v1/permissions` | [List every permission a role can have](https://formpik.com/docs/api/roles#permissions) | Any API key |
| `GET /api/v1/roles` | [List roles, default and your own](https://formpik.com/docs/api/roles#list) | Any API key |
| `POST /api/v1/roles` | [Create a role](https://formpik.com/docs/api/roles#create) | Admin key |
| `GET /api/v1/roles/{id}` | [Read one role](https://formpik.com/docs/api/roles#one) | Any API key |
| `PATCH /api/v1/roles/{id}` | [Change a role and its permissions](https://formpik.com/docs/api/roles#update) | Admin key |
| `DELETE /api/v1/roles/{id}` | [Delete a role and move its people](https://formpik.com/docs/api/roles#delete) | Admin key |
| `GET /api/v1/forms` | [List forms with every field and setting](https://formpik.com/docs/api/forms#list) | Any API key |
| `POST /api/v1/forms` | [Create a form](https://formpik.com/docs/api/forms#create) | Full or admin key |
| `GET /api/v1/forms/{id}` | [Read one form](https://formpik.com/docs/api/forms#one) | Any API key |
| `PATCH /api/v1/forms/{id}` | [Change a form, its fields or its settings](https://formpik.com/docs/api/forms#update) | Full or admin key |
| `DELETE /api/v1/forms/{id}` | [Delete a form](https://formpik.com/docs/api/forms#delete) | Full or admin key |
| `POST /api/v1/forms/{id}/publish` | [Publish a form on its share link, with embed codes](https://formpik.com/docs/api/forms#publish) | Full or admin key |
| `POST /api/v1/forms/{id}/unpublish` | [Take the share link and embeds offline](https://formpik.com/docs/api/forms#unpublish) | Full or admin key |
| `POST /api/v1/forms/{id}/duplicate` | [Copy a form into a new draft](https://formpik.com/docs/api/forms#duplicate) | Full or admin key |
| `POST /api/v1/ai/form-draft` | [Draft a form or missing fields with AI](https://formpik.com/docs/api/forms#ai) | Full or admin key |
| `GET /api/v1/sources` | [List sources and their endpoint addresses](https://formpik.com/docs/api/sources#list) | Any API key |
| `POST /api/v1/sources` | [Connect a website to a form](https://formpik.com/docs/api/sources#create) | Full or admin key |
| `GET /api/v1/sources/{id}` | [Read one source](https://formpik.com/docs/api/sources#one) | Any API key |
| `PATCH /api/v1/sources/{id}` | [Change, pause or resume a source](https://formpik.com/docs/api/sources#update) | Full or admin key |
| `POST /api/v1/sources/{id}/rotate-key` | [Give a source a new endpoint address](https://formpik.com/docs/api/sources#rotate) | Full or admin key |
| `DELETE /api/v1/sources/{id}` | [Remove a source](https://formpik.com/docs/api/sources#delete) | Full or admin key |
| `GET /api/v1/flows` | [List flows with their steps](https://formpik.com/docs/api/flows#list) | Any API key |
| `POST /api/v1/flows` | [Create a flow](https://formpik.com/docs/api/flows#create) | Full or admin key |
| `GET /api/v1/flows/{id}` | [Read one flow and its go-live checks](https://formpik.com/docs/api/flows#one) | Any API key |
| `PATCH /api/v1/flows/{id}` | [Change a flow, take it live or pause it](https://formpik.com/docs/api/flows#update) | Full or admin key |
| `POST /api/v1/flows/{id}/test` | [Test a flow on sample answers](https://formpik.com/docs/api/flows#test) | Full or admin key |
| `POST /api/v1/flows/{id}/duplicate` | [Copy a flow into a new draft](https://formpik.com/docs/api/flows#duplicate) | Full or admin key |
| `DELETE /api/v1/flows/{id}` | [Delete a flow](https://formpik.com/docs/api/flows#delete) | Full or admin key |
| `GET /api/v1/destinations` | [List chat channels and webhooks](https://formpik.com/docs/api/destinations#list) | Any API key |
| `POST /api/v1/destinations` | [Connect a destination](https://formpik.com/docs/api/destinations#create) | Full or admin key |
| `GET /api/v1/destinations/{id}` | [Read one destination](https://formpik.com/docs/api/destinations#one) | Any API key |
| `PATCH /api/v1/destinations/{id}` | [Change a destination](https://formpik.com/docs/api/destinations#update) | Full or admin key |
| `DELETE /api/v1/destinations/{id}` | [Disconnect a destination](https://formpik.com/docs/api/destinations#delete) | Full or admin key |
| `GET /api/v1/submissions` | [List submissions, newest first](https://formpik.com/docs/api/submissions#list) | Any API key |
| `POST /api/v1/submissions/test` | [Send a test submission](https://formpik.com/docs/api/submissions#test) | Full or admin key |
| `GET /api/v1/submissions/{id}` | [Read one submission with its runs and files](https://formpik.com/docs/api/submissions#one) | Any API key |
| `PATCH /api/v1/submissions/{id}` | [Mark as spam or release](https://formpik.com/docs/api/submissions#spam) | Full or admin key |
| `POST /api/v1/submissions/{id}/rerun` | [Run flows again](https://formpik.com/docs/api/submissions#rerun) | Full or admin key |
| `GET /api/v1/submissions/{id}/files/{fileId}` | [Get a private link to an uploaded file](https://formpik.com/docs/api/submissions#files) | Any API key |
| `DELETE /api/v1/submissions/{id}` | [Delete a submission](https://formpik.com/docs/api/submissions#delete) | Full or admin key |
| `GET /api/v1/members` | [List the team and open invitations](https://formpik.com/docs/api/team#members) | Admin key |
| `GET /api/v1/members/{id}` | [Read one member with their role](https://formpik.com/docs/api/roles#member) | Admin key |
| `PATCH /api/v1/members/{id}` | [Change a member's role](https://formpik.com/docs/api/team#roles) | Admin key |
| `DELETE /api/v1/members/{id}` | [Remove someone from the team](https://formpik.com/docs/api/team#roles) | Admin key |
| `POST /api/v1/invitations` | [Invite someone by email](https://formpik.com/docs/api/team#invite) | Admin key |
| `POST /api/v1/invitations/{id}/resend` | [Send an invitation again](https://formpik.com/docs/api/team#resend) | Admin key |
| `DELETE /api/v1/invitations/{id}` | [Withdraw an invitation](https://formpik.com/docs/api/team#resend) | Admin key |
| `GET /api/v1/api-keys` | [List API keys](https://formpik.com/docs/api/team#keys) | Admin key |
| `POST /api/v1/api-keys` | [Create an API key](https://formpik.com/docs/api/team#keys) | Admin key |
| `DELETE /api/v1/api-keys/{id}` | [Revoke an API key](https://formpik.com/docs/api/team#keys) | Admin key |
| `GET /api/v1/connected-apps` | [List agent apps signed in with a link](https://formpik.com/docs/api/team#apps) | Admin key |
| `DELETE /api/v1/connected-apps/{id}` | [Disconnect an agent app](https://formpik.com/docs/api/team#apps) | Admin key |
| `GET /api/v1/billing` | [Read the plan, card, invoices and prices](https://formpik.com/docs/api/billing#read) | Admin key |
| `POST /api/v1/billing/checkout` | [Move to a paid plan, or change it](https://formpik.com/docs/api/billing#plan) | Admin key |
| `PATCH /api/v1/billing/subscription` | [Cancel the plan at period end, or keep it](https://formpik.com/docs/api/billing#cancel) | Admin key |
| `POST /api/v1/billing/portal` | [Get a billing portal link](https://formpik.com/docs/api/billing#portal) | Admin key |

The team, roles, API keys, workspace settings and billing need a key with admin access, so a read only or full access key that leaks can never bring someone in, change who does what, change your plan or make more keys. No key can delete the workspace or hand it over, and none gives a role more than its access allows.

## Authentication

1. **Open API keys**

   Open the workspace menu at the top of the sidebar and choose **API keys**. Owners, admins and roles with the API keys and apps permission can create and revoke keys.
2. **Create a key**

   Give it a name that says where it is used, such as `CRM sync`, and pick its access: read only, full or admin access. The full key, which starts with `fp_live_`, is shown **once**. Copy it into your server's secrets right away.
3. **Send it in a header**

   Send it as a bearer token in the `Authorization` header of every request.

*Header*

```
Authorization: Bearer fp_live_your_api_key
```

- Formpik stores only a SHA-256 hash of the key, never the key itself, so a lost key cannot be shown again. Create a new one and revoke the old one.
- The API keys page shows the last 4 characters of each key and when it was last used, so you can tell keys apart.
- A key belongs to one workspace and works on everything in it. Keep it on your server and never put it in a web page or a mobile app.
- On the submission endpoint a key is optional. With any key of the form's workspace, whatever its access, the request skips the allowed websites check and the bot check, which is what senders such as your backend need. A key of another workspace is refused with a `401`.
- Revoke a key on the API keys page and it stops working right away: requests with it get a `401` with the code `invalid-key`.

| Plan | API keys |
| --- | --- |
| Starter | 1 API key |
| Pro | 10 API keys |
| Max | Unlimited API keys |

## Access levels

Every key has one of three access levels. You pick it when you create the key, read only is the default, and it cannot change later: to give an integration more access, create a new key. Only owners and admins create keys.

| Access | What the key can do |
| --- | --- |
| Read only | Every `GET` endpoint except the admin ones, and sending submissions to the endpoint. Destination addresses show only their host, such as `https://hooks.slack.com/...`, and webhook signing secrets are `null`. Every `POST`, `PATCH` and `DELETE` under `/api/v1` answers `403` with the code `read-only-key`. |
| Full access | Everything above, plus creating, changing, duplicating and deleting forms, sources, flows and destinations, publishing forms on their share link, testing flows, sending test submissions, marking spam, running flows again and drafting forms with AI. It sees destination addresses and webhook signing secrets in full, like an admin. |
| Admin access | Everything above, plus what the Settings, Members, API keys and Plan and billing pages do: workspace settings, invitations, roles and who has them, removing members, API keys, connected apps and plan changes. Other keys answer `403` with the code `admin-key-required`. It can never delete the workspace or hand it over, which stays with the owner in the dashboard. |

*403 Forbidden*

```json
{
  "message": "This API key is read only. Create a key with full access on the API keys page to make changes.",
  "code": "read-only-key"
}
```

Use read only keys wherever your code only reads, such as a sync that copies submissions into your CRM or a report. Keep full access keys for the code that builds and runs your setup, and admin keys for the rare script that manages the team or billing, such as onboarding new clients of an agency.

## Requests and answers

- Send bodies as JSON with `Content-Type: application/json`. A body sent as plain text answers `415`, and a JSON list instead of an object answers `400`.
- Names use snake_case, such as `form_id` and `success_message`, in what you send and in what comes back.
- `PATCH` changes only the properties you send and keeps the rest.
- Answers are JSON objects with a `data` property: an object for one item, a list for several. Creating something answers `201`. Deleting answers `{ "ok": true, "id": "..." }`.
- Errors are JSON objects with a `message` you can show people and a `code` you can branch on. See [Errors and limits](https://formpik.com/docs/api/errors).
- Times are ISO 8601 in UTC, such as `2026-11-20T09:30:00.000Z`.
- Ids start with a prefix that says what they are, such as `frm_` for forms, `src_` for sources and `sub_` for submissions.
- Answers are never cached (`Cache-Control: no-store`), so you always read the current state. Changes made through the API show in the dashboard the next time it loads.

The submission endpoint is the one exception: it takes JSON, form posts and file uploads, and answers `{ "ok": ..., "message": ... }`. See [Send a submission](https://formpik.com/docs/api/submit).

## Paging

`GET /api/v1/submissions` returns up to 100 submissions per request, 50 by default, newest first. When a page is full, the answer carries `next_before`, the time of its oldest submission. Send it back as `before` to get the next page, and stop when `next_before` is `null`. See [Read every page](https://formpik.com/docs/api/submissions#paging). The other lists answer everything in one go.

## Rate limits

| What | Limit | Above it |
| --- | --- | --- |
| API requests | 120 a minute per API key, reads and changes together | 429 with Retry-After: 60 |
| AI form drafts | The daily drafts of your plan, shared with the dashboard, and 20 an hour per key | 429 |
| Submission endpoint | 120 posts a minute per address | 429 |
| Submissions per visitor | Set on each form, 30 an hour by default | 429 |
| Monthly submissions | Set by your plan | 429 |
| Forms, flows, sources and destinations | Set by your plan | 402 |

The minute limits count requests in the last 60 seconds, so they free up gradually. Refused requests do not count.

## Quickstart

Create a key with **full access**, put it in a `FORMPIK_API_KEY` environment variable, and run the steps below. They check the key, create a form, connect a source to it, send a submission and read it back. With a read only key, steps 1 and 5 work and steps 2 and 3 answer `403`.

*cURL*

```bash
# 1. Check the key: its workspace, plan, usage and access
curl "https://formpik.com/api/v1/workspace" \
  -H "Authorization: Bearer $FORMPIK_API_KEY"

# 2. Create a form (full access key)
curl -X POST "https://formpik.com/api/v1/forms" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contact", "fields": [{"key": "full_name", "label": "Full name", "type": "text", "required": true}, {"key": "email", "label": "Email", "type": "email", "required": true}, {"key": "topic", "label": "Topic", "type": "select", "options": ["Sales", "Support"]}]}'

# 3. Connect a source to it, with the form id from step 2.
#    The answer carries endpoint_url, the address to send submissions to.
curl -X POST "https://formpik.com/api/v1/sources" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form_id": "frm_q8w2e4r6t1", "name": "Website"}'

# 4. Send a submission to endpoint_url
curl -X POST "https://formpik.com/api/in/YOUR_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_name": "Jane Cooper", "email": "jane@example.com", "topic": "sales"}'

# 5. Read it back with its flow runs, with the id from step 4
curl "https://formpik.com/api/v1/submissions/sub_7k2m9x4q1w3e" \
  -H "Authorization: Bearer $FORMPIK_API_KEY"
```

*JavaScript*

```js
const BASE = "https://formpik.com"

// One helper for every call: JSON in, { data } out, { message, code } errors thrown
async function api(method, path, body) {
  const response = await fetch(`${BASE}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.FORMPIK_API_KEY}`,
      ...(body ? { "Content-Type": "application/json" } : {})
    },
    body: body ? JSON.stringify(body) : undefined
  })
  const json = await response.json()

  if (!response.ok) throw new Error(`${response.status} ${json.code}: ${json.message}`)

  return json
}

// 1. Check the key
const { data: workspace } = await api("GET", "/api/v1/workspace")
console.log(workspace.plan.name, workspace.key.access)

// 2. Create a form (full access key)
const { data: form } = await api("POST", "/api/v1/forms", {
  name: "Contact",
  fields: [
    { key: "full_name", label: "Full name", type: "text", required: true },
    { key: "email", label: "Email", type: "email", required: true },
    { key: "topic", label: "Topic", type: "select", options: ["Sales", "Support"] }
  ]
})

// 3. Connect a source, which gives the form its endpoint address
const { data: source } = await api("POST", "/api/v1/sources", { form_id: form.id, name: "Website" })

// 4. Send a submission. The endpoint answers { ok, id, message }
const sent = await fetch(source.endpoint_url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ full_name: "Jane Cooper", email: "jane@example.com", topic: "sales" })
}).then(response => response.json())

if (!sent.ok) throw new Error(sent.message)

// 5. Read it back. Flows run right after the answer, so wait a moment first.
await new Promise(resolve => setTimeout(resolve, 2000))

const { data: submission } = await api("GET", `/api/v1/submissions/${sent.id}`)
console.log(submission.status, submission.runs.length)
```

*Python*

```python
import os
import time

import requests

BASE = "https://formpik.com"
HEADERS = {"Authorization": f"Bearer {os.environ['FORMPIK_API_KEY']}"}

def api(method, path, body=None):
    response = requests.request(method, f"{BASE}{path}", headers=HEADERS, json=body, timeout=30)
    payload = response.json()

    if not response.ok:
        raise RuntimeError(f"{response.status_code} {payload['code']}: {payload['message']}")

    return payload

# 1. Check the key
workspace = api("GET", "/api/v1/workspace")["data"]
print(workspace["plan"]["name"], workspace["key"]["access"])

# 2. Create a form (full access key)
form = api("POST", "/api/v1/forms", {
    "name": "Contact",
    "fields": [
        {"key": "full_name", "label": "Full name", "type": "text", "required": True},
        {"key": "email", "label": "Email", "type": "email", "required": True},
        {"key": "topic", "label": "Topic", "type": "select", "options": ["Sales", "Support"]},
    ],
})["data"]

# 3. Connect a source, which gives the form its endpoint address
source = api("POST", "/api/v1/sources", {"form_id": form["id"], "name": "Website"})["data"]

# 4. Send a submission. The endpoint answers { ok, id, message }
sent = requests.post(
    source["endpoint_url"],
    json={"full_name": "Jane Cooper", "email": "jane@example.com", "topic": "sales"},
    timeout=30,
).json()

if not sent["ok"]:
    raise RuntimeError(sent["message"])

# 5. Read it back with its flow runs
time.sleep(2)
submission = api("GET", f"/api/v1/submissions/{sent['id']}")["data"]
print(submission["status"], len(submission["runs"]))
```

The new form has no flows yet, so the submission stays `received` with no runs. Add a flow in the app or with [POST /api/v1/flows](https://formpik.com/docs/api/flows#create) to route it somewhere.

> **Webhooks are the other half**
>
> To get submissions pushed to your server the moment they arrive, add a Send webhook step to a flow instead of polling. See [Webhooks](https://formpik.com/docs/webhooks).

> **Working with an AI agent?**
>
> The same keys connect Claude, Cursor and other MCP clients, and every endpoint above is a tool the agent can call. See [MCP server for AI agents](https://formpik.com/docs/mcp).

## Common questions

### Can I create forms and flows through the API?

Yes, with a full access key. Forms, sources, flows and destinations can be created, changed and deleted, and flows can be tested and taken live. A key with admin access also manages the team, roles, API keys, settings and billing.

### Which access should my key have?

Read only whenever your code only reads. A leaked read only key cannot change or delete anything and never shows webhook addresses or signing secrets. Use full access only where your code really builds or changes your setup.

### Can I call the API from a browser?

Not the `/api/v1` endpoints. They need an API key, and a key in a web page can be read by anyone. Call them from your server and pass on only what the page needs. Browsers post straight to the submission endpoint, without a key.

### Do API calls count toward my monthly submissions?

Reading and changing records does not. Every submission stored through the endpoint counts, whether it came from a browser or from your server with a key. Test submissions do not count.

### Do changes through the API respect my plan?

Yes. The API uses the same checks as the dashboard, so creating a form, flow, source or destination past your plan answers `402` with the code `plan-limit`. Check what is left first with [GET /api/v1/workspace](https://formpik.com/docs/api/workspace).

- [Send a submission](https://formpik.com/docs/api/submit): JSON, form posts and file uploads.
- [Forms](https://formpik.com/docs/api/forms): Create and change forms and their fields.
- [Flows](https://formpik.com/docs/api/flows): Build, test and take flows live.
- [Submissions](https://formpik.com/docs/api/submissions): List, page, read and run again.
- [Errors and limits](https://formpik.com/docs/api/errors): Every status, code and limit.

---

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