Leads

POST /api/collect is a webhook that accepts any JSON object, stores it verbatim, and stamps it with the client IP address and the user agent. It needs no authentication and no schema registration: whatever keys you send become the columns of the Leads screen.

Send a submission

curl -X POST http://localhost:9173/api/collect \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "message": "Interested in plym Cloud.",
    "source": "pricing-page"
  }'

{"id": 42, "created_at": "2026-07-30T09:14:22.187431Z"}

The response is a receipt and the status is 201. Post the form and discard the body — there is nothing else to read.

Customise the fields

The payload has no fixed schema, so the fields are whatever your form sends. Add or remove one and the next submission carries the change.

Serve the form from the same origin as plym and post to the relative path. plym sends no CORS headers, so a fetch from another origin is blocked by the browser.

<form id="contact">
  <input name="email" type="email" required>
  <input name="company">
  <select name="plan_interest">
    <option value="self-hosted">Self-hosted</option>
    <option value="cloud">plym Cloud</option>
  </select>
  <button type="submit">Send</button>
</form>

<script>
document.getElementById('contact').addEventListener('submit', async (event) => {
  event.preventDefault();
  const body = Object.fromEntries(new FormData(event.target));
  body.source = location.pathname;
  await fetch('/api/collect', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  event.target.reset();
});
</script>

The Leads table builds its columns from the union of keys across the submissions on screen, in the order it first meets them. A row saved before you added a field shows — in that column. Header labels come from the key: plan_interest becomes Plan interest.

What plym stores

Behind a reverse proxy, the recorded address is whatever the proxy puts in X-Forwarded-For. The bundled Caddy sets it to the connecting client and discards any value the client sent. plym reads the first entry of that header and does not fall back to the peer address when the entry is unparseable, so a malformed header stores null rather than a wrong address.

Read leads in the admin

Leads is administrator-only. An editor who opens it is redirected to the dashboard.

Rows arrive newest first, 20 at a time, with Load more for the rest. Five controls sit above the table.

• Filter — a "contains" match per column. The badge counts the active filters.
• Sort — click a column header to cycle ascending, descending, off.
• Search — one query across every column at once.
• Export as CSV — downloads leads-2026-07-30.csv.
• Open in Google Sheets — copies the same rows as tab-separated text and opens a blank sheet to paste into.

Both exports write the filtered and sorted view, and only the rows already loaded. Click Load more until it disappears before you export, or the file is a partial table.

Read leads over the API

curl -H "Authorization: Bearer $PLYM_TOKEN" \
  'http://localhost:9173/api/submissions?page=1&page_size=20'

{
  "items": [
    {
      "id": 42,
      "payload": {
        "email": "ada@example.com",
        "name": "Ada Lovelace",
        "message": "Interested in plym Cloud.",
        "source": "pricing-page"
      },
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",
      "client_addr": "203.0.113.9",
      "additional_ctx": null,
      "created_at": "2026-07-30T09:14:22.187431Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

The caller must be an administrator. A missing or expired token returns 401 auth.token_invalid; an editor's token returns 403 auth.insufficient_role.

Limits