Zapier
The claritos app for Zapier: triggers for every event, actions for every write endpoint, searches for every list — all generated from the spec.
What the app is
A thin adapter (Zapier Platform CLI) over the public API. Nothing domain-specific lives in the app: triggers are webhook subscriptions, actions and searches call the HTTP endpoints. The code lives in the main repository under integrations/zapier; the domain parts (generated/) are produced from the OpenAPI spec and the event catalog and follow every API version automatically.
Connecting
On the first Zap, Zapier asks for a claritos API key (capi_…, organisation settings → API) and the environment (production or staging). Zapier checks the key via GET /me and shows the organisation name as the connection name. The key's scopes decide which triggers and actions work — missing scopes show up in the Zap history as 403 insufficient-scope.
Triggers (REST hooks)
One trigger per event type (“New Lead”, “Invoice Paid”, “Signature Request Completed” …). When a Zap is switched on, Zapier creates a subscription for exactly that event type via POST /webhooks (visible in the organisation tab “API” → Webhooks); switching it off deletes it. Every delivery is verified against the endpoint secret (Standard Webhooks signature). “Load sample” fetches real recent events via /webhooks/events/{type}/recent and falls back to the documented sample.
POST /api/v1/webhooks
{ "url": "https://hooks.zapier.com/hooks/standard/…", "eventTypes": ["leads.lead.created"], "description": "Zapier — New Lead" }
201 { "id": "wh_…", "secret": "whsec_…", … } ← Zapier merkt sich id + secret (performSubscribe)Actions and searches
Actions correspond to the write endpoints (create contact, issue invoice, send SMS, request signature …); fields come from the body schema, nested fields (items, values) are entered as JSON. Searches correspond to the list endpoints with search term and filters and return the first page. Clients-data endpoints (clients.*) and webhook management are deliberately not included as actions. Errors arrive as Problem Details (RFC 9457) with title, detail and field errors; 429 is reported as a Zapier throttle.
Generation and versions
pnpm api:openapi in the main repository writes the spec, the event catalog (docs/api/events.v1.json) and the generated platform files; pnpm api:check requires everything to be committed. The app version is the spec version. Tests (npm test) check structure and signature verification without network; zapier validate checks the schema.
pnpm api:openapi # Spec + Ereigniskatalog + generierte Plattform-Dateien
cd integrations/zapier && npm install && npm test
npx zapier validate && npx zapier push # oder Tag zapier-v<version>For operators: publishing
Once: Zapier developer account, zapier login, zapier register “claritos” (app id → secret ZAPIER_APP_ID), deploy key → secret ZAPIER_DEPLOY_KEY. From then on the publish-zapier workflow publishes on every tag zapier-v<version> (validate + push). Public listing requires a Zapier review; until then the app can be used via an invite link.