> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signup forms

> Create signup forms and popups, read their numbers, and sign people up from your own markup.

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](/selling/signup-forms).

<Note>
  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.
</Note>

## 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

```bash theme={"system"}
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):

```js theme={"system"}
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

```ts theme={"system"}
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" });
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.