If you want reliable, scalable status updates and good debugging, webhooks are strongly recommended. Polling is more fragile and expensive.

Lindy API - Complete Developer Guide

Q: Is Lindy an API or an app?

Lindy is primarily an automation assistant platform. “API” often refers to how you trigger workflows and integrate via webhooks, connectors, and custom actions.

Q: How do I prevent the same automation running twice?

Use idempotency keys for triggers and deduplicate incoming webhook events by event_id in your database.

1) What the Lindy API is (and what “API” usually means)

When developers say “Lindy API,” they usually mean one or more integration surfaces: triggering workflows, connecting third-party tools, receiving webhooks, and embedding automation into multi-user products.

A. Trigger API

Start a workflow from your app. Typical pattern: job/execute → returns a job ID.

“Purchase completed → onboarding assistant”
“Lead created → follow-up email + schedule”
“Ticket arrives → draft reply + tag”

B. Connector APIs

Allow Lindy to act in tools via OAuth, scopes, and per-user authorization.

Email + calendar actions
Slack messaging
CRM / Notion / Sheets updates
Custom HTTP actions to your backend

C. Webhooks

Lindy notifies you about progress, completion, errors, and approval requests.

Workflow completed
Email sent / failed
Human approval required
Output generated (JSON, summary, score)

D. Agent embedding

Build “automation agents” in your SaaS: multi-tenant, per-user credentials, audit trails.

User mapping (your IDs ↔ Lindy IDs)
Isolation + privacy boundaries
Per-tenant rate limits
Auditable execution logs

Event-driven Job execution OAuth scopes Webhook verification Multi-tenant

2) Core concepts: agents, workflows, triggers, actions, and tools

Most assistant automation platforms share these building blocks. Use them to design predictable, safe automations.

Agent (behavior layer)

Role/goal (“Sales follow-up assistant”)
Tool permissions (email, calendar, CRM)
Guardrails (approval gates, allowed domains)
Tone and templates (email style rules)

Workflow (process layer)

Trigger → fetch context → draft output
Approve? → send → log result
Deterministic vs agentic vs hybrid

Triggers

In-app events (your backend → Lindy)
Schedules (“every morning at 8”)
External events (CRM update, calendar invite)
Inbound email events

Human-in-the-loop approvals

Approve before first-touch outreach
Require approval for pricing/legal/refunds
“Draft-only” mode until trust is earned

High-signal guardrail: Separate draft from send. Most production failures come from acting too early.

3) How Lindy fits into a modern product stack

The most common production architecture is event-driven: your app triggers workflows, Lindy runs the automation, and webhooks update your system.

Recommended architecture

Your app emits events (lead created, ticket opened, call ended)
Your backend triggers Lindy workflow (execute/job endpoint)
Lindy runs steps using tools/connectors
Lindy sends webhook events (progress, approval required, complete)
Your system stores results in DB and updates UI

Why this beats polling

Scales better
Fewer wasted requests
Cleaner reliability and observability

Source of truth rule

Store inputs sent
Execution IDs + timestamps
Structured outputs
Approval decisions
Error codes + retries

4) Common use cases (real product patterns)

These patterns help you design payloads, guardrails, and event flows that behave well at scale.

1) Sales follow-up

Trigger: lead created • Actions: enrich → draft → follow-up schedule → CRM update

Keep a lead profile schema
Frequency caps + “do not contact”
Approval gate for first touch

2) Recruiting coordination

Trigger: candidate stage change • Actions: propose times → coordinate calendars → invite

Deterministic time window rules
Clear per-recruiter permissions
Fallback: ask human if no slots

3) Support triage + drafting

Trigger: new ticket/thread • Actions: categorize → extract → draft → tag

Policy constraints (refund rules)
Approvals for billing/cancellations
Drafting ≠ sending

4) Meeting-to-actions

Trigger: call ended + transcript • Actions: summarize → actions → tasks → recap email

Store transcript references
Consistent JSON outputs
Create tasks in your system

5) Internal ops

Trigger: invoice received • Actions: extract → validate → approval → accounting update

Always require approval
Supplier allowlists + totals checks
Audit logging

Common UI states

Running… (progress)
Needs approval (action required)
Completed (output ready)
Failed (next steps)

5) Authentication & security model (what to think about)

Design as if webhooks and tokens are constantly under attack. Your defaults should be safe.

A. Two authentication types

Server-to-server auth (backend → Lindy)
User OAuth (user grants access to Gmail/Calendar/CRM)

B. Scope minimization

Draft-only? Don’t request delete scopes
Read availability? Avoid calendar write scopes

C. Credential isolation

Never share credentials across tenants
Keep mapping: app_user_id → lindy_workspace_id

D. Webhook verification

Verify signature + timestamp
Reject unknown sources
Replay protection (nonce/event ID)

6) Webhooks and event-driven integrations

Webhooks provide scalable status updates and reliable UX. Treat them like public internet traffic.

Webhook types you typically want

execution.started
execution.step.completed
execution.needs_approval
execution.completed
execution.failed
execution.canceled

Your receiver should

Validate signature
Schema-validate payload
Store with idempotency key
Update DB + trigger UI refresh

Idempotency is non-negotiable: webhook deliveries may repeat. Deduplicate by event_id.

7) Executions: job model, statuses, retries, and idempotency

Treat each run as a job in your system. Store it, track it, and make it safe to retry.

Execution states

queued, running
waiting_for_approval
succeeded, failed, canceled

Retry strategy

Retry timeouts and 5xx
Don’t blindly retry 4xx
Exponential backoff + jitter
Max retry window (10–20 min)

Idempotency key pattern

Use a unique key per business event so network retries don’t trigger duplicate runs.

Pseudo request header

Idempotency-Key: <uuid>
X-Trace-Id: <trace_id>

8) Data and memory: context, knowledge bases, and privacy boundaries

Bad automations usually come from bad inputs. Provide structured, scoped context—not entire database dumps.

Recommended payload design

user_profile (safe fields only)
object (lead/ticket/candidate fields)
history (last messages only)
policies (rules + constraints)

Privacy boundary rule

Never send secrets you don’t want repeated
Use references/IDs instead of raw sensitive data
Fetch sensitive data via your backend proxy

9) Multi-tenant architecture: user-by-user integrations

If you’re building a SaaS on top of Lindy, treat automation as multi-tenant infrastructure.

Data model (example)

users
lindy_accounts (workspace mapping)
lindy_integrations (provider, scopes)
automation_executions
automation_events

Guardrails

Pre-check: automation enabled?
Pre-check: integrations connected?
Per-tenant rate limits
Audit trail always on

10) Cost control: throttling, caching, batching, and guardrails

Predictable cost comes from fewer repeated runs and safer defaults.

Cost levers

Rolling summaries (incremental updates)
Batch low-stakes tasks
Confidence thresholds → approval
Frequency caps for outreach

Safety vs spend

Start in draft-only
Enable “send” behind approvals
Automate more as success rate stabilizes

11) Observability: logs, traces, metrics, and audits

To run automations at scale, you need a flight recorder: executions, events, outputs, and decisions.

Minimum fields to log

execution_id, workflow_id
app_user_id, trigger_event_id
Start/end timestamps
Status + steps completed
Sanitized error codes/messages

Useful metrics

Success rate per workflow
Latency (p50/p95)
Approval rate
Tool failure rates (429/timeout)
Cost per execution (if available)

Audit tip: For regulated flows, record who approved what, when, and what data was used (append-only logs).

12) Reliability engineering: failure modes and fallback strategies

Automations fail in predictable ways. Plan for them and build graceful fallbacks.

Common failure modes

Missing/stale integrations
Ambiguous instructions
Third-party rate limits
Duplicate triggers

Fallbacks

Switch to draft-only
Notify a human with context
Retry later with backoff
Alternate tool path (e.g., create task if email fails)

13) Example integration patterns (with pseudo-API contracts)

These are vendor-agnostic contract shapes you can map to Lindy’s interface: trigger → webhooks → approvals.

Pattern 1: Trigger a workflow

Request JSON

{
  "workflow_id": "wf_sales_followup",
  "inputs": {
    "lead_id": "L_123",
    "lead_email": "lead@company.com",
    "lead_name": "A. Perera",
    "company": "ExampleCo",
    "source": "web_form",
    "notes": "Asked about pricing"
  },
  "metadata": {
    "app_user_id": "U_999",
    "trace_id": "tr_abc123"
  }
}

Response JSON

{
  "execution_id": "ex_456",
  "status": "queued"
}

Pattern 2: Completion webhook

Webhook event

{
  "event_id": "evt_001",
  "type": "execution.completed",
  "execution_id": "ex_456",
  "workflow_id": "wf_sales_followup",
  "outputs": {
    "email_subject": "Quick follow-up",
    "email_body": "Hi A. Perera,...",
    "crm_updated": true,
    "next_followup_at": "2026-02-10T09:00:00Z"
  },
  "timestamp": "2026-02-06T10:20:00Z"
}

Pattern 3: Human approval required

{
  "event_id": "evt_002",
  "type": "execution.needs_approval",
  "execution_id": "ex_456",
  "approval": {
    "action": "send_email",
    "preview": {
      "to": "lead@company.com",
      "subject": "Quick follow-up",
      "body": "Hi A. Perera,..."
    }
  }
}

UI flow: Approve → call approval endpoint • Reject → cancel • Edit → update draft then approve.

Pattern 4: Safe custom action (your internal API)

Expose narrow endpoints so sensitive operations remain controlled and auditable.

POST /automation/create_task
POST /automation/update_lead_stage
POST /automation/log_activity

14) Testing & environments (dev/staging/prod)

Treat automations like product features: versioned workflows, test data, and structured regression checks.

Environments

Dev: sandbox integrations, test inbox
Staging: production-like but isolated
Prod: real operations

Test strategy

Unit test webhook verification + parsing
Integration test happy paths
Chaos test duplicates + timeouts
Regression tests for policy enforcement

15) Deployment checklist (ship-ready)

Use this as your “go live” gate. If you can’t answer one item, don’t ship yet.

Webhook signature verification enabled

Idempotency strategy implemented

DB stores executions + events

Draft vs Send guardrails set

Approval UI exists for risky actions

Rate limits + retries configured

Error notifications to humans (Slack/email)

Redaction for sensitive logs

Integration reconnection UX

Monitoring dashboards in place

Rollback switch to disable automations

Approval/audit trail stored append-only

16) FAQ (developer-focused)

Quick answers to the questions builders ask before integrating.

Is Lindy an API or an app?

It’s primarily an automation assistant platform. “API” usually means how you trigger workflows and integrate with tools (webhooks, connectors, custom actions).

Can I call Lindy from my backend?

In most designs, yes: your backend posts events to start workflows and listens for webhooks to track completion, approval requests, and failures.

How do I prevent the same automation running twice?

Use an idempotency key tied to the business event (like a lead-created event ID) and dedupe webhook events by event_id in your database.

Do I need webhooks?

If you want reliable, scalable UX and strong debugging, yes. Polling is usually more fragile and expensive.

How do I keep it safe in production?

Start in draft-only mode, add approval gates for external actions, enforce strict policies (allowed domains, frequency caps), and invest early in logs + monitoring + rollback controls.

Can I build a multi-user SaaS on top of Lindy?

Yes—treat it as multi-tenant infrastructure: per-user integration grants, per-tenant rate limiting, strict data isolation, and auditable execution logs.