Skip to content

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

Base URL
https://formpik.com

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
PATCH /api/v1/workspaceChange the name, timezone and preferencesAdmin key
POST /api/v1/workspace/logoSet the workspace logoAdmin key
DELETE /api/v1/workspace/logoRemove the workspace logoAdmin key
GET /api/v1/statsRead the overview numbers for 7 to 90 daysAny API key
GET /api/v1/permissionsList every permission a role can haveAny API key
GET /api/v1/rolesList roles, default and your ownAny API key
POST /api/v1/rolesCreate a roleAdmin key
GET /api/v1/roles/{id}Read one roleAny API key
PATCH /api/v1/roles/{id}Change a role and its permissionsAdmin key
DELETE /api/v1/roles/{id}Delete a role and move its peopleAdmin key
GET /api/v1/formsList forms with every field and settingAny API key
POST /api/v1/formsCreate a formFull or admin key
GET /api/v1/forms/{id}Read one formAny API key
PATCH /api/v1/forms/{id}Change a form, its fields or its settingsFull or admin key
DELETE /api/v1/forms/{id}Delete a formFull or admin key
POST /api/v1/forms/{id}/publishPublish a form on its share link, with embed codesFull or admin key
POST /api/v1/forms/{id}/unpublishTake the share link and embeds offlineFull or admin key
POST /api/v1/forms/{id}/duplicateCopy a form into a new draftFull or admin key
POST /api/v1/ai/form-draftDraft a form or missing fields with AIFull or admin key
GET /api/v1/sourcesList sources and their endpoint addressesAny API key
POST /api/v1/sourcesConnect a website to a formFull or admin key
GET /api/v1/sources/{id}Read one sourceAny API key
PATCH /api/v1/sources/{id}Change, pause or resume a sourceFull or admin key
POST /api/v1/sources/{id}/rotate-keyGive a source a new endpoint addressFull or admin key
DELETE /api/v1/sources/{id}Remove a sourceFull or admin key
GET /api/v1/flowsList flows with their stepsAny API key
POST /api/v1/flowsCreate a flowFull or admin 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 or admin key
POST /api/v1/flows/{id}/testTest a flow on sample answersFull or admin key
POST /api/v1/flows/{id}/duplicateCopy a flow into a new draftFull or admin key
DELETE /api/v1/flows/{id}Delete a flowFull or admin key
GET /api/v1/destinationsList chat channels and webhooksAny API key
POST /api/v1/destinationsConnect a destinationFull or admin key
GET /api/v1/destinations/{id}Read one destinationAny API key
PATCH /api/v1/destinations/{id}Change a destinationFull or admin key
DELETE /api/v1/destinations/{id}Disconnect a destinationFull or admin key
GET /api/v1/submissionsList submissions, newest firstAny API key
POST /api/v1/submissions/testSend a test submissionFull or admin 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 or admin key
POST /api/v1/submissions/{id}/rerunRun flows againFull or admin 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 or admin key
GET /api/v1/membersList the team and open invitationsAdmin key
GET /api/v1/members/{id}Read one member with their roleAdmin key
PATCH /api/v1/members/{id}Change a member's roleAdmin key
DELETE /api/v1/members/{id}Remove someone from the teamAdmin key
POST /api/v1/invitationsInvite someone by emailAdmin key
POST /api/v1/invitations/{id}/resendSend an invitation againAdmin key
DELETE /api/v1/invitations/{id}Withdraw an invitationAdmin key
GET /api/v1/api-keysList API keysAdmin key
POST /api/v1/api-keysCreate an API keyAdmin key
DELETE /api/v1/api-keys/{id}Revoke an API keyAdmin key
GET /api/v1/connected-appsList agent apps signed in with a linkAdmin key
DELETE /api/v1/connected-apps/{id}Disconnect an agent appAdmin key
GET /api/v1/billingRead the plan, card, invoices and pricesAdmin key
POST /api/v1/billing/checkoutMove to a paid plan, or change itAdmin key
PATCH /api/v1/billing/subscriptionCancel the plan at period end, or keep itAdmin key
POST /api/v1/billing/portalGet a billing portal linkAdmin 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. 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.
  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, 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. 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, 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.
PlanAPI keys
Starter1 API key
Pro10 API keys
MaxUnlimited 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.

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