Forms

A form is a Shout survey, quiz or poll. These endpoints let you list forms, read a form’s full structure, and create new forms.

Reading requires the forms:read scope; creating requires forms:write.

List forms

GET /v1/forms

Query param	Description
`cursor`	Pagination cursor from a previous `nextCursor`.
`limit`	Page size, default 25, max 100.
`workspace_id`	Only forms in this workspace.
`updated_since`	Only forms changed at/after this ISO-8601 UTC timestamp.

curl "https://publicapi.shout.com/v1/forms?limit=2" \
  -H "Authorization: Bearer $SHOUT_API_KEY"

{
  "items": [
    {
      "id": "90751669-9ebc-4215-9321-538b6c9e29ac",
      "title": "Customer Feedback",
      "status": "active",
      "workspaceId": "34c78488-d53e-09bb-27b9-3a206f1f1ad7",
      "publishedAt": "2026-07-11T11:09:32Z",
      "updatedAt": "2026-07-11T00:00:00Z"
    }
  ],
  "nextCursor": "djE6OTIxOTA1"
}

status is "active" (live/collecting) or "inactive" (closed). Trashed forms are never returned.

Get a form

GET /v1/forms/{id}

Returns the form with its pages and questions.

curl "https://publicapi.shout.com/v1/forms/90751669-9ebc-4215-9321-538b6c9e29ac" \
  -H "Authorization: Bearer $SHOUT_API_KEY"

{
  "id": "90751669-9ebc-4215-9321-538b6c9e29ac",
  "title": "Customer Feedback",
  "status": "active",
  "workspaceId": "34c78488-d53e-09bb-27b9-3a206f1f1ad7",
  "publishedAt": "2026-07-11T11:09:32Z",
  "updatedAt": "2026-07-11T00:00:00Z",
  "description": "You can enter some introduction text here!",
  "pages": [
    {
      "id": 2503284,
      "index": 1,
      "title": "",
      "questions": [
        {
          "id": 7441598,
          "text": "<p>What is your favorite product feature?</p>",
          "description": null,
          "type": "choose_one",
          "position": 1
        },
        {
          "id": 7441601,
          "text": "<p>How likely are you to recommend Shout to a colleague?</p>",
          "description": null,
          "type": "likert",
          "position": 3
        }
      ]
    }
  ]
}

Notes:

Question text is stored as HTML (that’s how the builder saves it).
Page and question ids are integers; the form id is a UUID.
Use the question ids to match answers when reading responses.

Create a form

POST /v1/forms

Create a whole form — title, optional description/workspace, and its questions — in one atomic call. On success you get 201 Created, a Location: /v1/forms/{id} header, and the created form in the Get a form shape.

Provide questions either as a flat questions array (single-page shorthand) or as pages, each with its own questions. If both are given, pages wins.

Minimal example

curl -X POST "https://publicapi.shout.com/v1/forms" \
  -H "Authorization: Bearer $SHOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Feedback",
    "description": "Tell us what you think",
    "questions": [
      { "type": "choose_one", "text": "How did you hear about us?", "required": true,
        "options": ["Search", "A friend", "An ad"] },
      { "type": "nps", "text": "How likely are you to recommend us?" },
      { "type": "textbox", "text": "Any other feedback?", "rows": 3 }
    ]
  }'

Multi-page example

curl -X POST "https://publicapi.shout.com/v1/forms" \
  -H "Authorization: Bearer $SHOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Event Survey",
    "workspaceId": "34c78488-d53e-09bb-27b9-3a206f1f1ad7",
    "active": true,
    "pages": [
      {
        "title": "About you",
        "questions": [
          { "type": "contact_details", "text": "Your details",
            "contactFields": [
              { "field": "first_name", "visible": true },
              { "field": "email", "label": "Work email", "visible": true }
            ] }
        ]
      },
      {
        "title": "Your feedback",
        "questions": [
          { "type": "star_rating", "text": "Rate the venue", "maxStars": 5 },
          { "type": "date", "text": "When did you attend?" }
        ]
      }
    ]
  }'

Common question fields

Every question object takes these, regardless of type:

Field	Type	Notes
`type`	string	One of the type identifiers in the table below. Required.
`text`	string	The question text (simple HTML allowed).
`required`	boolean	Whether an answer is mandatory. Default `false`.
`friendlyId`	string	Optional uppercase snake_case id to reference the question in formulas.

Supported question types

19 types are supported. The type identifier is the value you send (and, for most types, the value you get back on read).

`type`	What it is	Key fields
`choose_one`	Single choice (radio)	`options` (≥2), `otherText`
`dropdown`	Single choice as a dropdown	`options` (≥2), `otherText`
`choose_any`	Multiple choice (checkboxes)	`options` (≥2), `otherText`, `minSelections`, `maxSelections`
`multi_dropdown`	Multiple choice as a dropdown	`options` (≥2), `otherText`, `minSelections`, `maxSelections`
`likert`	Opinion scale, shown as buttons	`scales` (`[{text, opposingText}]`), `scaleStart`, `scaleEnd`
`likert_slider`	Opinion scale, shown as a slider	`scales`, `scaleStart`, `scaleEnd`
`nps`	Net Promoter Score, 0–10	(no extra fields)
`binary`	Yes/No, True/False	`trueLabel`, `falseLabel`, `icon`
`star_rating`	Star rating	`maxStars` (default 5, max 10)
`textbox`	Free-text input	`rows`, `inputLimitation`
`matrix`	Rows rated against a shared scale	`rowHeadings` (≥1), `columnHeadings`, `lastColumnIsNotWeighted`
`ranking`	Drag-and-drop ordering	`rankOptions`
`contact_details`	Contact detail fields	`contactFields` (`[{field, label, visible}]`)
`date`	Single date	`datePlaceholder`, `collectTime`
`date_range`	A from/to date range	`startDatePlaceholder`, `endDatePlaceholder`, `collectTime`
`numeric`	Numeric value	(created with default numeric formatting)
`file_upload`	One or more upload slots	`fileUploadSlots` (labels, ≥1)
`signature`	Signature capture	(no extra fields)
`payment`	Stripe payment	`amount` (smallest currency unit, e.g. `1000` = $10.00), `currency` (ISO 4217), `formula`

Field details:

options — a JSON array of label strings. Choice questions need at least 2.
otherText — set it to add a free-text “other” option; omit for none.
scales — one or more { "text": "...", "opposingText": "..." } pairs (both ends required), e.g. {"text": "Very poor", "opposingText": "Excellent"}.
icon (binary) — thumbs (default), tick_cross, or faces.
contactFields[].field — one of: first_name, last_name, company, address_line_1, address_line_2, city, state, zip_code, country, email, phone_number. label is optional; visible defaults to false, so set it to true for fields you want shown.
inputLimitation (textbox) — restricts accepted input, e.g. Email or Telephone. Default is unrestricted.

Limits: a form may contain at most 200 questions.

Create errors

Status	When
`400 invalid_request`	Missing `title`, an unknown `type`, an unknown enum value (icon/contact field), or a structurally invalid question (e.g. fewer than 2 options). The message names the problem.
`422 unprocessable_entity`	The form couldn’t be assigned an owner (no billable user on the tenant).

Workspaces

Forms can be filed under a workspace. List them with:

GET /v1/workspaces

Requires forms:read. Small by nature, so returned unpaginated.

{
  "items": [
    { "id": "f14c391a-3d97-3f31-5351-3a206f2e410c", "name": "Marketing" },
    { "id": "34c78488-d53e-09bb-27b9-3a206f1f1ad7", "name": "Product" }
  ],
  "nextCursor": null
}