# Form Plume API

Automate forms, submissions, delivery settings, integrations, analytics, and usage over a JSON REST API described by OpenAPI.

Use the API to automate forms, submissions, delivery settings, integrations, analytics, and usage. Billing, organization membership, invitations, and API key management remain dashboard-session-only. Give an AI coding assistant the [`form-plume-api` skill](https://formplume.com/skills/form-plume-api/SKILL.md), or use the [MCP server](/docs/api/mcp) if you prefer ready-made agent tools.

The API skill is for authenticated workspace automation. If you are only building a form that sends visitor submissions, use the [form-building skill](https://formplume.com/SKILL.md) and the public form endpoint instead; you do not need an organization API key.

Use it to:

- Create and configure [forms](/docs/quickstart)
- Read and act on submissions
- Manage [webhooks](/docs/integrations/webhooks) and [integrations](/docs/integrations)
- Tune [spam protection](/docs/spam-protection)
- Run [data requests](/docs/submissions/data-requests)
- Read analytics and usage

Authenticate with an organization [API key](/docs/api/authentication) and try these three requests:

```bash
# Who am I?
curl -s https://api.formplume.com/v1/api-keys/current \
  -H "Authorization: Bearer $FORMPLUME_API_KEY"

# Create a form
curl -s -X POST https://api.formplume.com/v1/forms \
  -H "Authorization: Bearer $FORMPLUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contact", "emoji": "📬"}'

# Read submissions
curl -s "https://api.formplume.com/v1/forms/FORM_ID/submissions?status=received" \
  -H "Authorization: Bearer $FORMPLUME_API_KEY"
```

> Need the OpenAPI spec? Open [`/v1/openapi.json`](https://api.formplume.com/v1/openapi.json)

## What the API covers

- **Forms and submissions:** manage forms, settings, submissions, files, and exports.
- **Delivery and automation:** configure email, autoresponders, [webhooks](/docs/integrations/webhooks), and [integrations](/docs/integrations).
- **Protection and reporting:** manage [spam protection](/docs/spam-protection), analytics, and usage.

## Conventions

- **Field names** are snake_case in requests and responses.
- **Errors** use one JSON envelope with a stable machine-readable code.
  Validation failures name the exact field that was rejected. See
  [Errors](/docs/api/errors).
- **Pagination**: list endpoints that paginate take `?cursor=` and return
  `next_cursor`, which is `null` on the last page. The cursor is opaque.
  Pass it back verbatim.
- **Timestamps** are RFC 3339 UTC strings. IDs are short opaque strings.
- **Enums**: every accepted value is listed in the OpenAPI spec with a
  description. Submission statuses are `received`, `spam`, `verified`, and
  `archived`. Bulk actions are `mark_spam`, `mark_verified`,
  `mark_received`, `archive`, `delete`, `restore`, and `redeliver`.

Unknown top-level fields in a request body are rejected, so typos fail
loudly. Inside `settings`, unknown keys in the typed sections (spam,
rate_limit, privacy, email, retention) are dropped. Unknown top-level
settings keys are preserved for forward compatibility.

> The API is separate from the submission endpoint your forms post to. Form
>   submissions go to `POST /f/{public_slug}` without an API key, as described
>   in the [quickstart](/docs/quickstart). They are governed by per-form
>   [submission rate limits](/docs/spam-protection/rate-limits), not the
>   [API rate limit](/docs/api/rate-limits).