Forms API

Manage your forms programmatically.

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

---

List forms

GET /forms

Returns all forms owned by the authenticated user (personal + team forms).

Response:

{
  "forms": [
    {
      "id": "clxyz...",
      "title": "DAO Contributor Survey",
      "slug": "dao-survey",
      "published": true,
      "responseCount": 142,
      "createdAt": "2026-03-01T10:00:00.000Z",
      "updatedAt": "2026-04-01T09:00:00.000Z"
    }
  ]
}

---

Get a form

GET /forms/:id

Returns full form details including questions and gate rules.

Response:

{
  "id": "clxyz...",
  "title": "DAO Contributor Survey",
  "slug": "dao-survey",
  "published": true,
  "questions": [
    {
      "id": "q_abc",
      "type": "SHORT_TEXT",
      "label": "What is your name?",
      "required": true,
      "order": 0
    }
  ],
  "gateRules": []
}

---

Get form responses

GET /forms/:id/responses

Returns all responses for the form, with answers.

Query parameters:

Param	Type	Description
limit	number	Max responses to return (default: 100, max: 1000)
offset	number	Pagination offset
since	ISO date	Only responses submitted after this date

Response:

{
  "responses": [
    {
      "id": "clresponse...",
      "walletAddress": "0xabc...def",
      "ensName": "vitalik.eth",
      "submittedAt": "2026-04-01T14:32:00.000Z",
      "durationSeconds": 87,
      "answers": [
        {
          "questionId": "q_abc",
          "questionLabel": "What is your name?",
          "value": "Alice"
        }
      ]
    }
  ],
  "total": 142,
  "hasMore": true
}

---

Export responses

GET /forms/:id/export

Query parameters:

Param	Values	Description
format	csv, json, merkle	Export format (merkle requires Business plan)

Returns the file as a download.

---

Examples

Fetch all responses and process them

const API_KEY = 'your_api_key';
const FORM_ID = 'clxyz...';

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

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

  return allResponses;
}

Get new responses since yesterday

const yesterday = new Date(Date.now() - 86400000).toISOString();

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

Export as CSV

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