All docs

API reference: Surveys

Every Surveys endpoint, request shapes, and status codes.

Updated . 7 min read.

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

http
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:

json
{
  "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

http
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:

  • name required - 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 an id (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

http
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

http
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

http
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

http
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:

http
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:

http
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)
http
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