Surveys are a separate product from forms - multi-screen, conditional logic, scoring, partial-response resume. Same token model: bearer auth, ability gates, team-scoped.
Base URL: https://formspring.io/api/v1
| Method | Path | Ability |
|---|---|---|
| GET | /surveys |
surveys:read |
| POST | /surveys |
surveys:write |
| GET | /surveys/{survey} |
surveys:read |
| PUT | PATCH | /surveys/{survey} |
surveys:write |
| DELETE | /surveys/{survey} |
surveys:write |
| POST | /surveys/{survey}/publish |
surveys:write |
| POST | /surveys/{survey}/unpublish |
surveys:write |
Surveys require a paid plan. Free-plan tokens get 402 Surveys require a paid plan on every mutating call.
The {survey} path parameter accepts the survey's public_id (preferred) or its slug.
List surveys
GET /surveys
Returns up to 100 surveys for the current team, sorted by updated_at desc. Soft-deleted and archived surveys are excluded.
Response 200:
{
"data": [
{
"id": "sv_8XfP2k",
"name": "Customer feedback",
"slug": "customer-feedback",
"public_url": "https://frmsp.io/s/customer-feedback",
"is_published": true,
"published_at": "2026-05-10T14:32:00+00:00",
"submissions_count": 142,
"updated_at": "2026-05-15T09:18:00+00:00"
}
]
}
Create a survey
POST /surveys
Content-Type: application/json
{
"name": "Customer feedback",
"slug": "customer-feedback",
"template": "nps",
"fields": [
{ "type": "email", "label": "Work email", "required": true },
{ "type": "textarea", "label": "What could be better?" }
]
}
Fields:
namerequired - survey name (1-120 chars).slug- URL slug. Auto-generated when omitted.template- key from the survey template registry (nps,csat,lead-qualification, ...). Pre-fills fields/theme/settings.fields- explicit field schema. Overrides any template-supplied fields. The API stamps anid(fld_xxxxxxxx), normalizes type aliases (long_text→textarea,dropdown→select), and slugs missing names - so a bare LLM-shaped definition works.
A newly-created survey is draft unless its fields array is empty (an empty-shell survey auto-publishes for quick demos). Call /publish once content is ready.
Response 201: SurveyResource with is_published: false.
Show a survey
GET /surveys/{survey}
Includes the full field array, theme, settings, scoring config, and a submissions_count accessor. Encrypted columns (hcaptcha_secret, recaptcha_secret, akismet_key) are never returned; matching *_set booleans indicate whether a secret is configured.
Update a survey
PATCH /surveys/{survey}
Content-Type: application/json
{
"name": "Customer feedback (Q2)",
"fields": [
{ "type": "rating", "label": "Overall satisfaction", "required": true },
{ "type": "textarea", "label": "Anything else?" }
]
}
PUT and PATCH behave the same - every field is optional, omitted keys stay unchanged. Sending fields replaces the entire field array (and triggers a relational rebuild of survey_screens + survey_questions to keep them in lockstep).
Publish / unpublish
POST /surveys/{survey}/publish
POST /surveys/{survey}/unpublish
Publish sets published_at = now(). Unpublish sets published_at = null. While unpublished, the public /s/{slug} URL serves a 409 with a "not yet published" notice instead of accepting responses.
Delete a survey
DELETE /surveys/{survey}
Soft-deletes the survey AND clears published_at (defense-in-depth - any cached snapshot or MCP read tool sees "not live" immediately). The row stays recoverable from the dashboard's trash for the retention window; permanent purge happens through the admin panel.
Response 200: { "ok": true }
Analysis, trends, invitations and shared dashboards
These endpoints mirror the dashboard. Reads and runs need surveys:read, changes need surveys:write. Responses are wrapped in data. Sending, scans and reminders are queued. Concepts and behaviour are explained in the survey guides: crosstabs, response quality, trends, dashboards and invitations.
| Method | Path | Ability |
|---|---|---|
| GET | /surveys/{survey}/analysis/questions |
surveys:read |
| POST | /surveys/{survey}/analysis/crosstab |
surveys:read |
| POST | /surveys/{survey}/analysis/crosstab/export |
surveys:read |
| GET | POST | /surveys/{survey}/analysis/views |
surveys:read | surveys:write |
| GET | PATCH | DELETE | /surveys/{survey}/analysis/views/{view} |
surveys:read | surveys:write |
| GET | /surveys/{survey}/analysis/views/{view}/export |
surveys:read |
| GET | /surveys/{survey}/quality |
surveys:read |
| POST | /surveys/{survey}/quality/scan (202) |
surveys:write |
| PUT | /surveys/{survey}/quality/settings |
surveys:write |
| POST | /surveys/{survey}/quality/responses/{response} |
surveys:write |
| GET | POST | /surveys/{survey}/trends/concepts |
surveys:read | surveys:write |
| GET | /surveys/{survey}/trends, /surveys/{survey}/trends/export |
surveys:read |
| GET | POST | /surveys/{survey}/distribution/waves |
surveys:read | surveys:write |
| GET | PATCH | /surveys/{survey}/distribution/waves/{wave} |
surveys:read | surveys:write |
| POST | /surveys/{survey}/distribution/waves/{wave}/launch, /close, /send |
surveys:write |
| GET | POST | /surveys/{survey}/distribution/waves/{wave}/invitations |
surveys:read | surveys:write |
| POST | /surveys/{survey}/distribution/event |
surveys:write |
| GET | /survey-dashboards, /survey-dashboards/{dashboard}/sharing |
surveys:read |
| POST | /survey-dashboards/{dashboard}/shares, /shares/{share}/revoke |
surveys:write |
| POST | PATCH | /survey-dashboards/{dashboard}/reports, /reports/{report} |
surveys:write |
| POST | GET | /survey-dashboards/{dashboard}/snapshots, /snapshots/{snapshot}, /snapshots/{snapshot}/{pdf|csv} |
surveys:write | surveys:read |
{wave} is the wave number within the survey (1, 2, 3...). A crosstab request body takes row, column, missing (exclude or include), inclusion, statistics, basis and filters:
POST /surveys/{survey}/analysis/crosstab
Content-Type: application/json
{ "row": "plan", "column": "satisfaction", "statistics": true, "filters": { "date_from": "2026-01-01" } }
A wave import takes the addresses as text or as a list:
POST /surveys/{survey}/distribution/waves/1/invitations
Content-Type: application/json
{ "emails": "ada@example.com,Ada", "recipients": [{ "email": "grace@example.com", "name": "Grace" }] }
The response counts added, duplicates, invalid and suppressed addresses. A share link URL is returned once, when the link is created.
Response caps
A response cap stops a survey, or just counts, once enough matching responses are in ("stop after 200 answers"). Reads need surveys:read, changes need surveys:write.
| Method | Path | What it does |
|---|---|---|
| GET | /surveys/{survey}/quotas |
Lists the caps with how full each is (response_count, is_full, filled_at) and the survey's questions as fields a cap's conditions can use |
| POST | /surveys/{survey}/quotas |
Adds a cap. Accepts Idempotency-Key, so a retried call makes one cap |
| PATCH | /surveys/{survey}/quotas/{quota} |
Changes a cap; only the fields you send change |
| DELETE | /surveys/{survey}/quotas/{quota} |
Deletes a cap (queued, answers 202) |
POST /surveys/{survey}/quotas
Content-Type: application/json
{ "name": "Germany, first 200", "limit": 200, "action": "endSurvey", "logic": { "op": "and", "conditions": [{ "field": "country", "op": "equals", "value": "DE" }] } }
action is endSurvey (close the survey when the cap is full) or continueSurvey (keep collecting, just mark the cap full). limit is 1 to 10 000 000. logic is optional: without it every response counts; with it only responses whose answers match count, and field is the name of one of the survey's questions. A cap of another workspace's survey answers 404.
Errors
| Status | When | What to do |
|---|---|---|
| 402 | Team's plan doesn't include surveys | Upgrade in dashboard or use a different team |
| 403 | Token missing surveys:read/surveys:write |
Mint a token with the right ability |
| 404 | Survey doesn't belong to the calling team | Switch active team in the dashboard and mint a fresh token |
| 422 | Validation failure (e.g. unknown template, malformed field) | Check the response errors map |
See also
- Submissions → - surveys reuse the same submission model
- Tokens & abilities → - full ability catalogue
- MCP server → - the same operations available as agent tools
