Public API & Zapier
A REST API for reading your guild's data and creating members, plus signed outbound webhooks that fire on member, payment, registration and form events. Base URL https://quilthosting.com/api/v1.
API keys and scopes
Admin → API (owners and admins). Create a key, tick the scopes it needs, and copy it — it is shown once. Keys look like qh_…; only a hash is stored. Revoke a key from the same screen; the last-used time is recorded.
| Scope | Grants |
|---|---|
read | Always granted. All GET endpoints. |
members:write | POST /members, PATCH /members/:id |
hooks:write | POST /hooks, DELETE /hooks/:id |
A trigger-only Zap needs hooks:write (Zapier subscribes and unsubscribes when the Zap is switched on and off) but not members:write. Keys created before v0.27 may carry a legacy write scope that grants both.
Authentication
Authorization: Bearer qh_…your_key…
Or, less securely, ?api_key=qh_…. API routes are exempt from the private-preview site password; the key is the only gate. An inactive guild returns 403.
Read endpoints
| Method | Path | Returns |
|---|---|---|
| GET | /me | Tenant id, name, slug, plan, and the key's scopes |
| GET | /members?status=&limit=&offset=&page= | Paginated: {members, total, limit, offset, page, total_pages, has_more}. Default 100 per page, max 500. |
| GET | /events | Up to 200 events (no pagination) |
| GET | /payments | Up to 200 payments (no pagination) |
| GET | /levels | Active membership levels |
| GET | /hooks | Up to 100 hook subscriptions (secrets never returned) |
curl -s "https://quilthosting.com/api/v1/members?status=active&limit=200" \ -H "Authorization: Bearer qh_…"
Member object fields: id, email, first_name, last_name, phone, status, joined_at, created_at.
Write endpoints
POST /members — members:write
curl -s -X POST https://quilthosting.com/api/v1/members \
-H "Authorization: Bearer qh_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: zap-01H8XYZ" \
-d '{"email":"member@example.com","first_name":"Ada","status":"pending"}'
Body: email (required), first_name, last_name, phone, status (pending | active | lapsed | cancelled; default pending). Returns 201 {"member": {…}}. Creating with active uses a slot against the free plan's 30-active-member limit (402 plan_limit when full). A duplicate email returns 409 duplicate_email with the existing member_id.
PATCH /members/:memberId — members:write
Body: any of first_name, last_name, phone, status. Email cannot be changed here — a mistyped Zap would silently split a member's history in two. Change email in the admin.
Idempotency-Key
Accepted on POST /members and PATCH /members/:id only. Strongly recommended on create: Zapier and Make retry on timeout, and without a key a retried create hits the duplicate-email guard and reports failure for a member that was in fact created.
- Same key, same body → the original response is replayed (kept for about 24 hours, worst case about 48).
- Same key, different body (or a different
memberId) → 422idempotency_key_reuse. - Same key while the first request is still running → 409
idempotency_in_progresswithRetry-After: 2. Wait and retry; this is not an error. - 402 and 5xx responses are not cached, so a retry after the condition clears runs for real.
- The key is scoped per operation, so reusing one id for a create and a later update of the same member is safe.
This is a 60-second concurrency guard, not an end-to-end exactly-once guarantee; details in the repo's docs/api.md.
REST hooks
POST /hooks — hooks:write
curl -s -X POST https://quilthosting.com/api/v1/hooks \
-H "Authorization: Bearer qh_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://hooks.zapier.com/…","events":["member.created"]}'
Returns 201 {"hook": {"id","url","events","secret"}} — the secret is shown once. URLs must be https and not point at private networks or QuiltHosting itself. Unknown event names are rejected with 400 unknown_event, never silently dropped. Omitting events subscribes to everything (*). Limit 25 hooks per guild (429 hook_limit).
DELETE /hooks/:hookId — hooks:write
Returns 200 {"deleted": true}.
Outbound webhooks
Hooks (and endpoints added under Admin → Zapier) receive a POST for each event:
| Event | When |
|---|---|
member.created | A member record is created (admin, join form, or API — not CSV import) |
member.activated | A member becomes active |
member.updated | A member's details or status change (carries previous_status and status) |
membership.activated | A membership becomes active, with level details |
payment.succeeded | A checkout completes |
event.registration | Someone takes an event seat (free, waitlist or paid) |
form.response | A public form is submitted |
{
"id": "delivery-uuid",
"schema_version": 1,
"event": "member.activated",
"created_at": "2026-09-08T12:00:00.000Z",
"tenant_id": "…",
"data": { "source": "join_form", "member_id": "…", "email": "…", "level_id": "…" }
}
Headers: X-QH-Event, X-QH-Delivery ({outbox-id}:{endpoint-id}, constant across retries of the same delivery), X-QH-Timestamp (unix seconds), X-QH-Schema-Version, and X-QH-Signature = HMAC-SHA256 hex of {timestamp}.{raw body} using the hook secret. Verify the signature, reject timestamps older than five minutes, and dedupe on id — delivery is at-least-once.
A 2xx response counts as delivered. Anything else is retried up to 6 attempts with jittered backoff (roughly 2.5–5 min, 12–25 min, 1–2 h, then 5–10 h), after which the event is marked dead. An endpoint that fails 20 times in a row is switched off; Admin → Zapier shows an auto-disabled badge with a Re-enable button, a Recent deliveries list with status, attempts and last error, and Replay for failed or dead events. Test sends a test.ping directly (it does not carry X-QH-Delivery).
Zapier and Make
- Admin → API → create a key with the scopes you need and copy it.
- In Zapier, create a Zap with Webhooks by Zapier → Catch Hook and copy its URL.
- Either paste the URL under Admin → Zapier → Add endpoint (choose events, save the signing secret shown once, click Test), or subscribe it with
POST /hooks. - For actions, use Webhooks by Zapier → Custom Request against
POST /memberswith anIdempotency-Keysuch as the Zap's task id.
There is also a native Zapier app (private, not listed in the Zapier directory) with New Member and New Event Registration triggers and a Create Member action. Polling /members or /payments on a schedule and filtering by created_at also works.
Error codes
Errors are {"error": "message", "code": "…"}.
| Code | Status | Meaning |
|---|---|---|
| (none) | 401 | Missing or invalid API key |
missing_field | 400 | A required field was absent |
invalid_status | 400 | Status not in the allowed list (valid array included) |
no_fields | 400 | PATCH body had nothing to change |
unknown_event | 400 | Event name not in the catalog (valid array included) |
invalid_hook_url | 400 | Not https, or a blocked host |
plan_limit | 402 | Free plan active-member limit reached |
insufficient_scope | 403 | Key lacks the required scope (required included) |
not_found | 404 | No such member or hook in this guild |
duplicate_email | 409 | A member already uses that email (member_id included) |
idempotency_in_progress | 409 | Same key still executing; retry after Retry-After |
idempotency_key_reuse | 422 | Key reused with a different body |
hook_limit | 429 | 25 hooks per guild reached |
event_prepare_failed | 500 | The webhook event could not be prepared; nothing was written |
Limits and notes
- No per-key rate limit is enforced today. Be a good citizen; poll no more often than every few minutes.
/eventsand/paymentsreturn at most 200 rows;/membersis paginated (offset-based, offsets capped at 100,000).- Versioning is by URL path (
/api/v1); webhook payloads carry their ownschema_version. - CSV imports do not fire
member.created; poll/membersafter an import. - The admin and portal use their own sign-in sessions, not API keys. The CSV importer is an admin route, not part of the API.
- Full contract for developers:
docs/api.mdanddocs/zapier-webhooks.mdin the repository.