Skip to content
tellie
Developers

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

  1. Sign in and open Account → API keys. Create a key (read-only is safest).
  2. 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.

Sign in to create a key

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.

MethodPathWhat it doesKey
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}/responsesSubmit 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}/rsvpRSVP 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}/resultsAggregated 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.

MethodPathWhat it doesKey
GET/api/meWho the key belongs to, and its workspace.read
GET/api/templatesTemplate keys you can create forms from.read
GET/api/eventsWebhook event names.read

Forms

Owners and admins of a workspace reach every form in it; members reach their own.

MethodPathWhat it doesKey
GET/api/formsThe forms in your workspace. Params: kind=rsvp|survey|pulse|poll, status=open|draft|closedread
POST/api/formsCreate a form from a template; any builder field can be set. Params: template, title, plus any field belowwrite
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}/openOpen 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.

MethodPathWhat it doesKey
GET/api/forms/{id|code}/responsesAnswers. Params: round (pulses)read
GET/api/forms/{id|code}/resultsAggregates: averages, NPS, per-option counts. Params: roundread
GET/api/forms/{id|code}/rsvpsRSVPs and headcount stats. Params: filter=going|maybe|waitlist|no|checkedinread
POST/api/forms/{id|code}/rsvps/{ticket}/checkinCheck a guest in by ticket code.write

Webhooks

Workspace owners and admins only.

MethodPathWhat it doesKey
GET/api/webhooksThe workspace webhooks.read
POST/api/webhooksAdd one; the reply includes the signing secret once. Params: url, events (e.g. ["rsvp.*"]), form_id (0 = all), kind json|teams|slackwrite
POST/api/webhooks/{id}/testSend a test ping now.read
GET/api/webhooks/{id}/deliveriesRecent 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.*.

EventWhen
response.createdA survey/poll/pulse answer was submitted
rsvp.createdSomeone RSVP'd
rsvp.updatedAn RSVP changed
rsvp.promotedSomeone moved off the waitlist
rsvp.checkedinA guest was checked in
form.openedA form was opened
form.closedA form was closed
form.sharedA form was posted to a channel (Teams/Slack)
pingTest 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.

Manage keys & webhooks