REST API

Build with surveys.

A simple, public JSON API for creating surveys programmatically. No authentication required.

Overview

All API endpoints accept and return JSON. No authentication is required.

Base URL /api

Errors return an error string (single errors) or an errors array (validation failures), along with an appropriate HTTP status code.

POST /api/surveys.php

Create a new survey. Returns the survey ID and URL.

Request body

Field	Type	Required	Description
`title`	string	Yes	Survey title. Max 255 characters.
`expiration_days`	integer	Yes	How long the survey stays live. Must be `1`, `7`, or `31`.
`questions`	array	Yes	At least one question object (see below).
`show_on_home`	boolean	No	Feature the survey on the homepage. Defaults to `false`.

Question object

Field	Type	Required	Description
`label`	string	Yes	The question text. Max 255 characters.
`type`	string	Yes	One of `radio`, `checkbox`, `select`, `text_short`, `text_long`.
`choices`	string[]	Conditional	Required for `radio`, `checkbox`, and `select`. At least 2 non-empty strings.
`description`	string	No	Optional helper text shown below the question label.
`required`	boolean	No	Whether an answer is required. Defaults to `false`.

Question types

Type	Description
`radio`	Pick one answer from a list of radio buttons.
`select`	Pick one answer from a dropdown menu.
`checkbox`	Pick one or more answers from a list of checkboxes.
`text_short`	Single-line free text input.
`text_long`	Multi-line free text input.

Example request

curl

curl -X POST https://example.com/api/surveys.php \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Team Lunch Preferences",
  "expiration_days": 7,
  "questions": [
    {
      "label": "What cuisine do you prefer?",
      "type": "radio",
      "required": true,
      "choices": ["Italian", "Mexican", "Thai", "Other"]
    },
    {
      "label": "Any dietary restrictions?",
      "type": "text_short"
    }
  ]
}'

Responses

201 Created Survey created successfully.

JSON

{
  "id": "a1b2c3d4e5",
  "url": "https://surveys.darnfinesoftware.com/surveys.php?id=a1b2c3d4e5"
}

400 Bad Request Validation failed.

JSON

{
  "errors": [
    "title is required.",
    "questions[0].choices must contain at least 2 non-empty options."
  ]
}

400 Bad Request Malformed JSON body.

JSON

{ "error": "Invalid JSON body" }

405 Method Not Allowed Non-POST request.

JSON

{ "error": "Method not allowed" }