Signup forms - Pocketsflow Docs

A signup form is an inline form, slide-in or popup that creators embed on their own sites with one script tag. The API manages forms and reads their stats; two public endpoints serve the embed. Product guide: Signup forms.

Growth plan and above. POST /forms and editing with PATCH /forms/{id} answer 403 with code: FEATURE_LOCKED (and details.requiredPlan) on a plan without forms. Listing, reading, pausing (status: "paused"), archiving and deleting stay open.

Endpoints

Method	Endpoint	Operation ID	MCP tool
`GET`	`/forms`	`listSignupForms`	`list_signup_forms`
`POST`	`/forms`	`createSignupForm`	`create_signup_form`
`GET`	`/forms/{id}`	`getSignupForm`	`get_signup_form`
`PATCH`	`/forms/{id}`	`updateSignupForm`	`update_signup_form`
`DELETE`	`/forms/{id}`	`deleteSignupForm`	`delete_signup_form`
`GET`	`/forms/public/{id}`	`getPublicSignupForm`	— (public)
`POST`	`/forms/public/{id}/subscribe`	`subscribeWithSignupForm`	— (public)

Create a form

curl -X POST https://api.pocketsflow.com/forms \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blog exit popup",
    "type": "popup",
    "headline": "Wait, take the playbook with you",
    "buttonLabel": "Send it to me",
    "tags": ["blog"],
    "doubleOptIn": true,
    "trigger": { "exitIntent": true, "delaySeconds": 10 },
    "frequencyDays": 7
  }'

The response is the form with stats (views, signups, conversionRate in percent) and embed.script / embed.iframe, ready to paste. GET /forms/{id} adds daily: views and signups per UTC day for the last 30 days.

Field	Type	Notes
`name`	string ≤ 80	Required on create. Only you see it.
`type`	`inline` \| `slide_in` \| `popup`	Default `inline`.
`status`	`active` \| `paused`	A paused form renders nothing.
`headline`, `body`, `buttonLabel`, `placeholder`	string	Default copy per type when omitted.
`collectName`	boolean	Ask for a first name too.
`successHeadline`, `successMessage`	string	The thank-you state.
`leadMagnetProductId`	string \| null	One of your products, linked after signup.
`tags`	string[] ≤ 10	Added to everyone who signs up.
`doubleOptIn`	boolean	Confirmation email before joining.
`accentColor`	`#rrggbb`	Button colour.
`position`	`bottom_right` \| `bottom_left`	Slide-in corner.
`trigger`	`{ delaySeconds 0–120, scrollPercent 0–100, exitIntent }`	When a slide-in or popup shows.
`frequencyDays`	0–365	Days before showing again to someone who closed it.

Your own markup

Build your own form and post to the public endpoint (no API key, any origin, 10 signups per 15 minutes per IP):

await fetch(`https://api.pocketsflow.com/forms/public/${formId}/subscribe`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, name, company: "", elapsedMs }),
});
// → { "status": "subscribed", "leadMagnet": { "name": "…", "url": "…" } }
// → { "status": "confirm_email" } with double opt-in

company is a honeypot (leave it empty) and elapsedMs is how long the form was on screen; a filled honeypot or a submit under 1.5 seconds gets a success answer and is ignored. The answer never says whether the address was already subscribed.

SDK

const forms = await pocketsflow.signupForms.list();
const form = await pocketsflow.signupForms.create({ name: "Footer", type: "inline", tags: ["blog"] });
await pocketsflow.signupForms.update(form._id, { status: "paused" });