Responses API

Retrieve and export form responses programmatically.

Base URL: https://forms.wtf/api/v1 Auth: Authorization: Bearer YOUR_API_KEY

---

List responses

GET /forms/:formId/responses

Returns all responses for a form, ordered by most recent first.

Response:

{
  "formId": "clxyz...",
  "formTitle": "DAO Contributor Survey",
  "total": 142,
  "responses": [
    {
      "id": "clresponse...",
      "walletAddress": "0xabc...def",
      "ensName": "vitalik.eth",
      "submittedAt": "2026-04-01T14:32:00.000Z",
      "answers": [
        {
          "question": "What is your name?",
          "type": "SHORT_TEXT",
          "value": "Alice"
        },
        {
          "question": "Rate your experience",
          "type": "RATING",
          "value": "5"
        }
      ]
    }
  ]
}

Response fields

Field	Type	Description
formId	string	The form's unique ID
formTitle	string	The form's title
total	number	Total number of responses
responses[].id	string	Response ID
responses[].walletAddress	string	Respondent's wallet address (or anon_<uuid> for anonymous)
responses[].ensName	string | null	Resolved ENS name, if available
responses[].submittedAt	ISO 8601	Timestamp of submission
responses[].answers	array	Array of answer objects
answers[].question	string	The question label
answers[].type	string	Question type (e.g. SHORT_TEXT, MULTIPLE_CHOICE)
answers[].value	string	The respondent's answer

Answer values by question type

Different question types store values in different formats:

Question type	Value format	Example
SHORT_TEXT, LONG_TEXT	Plain text	"Hello world"
EMAIL	Email address	"[email protected]"
NUMBER	Numeric string	"42"
DATE	Date string	"2026-04-01"
YES_NO	"Yes" or "No"	"Yes"
MULTIPLE_CHOICE, DROPDOWN	Selected option text	"Option A"
CHECKBOX	Comma-separated selections	"Option A, Option C"
RATING	"1" to "5"	"4"
OPINION_SCALE	"1" to "10"	"7"
NPS	"0" to "10"	"9"
LEGAL	"accepted"	"accepted"
WALLET_ADDRESS	Wallet address	"0xabc...def"
ENS_NAME	ENS name or text	"vitalik.eth"
URL	URL string	"https://example.com"
PHONE	Phone number	"[phone]"

Display-only types (WELCOME_SCREEN, STATEMENT, END_SCREEN) do not produce answers.

---

Export responses

GET /forms/:formId/export?format=csv

Downloads responses as a file.

Query parameters:

Param	Values	Description
format	csv, json, merkle	Export format

• csv — Comma-separated values with a header row. Columns: Submitted At, then each question label in order.

• json — JSON array of response objects (same structure as the list endpoint).

• merkle — Merkle tree export for on-chain verification. Requires Business plan.

Example:

curl "https://forms.wtf/api/v1/forms/clxyz.../export?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output responses.csv

---

Unique constraint

Each wallet address can submit only one response per form. If the same wallet submits again, the previous response is replaced (old answers deleted, new answers saved).

Anonymous respondents receive a unique anon_<uuid> identifier stored in their browser, so each device gets its own response.

---

Examples

Fetch and filter responses by date

const res = await fetch(
  `https://forms.wtf/api/v1/forms/${FORM_ID}/responses`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { responses } = await res.json();

// Filter to last 24 hours client-side
const cutoff = new Date(Date.now() - 86400000);
const recent = responses.filter(
  r => new Date(r.submittedAt) > cutoff
);

Build a response summary

const { responses, total } = await res.json();

console.log(`Total responses: ${total}`);
for (const r of responses) {
  console.log(`${r.ensName || r.walletAddress} — ${r.submittedAt}`);
  for (const a of r.answers) {
    console.log(`  ${a.question}: ${a.value}`);
  }
}

Paginate through all responses

async function getAllResponses(formId) {
  let offset = 0;
  const all = [];

  while (true) {
    const res = await fetch(
      `https://forms.wtf/api/v1/forms/${formId}/responses?limit=100&offset=${offset}`,
      { headers: { Authorization: `Bearer ${API_KEY}` } }
    );
    const { responses, hasMore } = await res.json();
    all.push(...responses);
    if (!hasMore) break;
    offset += 100;
  }

  return all;
}