API reference
Submission and management API.
Authenticate with an account API key, then use the same operations that power the dashboard.
Authentication
Create an API key in the dashboard. Send it as a bearer token:
Authorization: Bearer <API_KEY>
Content-Type: application/jsonKeys are shown once at creation. Revoke a key from the dashboard when it is no longer needed. The public ingest endpoint does not use an API key; it is protected by the form id, origin allowlist, rate limits, and optional captcha.
Public ingest
| Method | Path | Purpose |
|---|---|---|
| POST | /f/:formId | Accept a form submission as urlencoded, JSON, or multipart. |
Forms
| Method | Path | Purpose |
|---|---|---|
| GET | /api/forms | List forms for the account. |
| POST | /api/forms | Create a form. |
| GET | /api/forms/:id | Read one form. |
| PATCH | /api/forms/:id | Update settings. |
| DELETE | /api/forms/:id | Delete a form. |
Submissions and deliveries
| Method | Path | Purpose |
|---|---|---|
| GET | /api/forms/:id/submissions | List submissions with pagination and status filter. |
| GET | /api/forms/:id/submissions.csv | Export submissions as CSV. |
| GET | /api/submissions/:id/deliveries | List delivery attempts for a submission. |
| POST | /api/submissions/:id/deliveries/retry | Re-queue failed delivery channels. |
Rules
| Method | Path | Purpose |
|---|---|---|
| GET | /api/forms/:id/rules | List rules. |
| POST | /api/forms/:id/rules | Create a require, block, spam, or route rule. |
| PATCH | /api/forms/:id/rules/:ruleId | Update a rule. |
| DELETE | /api/forms/:id/rules/:ruleId | Delete a rule. |
Webhooks
| Method | Path | Purpose |
|---|---|---|
| GET | /api/webhooks | List endpoints, optionally filtered by form. |
| POST | /api/webhooks | Create an HTTP, Discord, or Telegram endpoint. |
| PATCH | /api/webhooks/:id | Update URL, events, or active state. |
| DELETE | /api/webhooks/:id | Delete an endpoint. |
| GET | /api/webhooks/:id/deliveries | Inspect delivery attempts. |
| POST | /api/webhooks/deliveries/:deliveryId/replay | Replay an event. |
Suppressions and sending domains
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /api/suppressions | List or add suppressed addresses. |
| DELETE | /api/suppressions/:id | Remove a suppression. |
| GET / POST | /api/sending-domains | List or create BYO SMTP domains. |
| POST | /api/sending-domains/:id/verify | Run the TXT and SMTP verification. |
| POST | /api/sending-domains/:id/default | Make the domain the account default. |
| DELETE | /api/sending-domains/:id | Delete the domain. |
Verification status
Recipient verification is exposed at GET /api/verifications and POST /api/verifications/resend. The resend operation has a 60-second cooldown per recipient.
Idempotency
Send an Idempotency-Key header on ingest when a retry must not create a second submission. Reusing the same key returns the existing record instead of duplicating it.
Errors
Errors are JSON with an error code and, where relevant, a message or field list. Authentication failures return 401; validation failures return 422; rate limits return 429.
This reference reflects the current early-access build. Verify payload shapes in the dashboard or the source before relying on a field in production automation.
Put your forms on a backend that keeps a record.
Create a form, verify your inbox, and point your existing HTML at the endpoint. No server, no SDK, no rewrite.
POST https://freelyform.com/f/FORM_ID