API reference
API overview
Everything you do in the dashboard, from your own code: send submissions, and read, create, change and delete forms, sources, flows, destinations and submissions. 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.modulify.websiteEvery 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 |
GET /api/v1/forms | List forms with every field and setting | Any API key |
POST /api/v1/forms | Create a form | Full access 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 access key |
DELETE /api/v1/forms/{id} | Delete a form | Full access key |
POST /api/v1/ai/form-draft | Draft a form or missing fields with AI | Full access 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 access key |
GET /api/v1/sources/{id} | Read one source | Any API key |
PATCH /api/v1/sources/{id} | Change, pause or resume a source | Full access key |
POST /api/v1/sources/{id}/rotate-key | Give a source a new endpoint address | Full access key |
DELETE /api/v1/sources/{id} | Remove a source | Full access key |
GET /api/v1/flows | List flows with their steps | Any API key |
POST /api/v1/flows | Create a flow | Full access 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 access key |
POST /api/v1/flows/{id}/test | Test a flow on sample answers | Full access key |
DELETE /api/v1/flows/{id} | Delete a flow | Full access key |
GET /api/v1/destinations | List chat channels and webhooks | Any API key |
POST /api/v1/destinations | Connect a destination | Full access key |
GET /api/v1/destinations/{id} | Read one destination | Any API key |
PATCH /api/v1/destinations/{id} | Change a destination | Full access key |
DELETE /api/v1/destinations/{id} | Disconnect a destination | Full access key |
GET /api/v1/submissions | List submissions, newest first | Any API key |
POST /api/v1/submissions/test | Send a test submission | Full access 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 access key |
POST /api/v1/submissions/{id}/rerun | Run flows again | Full access 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 access key |
Your team, billing and API keys stay in the dashboard on purpose, so a key that leaks can never invite people, change your plan or make more keys.
Authentication
- 01
Open API keys
Open the workspace menu at the top of the sidebar and choose API keys. Owners and admins 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 or full 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, read only or full 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 |
| Enterprise | Unlimited API keys |
Access levels
Every key has one of two 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.
| Access | What the key can do |
|---|---|
| Read only | Every GET endpoint, 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 and deleting forms, sources, flows and destinations, 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. |
{
"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.
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.modulify.website/api/v1/workspace" \
-H "Authorization: Bearer $FORMPIK_API_KEY"
# 2. Create a form (full access key)
curl -X POST "https://formpik.modulify.website/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.modulify.website/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.modulify.website/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.modulify.website/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.