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.

Service online Base path /api/v1

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 sent or delivery_failed. email_verified is true.

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_verification is on, Inviter emails “Verify your email” and the status is awaiting_verification. This still happens when auto_approval is also on.
  • When email verification is off and auto_approval is on, delivery starts in that call.
  • When both are off, the status is pending and 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.

Errors

Every response is { "success": true, "data": … } or { "success": false, "error": { "code", "message", "details" } }. Branch on error.code. The message says why.

CodeWhen
UNAUTHORIZEDAPI key is missing, API key is invalid, or API key was deleted.
PLAN_LIMITCustomer API is available on the Pro plan.
NOT_FOUNDInvitation not found, Event not found, or Applicant not found.
CONFLICTThe status does not allow the action, for example Invitation can only be edited while pending or awaiting verification.
VALIDATION_ERRORThe body failed validation. details names the fields.
RATE_LIMITEDThe 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

FieldTypeMeaning
idstringInvitation id.
emailstringInvitee email. You cannot change this later.
display_namestringName shown with the invite.
answersobject of stringsKeys are field ids from GET /api/v1/form.
statusstringpending, awaiting_verification, approved, delivering, sent, delivery_failed, or rejected.
platformsarray of stringsslack, discord, telegram, or whatsapp. Each one must already be enabled and connected.
email_verifiedbooleantrue after send, after the invitee verifies, or when verification is off.
created_attimestampWhen the invitation was stored.
updated_attimestampWhen it last changed. Webhook receivers should trust this over arrival order.

Page

List endpoints wrap records in a page.

FieldTypeMeaning
itemsarrayThe records for this page.
totalnumberHow many records match, not just this page.
pagenumberPage number, starting at 1.
per_pagenumberPage size. Default 20. Maximum 100.
total_pagesnumberHow many pages exist.

Event

FieldTypeMeaning
idstringEvent id. Present on responses.
titlestringEvent name.
slugstringURL slug, unique in the community.
descriptionstringShort description.
starts_at, ends_attimestampSchedule. Omit either one to leave it unset.
timezonestringIANA name, such as Europe/Istanbul.
location_typestringphysical or online.
locationstringAddress or link.
publishedbooleanWhether the public page is visible.
accepts_leadsbooleanWhether free registration is open.
ticket_sales_enabledbooleanCannot be true together with free registration.
lead_formobjectOnly 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.

FieldTypeMeaning
idstringApplicant id.
event_idstringEvent this registration belongs to.
dataobject of stringsAnswers, keyed by field id.
created_attimestampWhen the applicant was stored.

Form field

FieldTypeMeaning
idstringUse this as the answer key. Omit it on create and the response assigns one.
typestringtext, email, or another input type. One field must have type email.
labelstringQuestion shown to the person.
placeholderstringHint inside the input.
requiredbooleansubmit rejects the call when a required answer is missing. send does not.
regexpstringOptional pattern the answer must match.
optionsarrayFor 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.

FieldTypeMeaning
auto_approvalbooleanOn submit, delivery starts in that call when this is true and email verification is off.
email_verificationbooleanOn submit, Inviter emails “Verify your email” and stores awaiting_verification. send ignores this rule.
recaptcha_enabledbooleanPublic page only. The API never asks for a token.
redirect_urlstringWhere the public page sends the person after they submit.
allowed_countriesarray of stringsPublic page only. Country codes such as US.
denied_countriesarray of stringsPublic 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.

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.

FieldTypeMeaning
idstringEvent id, also sent as X-Inviter-Event-Id. Retries reuse it.
typestringOne of the event names above.
created_attimestampWhen this delivery was created.
dataInvitation or ApplicantThe 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.

  1. Read the X-Inviter-Timestamp header. It is a whole number of seconds, such as 1710000000.
  2. 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.
  3. Join them with one period and nothing else: 1710000000.{"id":"evt_1","type":"invitation.sent"}.
  4. HMAC-SHA256 that text. The key is the signing secret as plain text. Do not hex-decode it.
  5. Hex-encode the result. That string must equal the X-Inviter-Signature header.

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]" }
}