Skip to content

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

Base URL
https://formpik.modulify.website

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

Endpoints

Method and pathWhat it doesSigns in with
POST /api/in/{key}Send a submission to a formThe source key in the path
GET /api/v1/workspaceRead the workspace, its plan, limits and usageAny API key
GET /api/v1/formsList forms with every field and settingAny API key
POST /api/v1/formsCreate a formFull access key
GET /api/v1/forms/{id}Read one formAny API key
PATCH /api/v1/forms/{id}Change a form, its fields or its settingsFull access key
DELETE /api/v1/forms/{id}Delete a formFull access key
POST /api/v1/ai/form-draftDraft a form or missing fields with AIFull access key
GET /api/v1/sourcesList sources and their endpoint addressesAny API key
POST /api/v1/sourcesConnect a website to a formFull access key
GET /api/v1/sources/{id}Read one sourceAny API key
PATCH /api/v1/sources/{id}Change, pause or resume a sourceFull access key
POST /api/v1/sources/{id}/rotate-keyGive a source a new endpoint addressFull access key
DELETE /api/v1/sources/{id}Remove a sourceFull access key
GET /api/v1/flowsList flows with their stepsAny API key
POST /api/v1/flowsCreate a flowFull access key
GET /api/v1/flows/{id}Read one flow and its go-live checksAny API key
PATCH /api/v1/flows/{id}Change a flow, take it live or pause itFull access key
POST /api/v1/flows/{id}/testTest a flow on sample answersFull access key
DELETE /api/v1/flows/{id}Delete a flowFull access key
GET /api/v1/destinationsList chat channels and webhooksAny API key
POST /api/v1/destinationsConnect a destinationFull access key
GET /api/v1/destinations/{id}Read one destinationAny API key
PATCH /api/v1/destinations/{id}Change a destinationFull access key
DELETE /api/v1/destinations/{id}Disconnect a destinationFull access key
GET /api/v1/submissionsList submissions, newest firstAny API key
POST /api/v1/submissions/testSend a test submissionFull access key
GET /api/v1/submissions/{id}Read one submission with its runs and filesAny API key
PATCH /api/v1/submissions/{id}Mark as spam or releaseFull access key
POST /api/v1/submissions/{id}/rerunRun flows againFull access key
GET /api/v1/submissions/{id}/files/{fileId}Get a private link to an uploaded fileAny API key
DELETE /api/v1/submissions/{id}Delete a submissionFull 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

  1. 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.
  2. 02

    Create a key

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

    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, 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 401 with the code invalid-key.
PlanAPI keys
Starter1 API key
Pro10 API keys
EnterpriseUnlimited 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.

AccessWhat the key can do
Read onlyEvery 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 accessEverything 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.
403 Forbidden
{
  "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 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.
  • 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.

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

WhatLimitAbove it
API requests120 a minute per API key, reads and changes together429 with Retry-After: 60
AI form draftsThe daily drafts of your plan, shared with the dashboard, and 20 an hour per key429
Submission endpoint120 posts a minute per address429
Submissions per visitorSet on each form, 30 an hour by default429
Monthly submissionsSet by your plan429
Forms, flows, sources and destinationsSet by your plan402

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
# 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?
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. Only the team, billing and API keys stay in the dashboard.
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.