API reference
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
https://formpik.comEvery 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 | The source key in the path |
GET /api/v1/workspace | Read the workspace, its plan, limits and usage | Any API key |
PATCH /api/v1/workspace | Change the name, timezone and preferences | Admin key |
POST /api/v1/workspace/logo | Set the workspace logo | Admin key |
DELETE /api/v1/workspace/logo | Remove the workspace logo | Admin key |
GET /api/v1/stats | Read the overview numbers for 7 to 90 days | Any API key |
GET /api/v1/permissions | List every permission a role can have | Any API key |
GET /api/v1/roles | List roles, default and your own | Any API key |
POST /api/v1/roles | Create a role | Admin key |
GET /api/v1/roles/{id} | Read one role | Any API key |
PATCH /api/v1/roles/{id} | Change a role and its permissions | Admin key |
DELETE /api/v1/roles/{id} | Delete a role and move its people | Admin key |
GET /api/v1/forms | List forms with every field and setting | Any API key |
POST /api/v1/forms | Create a form | Full or admin key |
GET /api/v1/forms/{id} | Read one form | Any API key |
PATCH /api/v1/forms/{id} | Change a form, its fields or its settings | Full or admin key |
DELETE /api/v1/forms/{id} | Delete a form | Full or admin key |
POST /api/v1/forms/{id}/publish | Publish a form on its share link, with embed codes | Full or admin key |
POST /api/v1/forms/{id}/unpublish | Take the share link and embeds offline | Full or admin key |
POST /api/v1/forms/{id}/duplicate | Copy a form into a new draft | Full or admin key |
POST /api/v1/ai/form-draft | Draft a form or missing fields with AI | Full or admin key |
GET /api/v1/sources | List sources and their endpoint addresses | Any API key |
POST /api/v1/sources | Connect a website to a form | Full or admin key |
GET /api/v1/sources/{id} | Read one source | Any API key |
PATCH /api/v1/sources/{id} | Change, pause or resume a source | Full or admin key |
POST /api/v1/sources/{id}/rotate-key | Give a source a new endpoint address | Full or admin key |
DELETE /api/v1/sources/{id} | Remove a source | Full or admin key |
GET /api/v1/flows | List flows with their steps | Any API key |
POST /api/v1/flows | Create a flow | Full or admin key |
GET /api/v1/flows/{id} | Read one flow and its go-live checks | Any API key |
PATCH /api/v1/flows/{id} | Change a flow, take it live or pause it | Full or admin key |
POST /api/v1/flows/{id}/test | Test a flow on sample answers | Full or admin key |
POST /api/v1/flows/{id}/duplicate | Copy a flow into a new draft | Full or admin key |
DELETE /api/v1/flows/{id} | Delete a flow | Full or admin key |
GET /api/v1/destinations | List chat channels and webhooks | Any API key |
POST /api/v1/destinations | Connect a destination | Full or admin key |
GET /api/v1/destinations/{id} | Read one destination | Any API key |
PATCH /api/v1/destinations/{id} | Change a destination | Full or admin key |
DELETE /api/v1/destinations/{id} | Disconnect a destination | Full or admin key |
GET /api/v1/submissions | List submissions, newest first | Any API key |
POST /api/v1/submissions/test | Send a test submission | Full or admin key |
GET /api/v1/submissions/{id} | Read one submission with its runs and files | Any API key |
PATCH /api/v1/submissions/{id} | Mark as spam or release | Full or admin key |
POST /api/v1/submissions/{id}/rerun | Run flows again | Full or admin key |
GET /api/v1/submissions/{id}/files/{fileId} | Get a private link to an uploaded file | Any API key |
DELETE /api/v1/submissions/{id} | Delete a submission | Full or admin key |
GET /api/v1/members | List the team and open invitations | Admin key |
GET /api/v1/members/{id} | Read one member with their role | Admin key |
PATCH /api/v1/members/{id} | Change a member's role | Admin key |
DELETE /api/v1/members/{id} | Remove someone from the team | Admin key |
POST /api/v1/invitations | Invite someone by email | Admin key |
POST /api/v1/invitations/{id}/resend | Send an invitation again | Admin key |
DELETE /api/v1/invitations/{id} | Withdraw an invitation | Admin key |
GET /api/v1/api-keys | List API keys | Admin key |
POST /api/v1/api-keys | Create an API key | Admin key |
DELETE /api/v1/api-keys/{id} | Revoke an API key | Admin key |
GET /api/v1/connected-apps | List agent apps signed in with a link | Admin key |
DELETE /api/v1/connected-apps/{id} | Disconnect an agent app | Admin key |
GET /api/v1/billing | Read the plan, card, invoices and prices | Admin key |
POST /api/v1/billing/checkout | Move to a paid plan, or change it | Admin key |
PATCH /api/v1/billing/subscription | Cancel the plan at period end, or keep it | Admin key |
POST /api/v1/billing/portal | Get a billing portal link | 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
- 01
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. - 02
Create a key
Give it a name that says where it is used, such asCRM sync, and pick its access: read only, full or admin access. The full key, which starts withfp_live_, is shown once. Copy it into your server's secrets right away. - 03
Send it in a header
Send it as a bearer token in theAuthorizationheader of every request.
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
401with the codeinvalid-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. |
{
"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 answers415, and a JSON list instead of an object answers400. - Names use snake_case, such as
form_idandsuccess_message, in what you send and in what comes back. PATCHchanges only the properties you send and keeps the rest.- Answers are JSON objects with a
dataproperty: an object for one item, a list for several. Creating something answers201. Deleting answers{ "ok": true, "id": "..." }. - Errors are JSON objects with a
messageyou can show people and acodeyou can branch on. See Errors and limits. - 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 andsub_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.
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. 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.
# 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"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 to route it somewhere.
Common questions
Can I create forms and flows through the API?
Which access should my key have?
Can I call the API from a browser?
/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?
Do changes through the API respect my plan?
402 with the code plan-limit. Check what is left first with GET /api/v1/workspace.