claritos
deenru

LeadConnector

Three ways to connect claritos with LeadConnector — and the marketplace app that brings actions and triggers straight into the LeadConnector workflow builder.

Three routes

Route A: the LeadConnector workflow action “Webhook” calls the HTTP API (Authorization: Bearer capi_…), and claritos webhooks start LeadConnector workflows via the “Inbound Webhook” trigger. Route B: the claritos MCP as an external MCP server in LeadConnector AI agents. Route C: the marketplace app — actions and triggers with form fields instead of JSON. This guide covers route C; A and B only need the “Webhooks” and “MCP” guides.

Installation

From the organisation settings (tab “Integrations” → “Connect LeadConnector”): LeadConnector asks for the location, claritos stores the install (tokens encrypted) and links it to the organisation where the button was pressed. Alternatively install from the LeadConnector marketplace — then External Authentication (next section) links the location to the organisation.

External Authentication (API key)

When connecting the app in LeadConnector the user enters a claritos API key. LeadConnector verifies it against the verify URL; claritos answers with the organisation and remembers the location ↔ organisation link. From then on LeadConnector sends the key as Authorization header with every action — scopes, rate limits, request log and the clients-data gate apply as for any API call.

http
POST https://www.claritos.io/api/integrations/leadconnector/external-auth
Content-Type: application/json

{ "apiKey": "capi_…", "locationId": "ve9EPM428h8vShlRW1KT" }

200 { "organizationId": "org_…", "organizationName": "Muster GmbH", "locationId": "ve9EPM428h8vShlRW1KT" }

Actions (custom workflow actions)

Each action is a field mapping onto exactly one API endpoint and returns its response (fields usable in LeadConnector via response mapping). Available: contact-create, task-create, sms-send (SMS via Twilio), quote-create (quote draft), invoice-create (invoice draft), form-response (form response → lead). Errors come as Problem Details (RFC 9457) with the endpoint's HTTP status; LeadConnector shows them in the execution log. New: invoice-issue (finalize an invoice; the response adds `documents` with PDF status and URL, whether the ZUGFeRD XML is ready, where it is, otherwise `pending: xml-not-ready`). Requires `invoices:write`. Also set-custom-field: sets a custom field on the contact (field key and value, an empty value clears it). The action finds the contact by claritos contact ID or by email; it never creates one. If several contacts share the email it answers 409 with the reason contact-ambiguous, if there is none 404 with contact-not-found. The key needs contacts:write.

http
POST https://www.claritos.io/api/integrations/leadconnector/actions/contact-create
Authorization: Bearer capi_…
Content-Type: application/json

{ "data": { "firstName": "{{contact.first_name}}", "lastName": "{{contact.last_name}}", "email": "{{contact.email}}" } }

201 { "id": "ct_…", "type": "PERSON", "displayName": "Anna Muster", … }

Triggers (custom workflow triggers)

When a user adds a claritos trigger in the workflow builder, LeadConnector calls the subscribe URL with a target URL; claritos creates an internal webhook endpoint for it (with backoff, delivery log and alerts like any endpoint) and delivers events in the standard payload. Available: lead_created, contact_created, invoice_paid, invoice_issued, quote_accepted, esign_completed, form_submitted, task_done. Deleting the trigger removes the endpoint; so does disconnecting the location or uninstalling. Also payments: checkout_pending (payment started; with SEPA no money yet), checkout_completed (payment received, unlock here) and checkout_failed (failed, charged back or instalment missed, lock here). The `checkout` payload carries the amount in cents, currency, customer email and name (customerEmail, customerName), link ID and title (checkoutLinkId, checkoutLinkName), for invoices their ID and number, the order (orderId, orderNumber), and for checkout_failed the reason failureReason (direct_debit_failed, chargeback, no_mandate, payment_failed). Invoice, quote and task carry contactEmail so a workflow can find the contact with “Find Contact”. If the app is installed via OAuth, every delivery also carries the installation's access token (Authorization: Bearer, Version header); the signature of the standard payload stays.

json
// LeadConnector → Subscribe-URL (beim Anlegen des Triggers im Workflow)
{ "triggerData": { "id": "trg_…", "key": "invoice_paid", "targetUrl": "https://services.leadconnectorhq.com/hooks/…" },
  "meta": { "locationId": "ve9EPM428h8vShlRW1KT" }, "extras": { "type": "create" } }

// claritos → targetUrl (Standard-Webhook-Nutzlast)
{ "id": "evt_…", "type": "invoices.invoice.paid", "createdAt": "…", "data": { "id": "inv_…", "number": "RE-2026-0042", "totalCents": 119000, … } }

Route A without the app

Without the marketplace app the HTTP API is enough: in LeadConnector the workflow action “Webhook” (method/URL/headers/body as in the reference) — and in claritos a webhook endpoint pointing at the URL of the LeadConnector “Inbound Webhook” trigger (“Webhooks” guide, section “Platforms”). Upside: all 140+ endpoints and all events; downside: JSON instead of form fields.

Route B: MCP in LeadConnector AI agents

LeadConnector conversation AI and voice agents can include external MCP servers. Enter the URL https://www.claritos.io/api/mcp/v1 with an Authorization header (API key) — the agent gets exactly the tools the key allows (“MCP” guide).

Menu entry in LeadConnector (SSO)

claritos can appear as a menu entry in LeadConnector (custom menu link to {BASE}/embed/leadconnector, “Open in iframe”). The page requests the context from the parent window; LeadConnector answers encrypted, we decrypt it with the app's SSO key and show the state of the connection: linked organisation, active triggers, available actions. Deliberate boundary: the context proves the location, not a claritos identity — it creates no sign-in and the page shows no business data.

For operators: marketplace setup

The app is created once per environment in the LeadConnector developer portal (redirect URL, webhook URL for app events, External Authentication with field apiKey and verify URL, custom actions with their fields, custom triggers with subscribe URL, scopes). Client ID and secret go into the app as environment variables; claritos checks the signature of app events (Ed25519) with the public key from the docs. Field names and payloads of the LeadConnector calls are handled tolerantly in code (data/flat, triggerData/meta) — verify against the current marketplace docs on the first run. URLs in the form (no brand in the path): redirect {BASE}/api/integrations/leadconnector/callback, webhook for app events {BASE}/api/integrations/leadconnector/uninstall, verify URL {BASE}/api/integrations/leadconnector/external-auth, actions {BASE}/api/integrations/leadconnector/actions/<key>, subscribe URL {BASE}/api/integrations/leadconnector/triggers, menu entry {BASE}/embed/leadconnector. Older addresses remain reachable as aliases. Scope: only workflows.readonly, because the app does not call the platform's API.