BUbuttondown
Surveys

Create Survey

Changed on

Create a new survey

post/surveys

Request

  • Base URL
    https://api.buttondown.com/v1
  • URL
    https://api.buttondown.com/v1/surveys
  • Auth
    API key in header Authorization

Request body

identifierstring required

A newsletter-scoped slug used to reference this survey when embedding it in emails.

questionstring required

The survey question shown to subscribers.

answersstring[] required

The list of pre-defined answer choices. Order is preserved unless randomize_answers is true.

notesstring

Internal notes about the survey. Not shown to subscribers.

response_cadence'once' | 'once_per_email'

An enumeration.

is_freeform_response_enabledboolean

If true, subscribers can provide a freeform text response in addition to (or instead of) picking from answers.

input_type'radio' | 'checkbox' | 'text'

An enumeration.

randomize_answersboolean

If true, the order of answers is shuffled each time the survey is rendered.

Example request

{
  "identifier": "color",
  "question": "What's your favorite color?",
  "answers": [
    "Red",
    "Green",
    "Blue"
  ]
}

Response

Created

idstring required

A unique TypeID associated with the object.

creation_datestring date-time required

The date and time at which the object was first created.

identifierstring required

A newsletter-scoped slug used to reference this survey when embedding it in emails.

questionstring required

The survey question shown to subscribers.

response_countinteger required

The total number of responses this survey has received.

answersstring[] required

The list of pre-defined answer choices. Order is preserved unless randomize_answers is true.

notesstring required

Internal notes about the survey. Not shown to subscribers.

randomize_answersboolean required

If true, the order of answers is shuffled each time the survey is rendered.

response_cadence'once' | 'once_per_email' required

An enumeration.

status'active' | 'inactive' required

An enumeration.

is_freeform_response_enabledboolean required

If true, subscribers can provide a freeform text response in addition to (or instead of) picking from answers.

input_type'radio' | 'checkbox' | 'text' required

An enumeration.

Changes

  • 3ce442cb155bRevision changes
    • warning

      changed the pattern of the request property from ^[a-zA-Z0-9_-]+$ to ^[A-Za-z0-9][A-Za-z0-9_]*$

  • bed30b2b43bcRevision changes
    • warning

      changed the pattern of the request property / from ^[ -~]*[A-Za-z0-9][ -~]*$ to ^[^\x00-\x1f\x7f-\x9f]*[^\W_][^\x00-\x1f\x7f-\x9f]*$

    • warning

      changed the pattern of the request property from ^[ -~]*[A-Za-z0-9][ -~]*$ to ^[^\x00-\x1f\x7f-\x9f]*[^\W_][^\x00-\x1f\x7f-\x9f]*$