Kitchen API
Customer API
Invite people into a community, register event applicants, and receive webhooks. The API key is the community, so paths do not include a community id.
Send or submit
Both modes use POST /api/v1/invitations. Pick one before you write the call. They do different work.
Deliver now
send
You already decided this person should join.
- Inviter approves the invitation and delivers the Slack, Discord, Telegram, or WhatsApp invite in the same call.
- The person does not receive “Verify your email”.
- reCAPTCHA is not checked. Required form answers are not enforced. Answers you send are still stored.
- The response status is
sentordelivery_failed.email_verifiedistrue.
Follow the join form
submit
The invitation should follow the form rules, then wait for a decision.
- Required answers are checked. Read field ids from GET /api/v1/form first.
- reCAPTCHA is not checked. Country allow and deny lists are not applied. Those rules belong to the public page, because this call comes from your server.
- When
email_verificationis on, Inviter emails “Verify your email” and the status isawaiting_verification. This still happens whenauto_approvalis also on. - When email verification is off and
auto_approvalis on, delivery starts in that call. - When both are off, the status is
pendingand the person receives “Application received”.
submit with email verification on: awaiting_verification, then POST /approve, then sent. send goes straight to delivery.
Authentication
The customer API is for communities on the Pro plan. Send the community API key as a bearer token. Only the community owner can create or delete keys, and only from the dashboard.
Header
Authorization: Bearer inv_live_…
The secret is shown once, when the key is created. A deleted key stops working immediately. Dashboard routes are separate and are not documented here.
UNAUTHORIZED—API key is missing,API key is invalid, orAPI key was deleted.PLAN_LIMIT—Customer API is available on the Pro plan.
Errors
Every response is { "success": true, "data": … } or { "success": false, "error": { "code", "message", "details" } }. Branch on error.code. The message says why.
| Code | When |
|---|---|
UNAUTHORIZED | API key is missing, API key is invalid, or API key was deleted. |
PLAN_LIMIT | Customer API is available on the Pro plan. |
NOT_FOUND | Invitation not found, Event not found, or Applicant not found. |
CONFLICT | The status does not allow the action, for example Invitation can only be edited while pending or awaiting verification. |
VALIDATION_ERROR | The body failed validation. details names the fields. |
RATE_LIMITED | The API key exceeded 120 requests per minute. details.retry_after_seconds says when to retry. The same code is also the verification-email cap above. That one puts the wait time in message. |
Types
Dates are UTC timestamps like 2026-10-29T12:00:00Z. The shapes below are what sits in data.
Invitation
| Field | Type | Meaning |
|---|---|---|
id | string | Invitation id. |
email | string | Invitee email. You cannot change this later. |
display_name | string | Name shown with the invite. |
answers | object of strings | Keys are field ids from GET /api/v1/form. |
status | string | pending, awaiting_verification, approved, delivering, sent, delivery_failed, or rejected. |
platforms | array of strings | slack, discord, telegram, or whatsapp. Each one must already be enabled and connected. |
email_verified | boolean | true after send, after the invitee verifies, or when verification is off. |
created_at | timestamp | When the invitation was stored. |
updated_at | timestamp | When it last changed. Webhook receivers should trust this over arrival order. |
Page
List endpoints wrap records in a page.
| Field | Type | Meaning |
|---|---|---|
items | array | The records for this page. |
total | number | How many records match, not just this page. |
page | number | Page number, starting at 1. |
per_page | number | Page size. Default 20. Maximum 100. |
total_pages | number | How many pages exist. |
Event
| Field | Type | Meaning |
|---|---|---|
id | string | Event id. Present on responses. |
title | string | Event name. |
slug | string | URL slug, unique in the community. |
description | string | Short description. |
starts_at, ends_at | timestamp | Schedule. Omit either one to leave it unset. |
timezone | string | IANA name, such as Europe/Istanbul. |
location_type | string | physical or online. |
location | string | Address or link. |
published | boolean | Whether the public page is visible. |
accepts_leads | boolean | Whether free registration is open. |
ticket_sales_enabled | boolean | Cannot be true together with free registration. |
lead_form | object | Only on GET /api/v1/events/{id}. Contains fields, each with an id. |
Applicant
An applicant is one event registration. The create and update body is { "data": { "field_id": "answer" } }. Field ids come from the event’s lead_form. A new event starts with name and email. Event registration does not send “Verify your email” and does not check reCAPTCHA.
| Field | Type | Meaning |
|---|---|---|
id | string | Applicant id. |
event_id | string | Event this registration belongs to. |
data | object of strings | Answers, keyed by field id. |
created_at | timestamp | When the applicant was stored. |
Form field
| Field | Type | Meaning |
|---|---|---|
id | string | Use this as the answer key. Omit it on create and the response assigns one. |
type | string | text, email, or another input type. One field must have type email. |
label | string | Question shown to the person. |
placeholder | string | Hint inside the input. |
required | boolean | submit rejects the call when a required answer is missing. send does not. |
regexp | string | Optional pattern the answer must match. |
options | array | For a choice field. Each item is { "label": "Yes", "value": "yes" }. |
Form rules
Read Send or submit before changing these. reCAPTCHA and country lists affect the public page only.
| Field | Type | Meaning |
|---|---|---|
auto_approval | boolean | On submit, delivery starts in that call when this is true and email verification is off. |
email_verification | boolean | On submit, Inviter emails “Verify your email” and stores awaiting_verification. send ignores this rule. |
recaptcha_enabled | boolean | Public page only. The API never asks for a token. |
redirect_url | string | Where the public page sends the person after they submit. |
allowed_countries | array of strings | Public page only. Country codes such as US. |
denied_countries | array of strings | Public page only. |
Invitations
For submit, call GET /api/v1/form first and use those field ids as answer keys. send can omit answers.
Idempotency-Key
This header stops a retry from creating a second invitation or a second applicant. Use it on POST /api/v1/invitations and POST /api/v1/events/{id}/applicants. Other calls ignore it.
Inviter does not give you this value. There is no endpoint to fetch one. You make it up before you send the request, and you store it. One new value per person you are creating.
- On a Mac or Linux terminal, run
uuidgen. It prints a value like550e8400-e29b-41d4-a716-446655440000. - In JavaScript, call
crypto.randomUUID(). - In Python, call
uuid.uuid4().
Put that exact text in the Idempotency-Key header. It is not part of the JSON body.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
If the call times out or you are not sure the first call worked, send the same request again with the same key. You get the record from the first call. A second record is not created.
A new person needs a new value. Reusing the old value returns the old record, even when the email in the body is different. Do not use the person's email as the key. The value must be 1 to 128 characters, with no spaces and no line breaks. We remember it for 24 hours. After that, the same value creates a new record. If you leave the header off, every call creates a new record.
POST /api/v1/invitations
mode is send or submit. send delivers in the call and does not email “Verify your email”. submit follows the form, including the verification email when email_verification is on. reCAPTCHA is not checked for either mode. See Send or submit.
Request
curl -X POST "$BASE/api/v1/invitations" \
-H "Authorization: Bearer inv_live_…" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{"mode":"send","email":"[email protected]","display_name":"Ada","platforms":["slack"],"answers":{"field_id":"Ada"}}'
Fields: mode, email, display_name, platforms, answers. Success is 201. data is an Invitation.
Response
{
"success": true,
"data": {
"id": "671f0c2a9b1e4d6f8a000001",
"email": "[email protected]",
"display_name": "Ada",
"answers": { "field_id": "Ada" },
"status": "sent",
"platforms": ["slack"],
"email_verified": true,
"created_at": "2026-10-29T12:00:00Z",
"updated_at": "2026-10-29T12:00:02Z"
}
}
GET /api/v1/invitations
Optional query: page, per_page, status, email, platform. Success is 200. data is a Page of Invitations.
Request
curl "$BASE/api/v1/invitations?status=pending&page=1&per_page=20" \ -H "Authorization: Bearer inv_live_…"
Response
{
"success": true,
"data": {
"items": [
{
"id": "671f0c2a9b1e4d6f8a000001",
"email": "[email protected]",
"display_name": "Ada",
"status": "pending",
"platforms": ["slack"],
"email_verified": false,
"created_at": "2026-10-29T12:00:00Z",
"updated_at": "2026-10-29T12:00:00Z"
}
],
"total": 1,
"page": 1,
"per_page": 20,
"total_pages": 1
}
}
GET /api/v1/invitations/{id}
Success is 200. data is one Invitation. An id from another community is Invitation not found.
curl "$BASE/api/v1/invitations/671f0c2a9b1e4d6f8a000001" \ -H "Authorization: Bearer inv_live_…"
PATCH /api/v1/invitations/{id}
While pending or awaiting_verification, send any of display_name, answers, and platforms. Leave a field out to keep its current value. Email stays fixed. Other statuses return Invitation can only be edited while pending or awaiting verification. Success is 200 with the Invitation.
curl -X PATCH "$BASE/api/v1/invitations/671f0c2a9b1e4d6f8a000001" \
-H "Authorization: Bearer inv_live_…" \
-H "Content-Type: application/json" \
-d '{"display_name":"Ada Lovelace","platforms":["slack"]}'
POST /api/v1/invitations/{id}/approve
No body. Approves and delivers the platform invite. Allowed while pending or awaiting_verification. This does not send “Verify your email”. Otherwise: Invitation can only be approved while pending or awaiting verification. Success is 200 with the Invitation.
curl -X POST "$BASE/api/v1/invitations/671f0c2a9b1e4d6f8a000001/approve" \ -H "Authorization: Bearer inv_live_…"
POST /api/v1/invitations/{id}/reject
Body is { "reason": "string" }. reason is optional. Allowed while pending or awaiting_verification. Otherwise: Invitation can only be rejected while pending or awaiting verification. Success is 200 with the Invitation, status rejected.
curl -X POST "$BASE/api/v1/invitations/671f0c2a9b1e4d6f8a000001/reject" \
-H "Authorization: Bearer inv_live_…" \
-H "Content-Type: application/json" \
-d '{"reason":"Not a fit right now"}'
POST /api/v1/invitations/{id}/retry
No body. Retries delivery after delivery_failed. Otherwise: Invitation can only be retried when delivery failed. Success is 200 with the Invitation.
curl -X POST "$BASE/api/v1/invitations/671f0c2a9b1e4d6f8a000001/retry" \ -H "Authorization: Bearer inv_live_…"
DELETE /api/v1/invitations/{id}
No body. Success is 204 with an empty body. Deleting the invitation does not undo a platform invite that already went out, and it does not reset the verification-email count.
curl -X DELETE "$BASE/api/v1/invitations/671f0c2a9b1e4d6f8a000001" \ -H "Authorization: Bearer inv_live_…"
Events
Creating an event also creates a registration form with fields name and email. The list endpoint omits lead_form. Call GET one event when you need field ids.
POST /api/v1/events
Send an Event. title and slug are required. Success is 201. data is the Event plus lead_form.
Request
curl -X POST "$BASE/api/v1/events" \
-H "Authorization: Bearer inv_live_…" \
-H "Content-Type: application/json" \
-d '{"title":"Launch night","slug":"launch-night","published":true,"location_type":"online"}'
Response
{
"success": true,
"data": {
"id": "671f0c2a9b1e4d6f8a000010",
"title": "Launch night",
"slug": "launch-night",
"published": true,
"location_type": "online",
"created_at": "2026-10-29T12:00:00Z",
"lead_form": {
"fields": [
{ "id": "name", "type": "text", "label": "Name", "required": true },
{ "id": "email", "type": "email", "label": "Email", "required": true }
]
}
}
}
GET /api/v1/events
Query page and per_page. Success is 200. data is a Page of Events.
curl "$BASE/api/v1/events?page=1&per_page=20" \ -H "Authorization: Bearer inv_live_…"
GET /api/v1/events/{id}
Success is 200. data is the Event plus lead_form. Another community’s id is Event not found.
curl "$BASE/api/v1/events/671f0c2a9b1e4d6f8a000010" \ -H "Authorization: Bearer inv_live_…"
PATCH /api/v1/events/{id}
Send only the Event fields you want to change. Leave a field out to keep it. Success is 200 with the Event and lead_form.
curl -X PATCH "$BASE/api/v1/events/671f0c2a9b1e4d6f8a000010" \
-H "Authorization: Bearer inv_live_…" \
-H "Content-Type: application/json" \
-d '{"title":"Launch night — updated","published":true,"starts_at":"2026-11-01T18:00:00Z"}'
PUT /api/v1/events/{id}/form
Replaces the registration form. fields is an array of form fields. Include a required name field and a required email field. New fields may omit id. Success is 200. data is the saved form, including assigned ids.
curl -X PUT "$BASE/api/v1/events/671f0c2a9b1e4d6f8a000010/form" \
-H "Authorization: Bearer inv_live_…" \
-H "Content-Type: application/json" \
-d '{"title":"Registration","fields":[{"id":"name","type":"text","label":"Name","required":true},{"id":"email","type":"email","label":"Email","required":true}]}'
{
"success": true,
"data": {
"title": "Registration",
"fields": [
{ "id": "name", "type": "text", "label": "Name", "required": true },
{ "id": "email", "type": "email", "label": "Email", "required": true }
]
}
}
DELETE /api/v1/events/{id}
No body. Success is 204 with an empty body.
curl -X DELETE "$BASE/api/v1/events/671f0c2a9b1e4d6f8a000010" \ -H "Authorization: Bearer inv_live_…"
Applicants
Applicants are event registrations. Read field ids from the event before sending answers. On create, add an Idempotency-Key header you made up yourself. How to make that value is the same as for invitations: run uuidgen, save the text, and send that exact text again if you retry. The same value within 24 hours returns the original applicant.
POST /api/v1/events/{id}/applicants
Body is { "data": { "field_id": "answer" } }. Put name and email inside data, using the field ids. Success is 201. data in the response is an Applicant. The same Idempotency-Key returns that applicant instead of creating another.
Request
curl -X POST "$BASE/api/v1/events/671f0c2a9b1e4d6f8a000010/applicants" \
-H "Authorization: Bearer inv_live_…" \
-H "Idempotency-Key: 6ba7b810-9dad-11d1-80b4-00c04fd430c8" \
-H "Content-Type: application/json" \
-d '{"data":{"name":"Ada","email":"[email protected]"}}'
Response
{
"success": true,
"data": {
"id": "671f0c2a9b1e4d6f8a000020",
"event_id": "671f0c2a9b1e4d6f8a000010",
"data": { "name": "Ada", "email": "[email protected]" },
"created_at": "2026-10-29T12:00:00Z"
}
}
GET /api/v1/events/{id}/applicants
Query page, per_page, and q. q searches the answers. Success is 200. data is a Page of Applicants.
curl "$BASE/api/v1/events/671f0c2a9b1e4d6f8a000010/applicants?q=ada&page=1" \ -H "Authorization: Bearer inv_live_…"
GET /api/v1/events/{id}/applicants/{applicantId}
Success is 200. data is one Applicant. A missing id is Applicant not found.
curl "$BASE/api/v1/events/671f0c2a9b1e4d6f8a000010/applicants/671f0c2a9b1e4d6f8a000020" \ -H "Authorization: Bearer inv_live_…"
PATCH /api/v1/events/{id}/applicants/{applicantId}
Body is the same shape as create: { "data": { "field_id": "answer" } }. This replaces the answers. Success is 200 with the Applicant.
curl -X PATCH "$BASE/api/v1/events/671f0c2a9b1e4d6f8a000010/applicants/671f0c2a9b1e4d6f8a000020" \
-H "Authorization: Bearer inv_live_…" \
-H "Content-Type: application/json" \
-d '{"data":{"name":"Ada Lovelace","email":"[email protected]"}}'
DELETE /api/v1/events/{id}/applicants/{applicantId}
No body. Success is 204 with an empty body.
curl -X DELETE "$BASE/api/v1/events/671f0c2a9b1e4d6f8a000010/applicants/671f0c2a9b1e4d6f8a000020" \ -H "Authorization: Bearer inv_live_…"
Form
Each community has one join form. Call this before a submit so answers use field ids. Saving the form does not send a webhook.
GET /api/v1/form
Success is 200. data has id, title, fields, and rules. email_verification changes what submit does. recaptcha_enabled and the country lists do not.
Request
curl "$BASE/api/v1/form" \ -H "Authorization: Bearer inv_live_…"
Response
{
"success": true,
"data": {
"id": "form_1",
"title": "Join Us",
"fields": [
{ "id": "b7e1", "type": "text", "label": "Full Name", "required": true },
{ "id": "c2a9", "type": "email", "label": "Email", "required": true }
],
"rules": {
"auto_approval": false,
"email_verification": false,
"recaptcha_enabled": true,
"allowed_countries": [],
"denied_countries": []
}
}
}
PUT /api/v1/form
Body is { "fields": [form fields], "rules": { form rules } }. This replaces the form. The email field cannot be removed. New fields may omit id. Success is 200 with the saved form, including assigned ids.
curl -X PUT "$BASE/api/v1/form" \
-H "Authorization: Bearer inv_live_…" \
-H "Content-Type: application/json" \
-d '{"fields":[{"type":"text","label":"Full Name","required":true},{"type":"email","label":"Email","required":true}],"rules":{"auto_approval":false,"email_verification":true,"recaptcha_enabled":true}}'
Webhooks
One URL per community, saved by the owner from the dashboard. Public URLs must be https. When this API is running in development, http://localhost, http://127.0.0.1, and http://[::1] are allowed. Saving the URL returns a new signing secret once. Clearing the URL stops delivery, including after the community leaves the Pro plan. Revoking an API key does not change the URL. Delivery is skipped while the community is not on Pro.
Events: invitation.created, invitation.awaiting_verification, invitation.approved, invitation.delivering, invitation.sent, invitation.delivery_failed, invitation.rejected, invitation.deleted, applicant.created, applicant.updated, applicant.deleted. The dashboard, the public page, and this API all emit them. Event and form saves do not.
Delivery is at least once. Retries reuse the same event id. Order is not guaranteed; trust data.updated_at when it is present. A 2xx response within 5 seconds is success. A timeout, a non-2xx response, or a redirect is a failure. Backoff is 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, then 24 hours, after which the delivery is marked failed. The URL stays in place.
Each delivery is one JSON object. data is an Invitation or an Applicant, matching the event type.
| Field | Type | Meaning |
|---|---|---|
id | string | Event id, also sent as X-Inviter-Event-Id. Retries reuse it. |
type | string | One of the event names above. |
created_at | timestamp | When this delivery was created. |
data | Invitation or Applicant | The record after the change. |
Verify the signature before you trust the body. Reject the request when X-Inviter-Timestamp is more than 5 minutes from your clock.
Build X-Inviter-Signature
The signature is lowercase hex HMAC-SHA256 of {timestamp}.{raw body}. You build that text yourself. Inviter does not send it as a separate field.
- Read the
X-Inviter-Timestampheader. It is a whole number of seconds, such as1710000000. - Read the raw body. These are the exact bytes of the HTTP request. Do not parse the JSON and print it again. A space or a reordered key changes the signature.
- Join them with one period and nothing else:
1710000000.{"id":"evt_1","type":"invitation.sent"}. - HMAC-SHA256 that text. The key is the signing secret as plain text. Do not hex-decode it.
- Hex-encode the result. That string must equal the
X-Inviter-Signatureheader.
Check your code against this sample. Secret whsec_example, timestamp 1710000000, and raw body {"id":"evt_1","type":"invitation.sent"} produce this signature:
ac09ca1b7137cfe072e958b0578009cc64d8e518700656036d7461e97d05c176
Node.js. rawBody must be the exact request bytes, not JSON.stringify of a parsed object.
const crypto = require("crypto");
const secret = "whsec_example";
const timestamp = "1710000000";
const rawBody = '{"id":"evt_1","type":"invitation.sent"}';
const signed = timestamp + "." + rawBody;
const signature = crypto.createHmac("sha256", secret).update(signed).digest("hex");
Python.
import hmac, hashlib
secret = "whsec_example"
timestamp = "1710000000"
raw_body = b'{"id":"evt_1","type":"invitation.sent"}'
signed = timestamp.encode() + b"." + raw_body
signature = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
Go.
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(timestamp))
mac.Write([]byte("."))
mac.Write(rawBody)
signature := hex.EncodeToString(mac.Sum(nil))
X-Inviter-Timestamp: 1710000000 X-Inviter-Signature: ac09ca1b7137cfe072e958b0578009cc64d8e518700656036d7461e97d05c176 X-Inviter-Event-Id: evt_…
{
"id": "evt_…",
"type": "invitation.sent",
"created_at": "2026-10-29T00:00:00Z",
"data": { "id": "…", "status": "sent", "email": "[email protected]" }
}