API & webhooks
Read your forms and results from any script, and let Tellie push events to your other systems the moment they happen. JSON in, JSON out.
Quick start
- Sign in and open Account → API keys. Create a key (read-only is safest).
- Send it as a bearer token:
curl -H "Authorization: Bearer sso_YOUR_KEY" \ "https://tellie.us/api/forms?pretty=1"
Base URL: https://tellie.us/api. Add ?pretty=1 to any call for readable output.
Public API: put a form on your own site
No key, no sign-in, and browsers can call it directly. In the builder, turn on Let other websites collect answers for a form, open it, and use its short code (the last part of its share link).
Fetch the form, then submit
// 1. what to draw
const form = (await (await fetch("https://tellie.us/api/public/forms/CODE")).json()).form;
// 2. send the answers, keyed by question id
const res = await fetch("https://tellie.us/api/public/forms/CODE/responses", {
method: "POST", headers: {"Content-Type": "application/json"},
body: JSON.stringify({ respondent: "user-42", answers: { q1: "Great session", q2: 5 } })
});
const out = await res.json(); // 201 {ok:true, thank_you:"..."} | 422 {error, errors:{q1:"..."}}
RSVP to an event
curl -X POST "https://tellie.us/api/public/forms/CODE/rsvp" \
-H "Content-Type: application/json" \
-d '{"name":"Jamie Rivera","email":"jamie@example.com","response":"going","guests":1}'
# 201 {"ok":true,"state":"confirmed","ticket":"QYEAJHKJ"} (state is "waitlist" when the event is full)
respondent is your own stable id for the person; it is stored only as a one-way hash and is required when a form allows one answer per person. Calls are rate limited per network address.
Authentication
Every call needs Authorization: Bearer sso_... (or the header X-API-Key). Keys act as the person who made them: you can only see and change your own forms (admins can reach every form).
- Read-only keys can use every GET endpoint.
- Read and write keys can also create, update, open, close and delete.
- Keys are stored as one-way hashes. Revoke one any time on your Account page.
- Anonymous forms stay anonymous in the API too: responses never include who answered.
Endpoints
Public API (no key)
Draw a form on your own website and collect answers without sending people to Tellie. No key and no sign-in; browsers can call it directly (CORS is open). The form owner must switch on "Let other websites collect answers" in the builder, and the form must be open.
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /api/public/forms/{code} | The form to draw: title, questions (id, type, label, options, required), open/closed, thank-you text, and for RSVPs the event details and seats left. | public |
| POST | /api/public/forms/{code}/responses | Submit answers to a survey, poll or pulse. Reply 201 {"ok":true,"thank_you":"..."}; 422 with per-question "errors" when something is missing. Params: answers {"q1":"text","q2":4,"q3":["A","B"]} keyed by question id; respondent = your own stable id for the person (required when the form allows one answer per person; stored only as a one-way hash); optional hidden field website (leave it empty; bots that fill it are ignored). Owners can restrict which websites may call from a browser. | public |
| POST | /api/public/forms/{code}/rsvp | RSVP to an event. Reply 201 {"state":"confirmed|waitlist","ticket":"..."} and the guest is emailed their ticket. Params: name and email (required), response going|maybe|no, guests, dietary, notes, answers. | public |
| GET | /api/public/forms/{code}/results | Aggregated results, only when the owner made results visible (live, or after the form closes). Params: round (pulse forms). | public |
Account & templates
These need an API key. A key acts inside the workspace it was created in.
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /api/me | Who the key belongs to, and its workspace. | read |
| GET | /api/templates | Template keys you can create forms from. | read |
| GET | /api/events | Webhook event names. | read |
Forms
Owners and admins of a workspace reach every form in it; members reach their own.
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /api/forms | The forms in your workspace. Params: kind=rsvp|survey|pulse|poll, status=open|draft|closed | read |
| POST | /api/forms | Create a form from a template; any builder field can be set. Params: template, title, plus any field below | write |
| GET | /api/forms/{id|code} | One form with its questions. | read |
| PATCH | /api/forms/{id|code} | Update fields. Params: title, description, status, questions, capacity, closes_at, event_start, event_location, anonymous, one_per, show_results, public_api (true lets other sites use the public API) ... | write |
| POST | /api/forms/{id|code}/open | Open a form (also /close). | write |
| DELETE | /api/forms/{id|code} | Delete a form and its answers. | write |
Responses & RSVPs
Anonymous forms never reveal who answered.
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /api/forms/{id|code}/responses | Answers. Params: round (pulses) | read |
| GET | /api/forms/{id|code}/results | Aggregates: averages, NPS, per-option counts. Params: round | read |
| GET | /api/forms/{id|code}/rsvps | RSVPs and headcount stats. Params: filter=going|maybe|waitlist|no|checkedin | read |
| POST | /api/forms/{id|code}/rsvps/{ticket}/checkin | Check a guest in by ticket code. | write |
Webhooks
Workspace owners and admins only.
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /api/webhooks | The workspace webhooks. | read |
| POST | /api/webhooks | Add one; the reply includes the signing secret once. Params: url, events (e.g. ["rsvp.*"]), form_id (0 = all), kind json|teams|slack | write |
| POST | /api/webhooks/{id}/test | Send a test ping now. | read |
| GET | /api/webhooks/{id}/deliveries | Recent delivery attempts. | read |
| DELETE | /api/webhooks/{id} | Remove a webhook. | write |
Build it with AI
Copy this prompt into your AI coding assistant. It lists every endpoint above, so the assistant can wire Tellie into your site without guessing.
Examples
Create an RSVP and open it
curl -X POST "https://tellie.us/api/forms" \
-H "Authorization: Bearer sso_YOUR_KEY" -H "Content-Type: application/json" \
-d '{"template":"event_rsvp","title":"Holiday party","capacity":120,
"event_start":"2026-12-12 18:00","event_location":"Main atrium"}'
curl -X POST "https://tellie.us/api/forms/FORMCODE/open" -H "Authorization: Bearer sso_YOUR_KEY"
PowerShell: export results to CSV
$h = @{ Authorization = "Bearer sso_YOUR_KEY" }
$r = Invoke-RestMethod "https://tellie.us/api/forms/FORMCODE/responses" -Headers $h
$r.responses | ForEach-Object { [pscustomobject]@{ Date = $_.date; Answer = $_.answers[0].answer } } |
Export-Csv results.csv -NoTypeInformation
Python: headcount for an event
import requests
H = {"Authorization": "Bearer sso_YOUR_KEY"}
r = requests.get("https://tellie.us/api/forms/FORMCODE/rsvps", headers=H, timeout=10).json()
print(r["stats"]) # {'going': 31, 'guests': 12, 'seats': 43, 'waitlist': 2, ...}
Webhooks
Add a webhook on your Account page (or with the API). Tellie then sends an HTTPS POST with a JSON body whenever one of your forms emits an event you subscribed to. Use * for everything, or patterns like rsvp.*.
| Event | When |
|---|---|
| response.created | A survey/poll/pulse answer was submitted |
| rsvp.created | Someone RSVP'd |
| rsvp.updated | An RSVP changed |
| rsvp.promoted | Someone moved off the waitlist |
| rsvp.checkedin | A guest was checked in |
| form.opened | A form was opened |
| form.closed | A form was closed |
| form.shared | A form was posted to a channel (Teams/Slack) |
| ping | Test event |
Payload
{
"id": "evt_9f1c2a7be3d04a11",
"event": "rsvp.created",
"created": "2026-11-04T10:42:07-07:00",
"form": { "id": 14, "code": "k7m2xqa", "title": "Holiday party", "kind": "rsvp",
"status": "open", "anonymous": false, "url": "https://tellie.us/s/k7m2xqa" },
"data": { "name": "Jamie Rivera", "email": "jrivera@example.com", "response": "going",
"state": "confirmed", "guests": 1, "ticket": "Q7M2XK4P", "checked_in": false }
}
For anonymous forms, response.created events carry the answers but respondent is always null.
Headers
- X-Tellie-Event: the event name
- X-Tellie-Delivery: the event id (use it to ignore duplicates)
- X-Tellie-Timestamp: unix seconds when we signed it
- X-Tellie-Signature: sha256= followed by the HMAC
- Earlier receivers: the same four headers are also sent as X-SaySo-* (the product's old name), so nothing you built before breaks.
Delivery & retries
Reply with any 2xx within 6 seconds to confirm. Anything else is retried after 1 min, 5 min, 30 min, 2 h and 12 h, then marked failed. After 25 failures in a row the webhook is paused automatically; resume it on your Account page.
Verify the signature
The signature is HMAC-SHA256(secret, timestamp + "." + rawBody) as lowercase hex. Compute it over the raw request body (before JSON parsing), compare in constant time, and reject timestamps older than five minutes.
Node.js
const crypto = require('crypto');
function verify(rawBody, headers, secret) {
const ts = headers['x-tellie-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
const got = headers['x-tellie-signature'] || '';
return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}
Python
import hmac, hashlib, time
def verify(raw_body: bytes, headers, secret: str) -> bool:
ts = headers["X-Tellie-Timestamp"]
if abs(time.time() - int(ts)) > 300:
return False
msg = ts.encode() + b"." + raw_body
expected = "sha256=" + hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, headers["X-Tellie-Signature"])
C#
static bool Verify(string rawBody, string ts, string sig, string secret) {
using var h = new System.Security.Cryptography.HMACSHA256(System.Text.Encoding.UTF8.GetBytes(secret));
var hex = Convert.ToHexString(h.ComputeHash(System.Text.Encoding.UTF8.GetBytes(ts + "." + rawBody))).ToLower();
return System.Security.Cryptography.CryptographicOperations.FixedTimeEquals(
System.Text.Encoding.UTF8.GetBytes("sha256=" + hex), System.Text.Encoding.UTF8.GetBytes(sig));
}
PHP
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_SAYSO_TIMESTAMP'];
$exp = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
$ok = hash_equals($exp, $_SERVER['HTTP_X_SAYSO_SIGNATURE']) && abs(time() - (int)$ts) <= 300;
Teams & Slack
Choose Microsoft Teams or Slack when you add a webhook and paste the channel's incoming-webhook URL. Tellie then formats messages for the channel instead of sending raw JSON.
- Press Post to channels on a form's Share tab to announce it. RSVP posts include I'm going / Can't make it buttons that open a one-tap RSVP link (people sign in first).
- Subscribe the channel to rsvp.created or form.closed to get short updates, e.g. "Jamie RSVP'd (going)". Anonymous forms never name people.
- Teams: add the Workflows "Post to a channel when a webhook request is received" template (or an Incoming Webhook connector) and copy its URL.
- Slack: create an app with Incoming Webhooks, add it to the channel and copy the URL.
Limits & errors
- Rate limit: 120 requests per minute per user (HTTP 429 when exceeded).
- Webhook URLs must be https and publicly reachable. Private or local addresses are blocked unless an admin allows them.
- Up to 25 webhooks and 10 active keys per person.
Errors are JSON like {"error":"Form not found"} with a meaningful status: 400 bad input, 401 missing or bad key, 403 read-only key on a write, 404 not found, 429 slow down.