API Documentation

Authorization: Bearer fl_your_api_key_here

curl https://formslist.com/api/v1/forms \
  -H "Authorization: Bearer fl_live_a1b2c3d4e5f6"

const response = await fetch('https://formslist.com/api/v1/forms', {
  headers: {
    'Authorization': 'Bearer fl_live_a1b2c3d4e5f6',
    'Content-Type': 'application/json',
  },
});

const { data } = await response.json();
console.log(data); // Array of forms

import requests

headers = {"Authorization": "Bearer fl_live_a1b2c3d4e5f6"}
response = requests.get("https://formslist.com/api/v1/forms", headers=headers)

data = response.json()["data"]
print(data)  # List of forms

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 42,
    "total_pages": 2
  }
}

{
  "error": "Missing or invalid Authorization header"
}

curl https://formslist.com/api/v1/forms \
  -H "Authorization: Bearer fl_live_a1b2c3d4e5f6"

{
  "data": [
    {
      "id": "frm_8kTn2xLm",
      "name": "Contact Form",
      "hash": "abc123def",
      "endpoint": "/f/abc123def",
      "submission_count": 47,
      "is_active": true,
      "created_at": "2026-03-15T10:30:00Z"
    }
  ],
  "meta": { "total": 1 }
}

curl -X POST https://formslist.com/api/v1/forms \
  -H "Authorization: Bearer fl_live_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contact Form", "description": "Main site contact"}'

{
  "data": {
    "id": "frm_9pQr3yMn",
    "name": "Contact Form",
    "hash": "xyz789abc",
    "endpoint": "/f/xyz789abc",
    "is_active": true,
    "created_at": "2026-03-22T14:00:00Z"
  }
}

curl https://formslist.com/api/v1/forms/frm_8kTn2xLm \
  -H "Authorization: Bearer fl_live_a1b2c3d4e5f6"

curl -X PATCH https://formslist.com/api/v1/forms/frm_8kTn2xLm \
  -H "Authorization: Bearer fl_live_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Contact Form", "is_active": false}'

curl -X DELETE https://formslist.com/api/v1/forms/frm_8kTn2xLm \
  -H "Authorization: Bearer fl_live_a1b2c3d4e5f6"

{
  "data": { "deleted": true }
}

curl "https://formslist.com/api/v1/forms/frm_8kTn2xLm/submissions?page=1&per_page=50" \
  -H "Authorization: Bearer fl_live_a1b2c3d4e5f6"

{
  "data": [
    {
      "id": "sub_4jKp7rWs",
      "data": {
        "name": "Sarah Chen",
        "email": "sarah@example.com",
        "message": "Interested in your Pro plan. Can we schedule a demo?"
      },
      "is_spam": false,
      "created_at": "2026-03-22T09:15:00Z"
    },
    {
      "id": "sub_2mNq9tYu",
      "data": {
        "name": "Marcus Rivera",
        "email": "marcus@agency.co",
        "message": "We build 20+ client sites per year. Is there an agency plan?"
      },
      "is_spam": false,
      "created_at": "2026-03-21T16:42:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 47,
    "total_pages": 1
  }
}

curl https://formslist.com/api/v1/submissions/sub_4jKp7rWs \
  -H "Authorization: Bearer fl_live_a1b2c3d4e5f6"

{
  "data": {
    "id": "sub_4jKp7rWs",
    "form_id": "frm_8kTn2xLm",
    "data": {
      "name": "Sarah Chen",
      "email": "sarah@example.com",
      "message": "Interested in your Pro plan."
    },
    "metadata": {
      "ip": "203.0.113.42",
      "country": "US",
      "city": "San Francisco",
      "user_agent": "Mozilla/5.0...",
      "utm_source": "twitter",
      "utm_medium": "social"
    },
    "is_spam": false,
    "is_read": true,
    "created_at": "2026-03-22T09:15:00Z"
  }
}

<form action="https://formslist.com/f/your_form_hash" method="POST">
  <input name="name" type="text" required />
  <input name="email" type="email" required />
  <textarea name="message" required></textarea>
  <button type="submit">Send</button>
</form>

const response = await fetch('https://formslist.com/f/your_form_hash', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    name: 'Sarah Chen',
    email: 'sarah@example.com',
    message: 'Hello from JavaScript!',
  }),
});

const result = await response.json();
// { "ok": true, "submission_id": "..." }

<script src="https://formslist.com/widget.js" data-form="your_form_hash"></script>

<script src="https://formslist.com/sdk/formflow.js"></script>
<script>
  const fl = new FormsList('your_form_hash');
  fl.submit({ name: 'Sarah', email: 'sarah@example.com', message: 'Hi!' })
    .then((r) => console.log(r)); // { ok: true, submission_id: '...' }
</script>

// React (with the script loaded):
const { submit, submitting, success, error } = useFormsList('your_form_hash');

<script src="https://formslist.com/capture.js" data-form="your_form_hash" defer></script>