Forms
Create, read, update, archive, publish, and permanently delete forms. All endpoints require a bearer token.
Base URL: https://formspring.io/api/v1
| Method | Path | Ability |
|---|---|---|
| GET | /forms |
forms:read |
| POST | /forms |
forms:write |
| GET | /forms/{form} |
forms:read |
| PUT | /forms/{form} |
forms:write |
| DELETE | /forms/{form} |
forms:write |
| POST | /forms/{form}/publish |
forms:write |
| POST | /forms/{form}/unpublish |
forms:write |
| POST | /forms/{form}/restore |
forms:write |
| DELETE | /forms/{form}/force |
forms:write (owner only) |
| POST | /forms/{form}/autoresponder/test |
forms:test-email |
| POST | /forms/{form}/notifications/test |
forms:test-email |
List forms
GET /forms?per_page=25
Returns paginated forms scoped to the current team. Default page size is 25, max is 100.
Response 200:
{
"data": [
{ "id": "frm_01H...", "name": "Contact form", "slug": "contact", "published_at": "2026-01-12T09:00:00Z", "archived_at": null, ... }
],
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
"meta": { "current_page": 1, "per_page": 25, "total": 47 }
}
Create a form
POST /forms
Content-Type: application/json
{
"name": "Contact form",
"slug": "contact",
"redirect_url": "https://example.com/thanks",
"notification_emails": ["ops@example.com"]
}
name is the only required field. slug is auto-generated from the name if omitted. notification_emails is an array (max 10).
Response 201: FormResource shape, including the form ID and the public submission URL https://formspring.io/f/{slug}.
Show a form
GET /forms/{form}
{form} accepts the form ID (frm_...) or the slug. Returns the full FormResource including spam settings, autoresponder config, and counts.
Update a form
PUT /forms/{form}
Content-Type: application/json
Send only the fields you want to change. Omitted fields are left untouched. Available fields: name, slug, redirect_url, notification_emails, honeypot_field, recaptcha_*, hcaptcha_*, akismet_*, custom_rules, autoresponder, moderation_threshold, plus any fields visible on the form's edit page.
Response 200: updated FormResource.
Archive a form
DELETE /forms/{form}
Soft-delete. The form stops accepting submissions, disappears from the default list, and remains restorable for 30 days. Existing submissions are preserved.
Response 200: {"ok": true}
Publish / unpublish
POST /forms/{form}/publish
POST /forms/{form}/unpublish
Toggle whether the form's public submission URL accepts requests. An unpublished form returns 403 Forbidden to public submissions but stays in the dashboard.
Response 200: FormResource with the new published_at.
Restore an archived form
POST /forms/{form}/restore
Reverses a DELETE /forms/{form}. Only works within the 30-day soft-delete window. After 30 days, the form is permanently purged and restore returns 404 Not Found.
Response 200: restored FormResource.
Force delete
DELETE /forms/{form}/force
Owner-only. Permanently deletes the form, all submissions, all webhooks, all uploaded files. No recovery. Always confirm with the user before calling this — admins cannot do it via API or UI for exactly this reason.
Response 200: {"ok": true}
Send a test autoresponder
POST /forms/{form}/autoresponder/test
Content-Type: application/json
{
"from_name": "Florian",
"subject": "Thanks for reaching out",
"body_md": "Hi {{ name }}, ..."
}
Sends a one-off rendering of the autoresponder to the caller's account email so you can preview formatting. Doesn't save the draft to the form.
Response 200: {"ok": true}
Send a test notification
POST /forms/{form}/notifications/test
Sends a sample notification email to every address on the form's notification_emails list. Useful for verifying delivery and DKIM/SPF setup.
Response 200: {"ok": true}
Common errors
| Status | Meaning |
|---|---|
400 |
Validation error (e.g. invalid email in notification_emails) |
401 |
Token missing or invalid |
402 |
API not available on free plan |
403 |
Token lacks required ability, or force called by non-owner |
404 |
Form not found in current team, or restore window expired |
429 |
API rate limit hit |