Developer

Safebird-Daten in deinen Systemen

Leads, Bedarfsanalysen, Termine und Gesprächs-Intelligenz — alles, was Safebird erzeugt, erreichst du über eine versionierte REST-API, signierte Webhooks und einen MCP-Server für KI-Agenten.

API-Schlüssel erstellen

API-Schlüssel und Webhook-Endpunkte verwaltest du im Dashboard unter Integrationen.

Quick Start

1API-Schlüssel erstellen
Im Dashboard unter Integrationen → API-Schlüssel. Der Schlüssel wird genau einmal angezeigt und gilt für deinen gesamten Workspace.

2Ersten Request senden

Jeder Request trägt den Schlüssel als Bearer-Token:

curl https://safebird.ai/api/v1/leads?limit=5 \
  -H "Authorization: Bearer sb_live_..."

3Antwort lesen

Alle Antworten tragen dieselbe Hülle: api_version, data und optional meta (Paginierung, Cursor).

{
  "api_version": "v1",
  "data": [
    {
      "id": "8a5c…",
      "name": "Max Mustermann",
      "email": "max@example.com",
      "phone": "+49 171 2345678",
      "status": "qualified",
      "source_type": "inbound_email",
      "created_at": "2026-07-01T10:00:00Z"
    }
  ],
  "meta": { "count": 1, "limit": 5, "offset": 0 }
}

Authentifizierung

API-Schlüssel sind Workspace-weit gültig und tragen Scopes. Übergib den Schlüssel als Bearer-Token im Authorization-Header. Es gilt ein Limit von 240 Requests pro Minute je Schlüssel.

Scope	Erlaubt
`read:leads`	Leads lesen (/leads, /leads/:id)
`read:analyses`	Bedarfsanalysen lesen (/leads/:id/analysis)
`read:appointments`	Termine lesen (/appointments)
`read:meetings`	Gesprächs-Intelligenz lesen (/meetings/:id/intelligence)
`read:events`	Ereignis-Feed lesen (/events)
`write:hooks`	Webhook-Endpunkte verwalten (/hooks)

REST-API

Basis-URL: https://safebird.ai/api/v1. Ressourcenorientiert und versioniert — Breaking Changes erscheinen als /api/v2, nie als stille Änderung. Listen paginieren mit limit (max. 200) und offset.

Endpunkt	Scope	Beschreibung
GET `/leads`	`read:leads`	Leads der Pipeline, neueste zuerst.Parameter: limit, offset, status, search, include_archived
GET `/leads/:id`	`read:leads`	Ein Lead inklusive geparster Kontaktdaten.
GET `/leads/:id/analysis`	`read:analyses`	Die beste verfügbare Bedarfsanalyse des Leads (qualitäts-gerankt über Chat- und Call-Kanal).
GET `/appointments`	`read:appointments`	Termine, neueste zuerst.Parameter: limit, offset, status, from
GET `/meetings/:id/intelligence`	`read:meetings`	Gesprächs-Intelligenz eines Termins: Zusammenfassung, nächste Schritte, Scores mit Begründung.
GET `/events`	`read:events`	Ereignis-Feed (Cursor-Paginierung). Speichere meta.next_cursor und übergib ihn als ?after= — so verpasst dein System nie ein Ereignis, auch ohne Webhooks.Parameter: after, types, limit
GET `/hooks`	`write:hooks`	Registrierte Webhook-Endpunkte auflisten.
POST `/hooks`	`write:hooks`	Webhook-Endpunkt anlegen (REST-Hooks-Muster für Zapier/Make: { target_url, event_types[], label? }).
DELETE `/hooks/:id`	`write:hooks`	Webhook-Endpunkt entfernen.
GET `/hooks/sample`	`write:hooks`	Beispiel-Payloads je Ereignistyp (?type=lead.created) — z. B. für Feld-Mapping in Zapier oder Make.

Ereignisse & Webhooks

Wenn in Safebird etwas passiert, entsteht ein Ereignis — mit den Daten direkt im Payload, nicht nur als Signal. Du empfängst Ereignisse per Webhook (Push) oder über den /events-Feed (Pull). Jeder Ereignistyp hat eine eigene schema_version; Payload-Änderungen erhöhen die Version, die Hülle bleibt stabil.

Ereignis	Bedeutung	Payload enthält
`lead.created`	Neuer Lead	Kontaktdaten, Quelle, Status, Produkt-Klassifikation
`lead.stage_changed`	Lead-Phase geändert	Status/Phase vorher und nachher, Auslöser
`lead.archived`	Lead archiviert	Lead-ID, Archivierungsgrund
`analysis.completed`	Analyse abgeschlossen	Vollständige strukturierte Bedarfsanalyse, Kanal (Chat/Call)
`appointment.scheduled`	Termin angelegt	Titel, Zeitraum, Plattform, Meeting-Link, Kunde
`appointment.cancelled`	Termin abgesagt	Termin-Daten des abgesagten Termins
`meeting.intelligence_ready`	Gesprächs-Intelligenz fertig	Zusammenfassung, nächste Schritte, Score, konfigurierte Felder

Die Ereignis-Hülle

Webhook-Zustellungen und der /events-Feed liefern dieselbe Hülle. data enthält die eigentlichen Inhalte; links verweist auf Lead/Session für Detailabfragen über die REST-API.

{
  "id": "00000000-0000-4000-8000-00000000e0e0",
  "event_type": "lead.created",
  "schema_version": "1",
  "occurred_at": "2026-07-04T08:00:00.000Z",
  "object_type": "lead",
  "object_id": "00000000-0000-4000-8000-000000000001",
  "links": {
    "lead_id": "00000000-0000-4000-8000-000000000001",
    "session_id": null
  },
  "data": {
    "lead_id": "00000000-0000-4000-8000-000000000001",
    "name": "Max Mustermann",
    "email": "max.mustermann@example.com",
    "phone": "+49 171 2345678",
    "source_type": "inbound_email",
    "status": "new",
    "product_domain": "kfz"
  }
}

Zustellung & Wiederholungen

Zustellung als HTTPS-POST mit JSON-Body an deinen Endpunkt.
Antworte mit einem 2xx-Status. Bei 429 und 5xx wiederholt Safebird mit exponentiellem Backoff (bis zu 5 Versuche); andere 4xx gelten als endgültig fehlgeschlagen.
Nach 10 endgültig fehlgeschlagenen Zustellungen in Folge wird der Endpunkt automatisch pausiert — du siehst das im Dashboard und kannst ihn wieder aktivieren.
Zustellung ist at-least-once: dedupliziere bei Bedarf über die Ereignis-id.

Signatur prüfen

Jede Zustellung ist HMAC-SHA256-signiert. Der Header X-Safebird-Signature enthält v1=<hex>; signiert wird die Zeichenkette "<timestamp>.<body>" mit deinem Signing-Secret.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifySafebirdWebhook(req, secret) {
  const timestamp = req.headers["x-safebird-timestamp"];
  const [version, signature] = req.headers["x-safebird-signature"].split("=");
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${req.rawBody}`, "utf8")
    .digest("hex");
  return (
    version === "v1" &&
    timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"))
  );
}

MCP-Server (für KI-Agenten)

Der MCP-Server macht deine Safebird-Daten für KI-Agenten nutzbar — Claude, ChatGPT-Connectoren oder eigene Agenten fragen Leads, Analysen und Termine direkt ab. Transport: Streamable HTTP (stateless), Authentifizierung wie bei der REST-API per API-Schlüssel.

Endpunkt: https://safebird.ai/api/mcp

Tool	Beschreibung
`search_leads`	Leads nach Name, E-Mail oder Telefon durchsuchen
`get_lead`	Einen Lead per ID abrufen
`get_lead_analysis`	Bedarfsanalyse eines Leads abrufen
`list_appointments`	Termine auflisten
`get_meeting_intelligence`	Gesprächs-Intelligenz eines Termins abrufen
`list_events`	Ereignis-Feed lesen (Cursor-Paginierung)

Verbinden

Claude Code

claude mcp add --transport http safebird https://safebird.ai/api/mcp \
  --header "Authorization: Bearer sb_live_..."

Direkt per JSON-RPC

curl -X POST https://safebird.ai/api/mcp \
  -H "Authorization: Bearer sb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_leads","arguments":{"query":"Mustermann"}}}'

Beispiel-Payloads

So sieht die Ereignis-Hülle konkret aus. Dieselben Beispiele liefert GET /hooks/sample — nützlich für Feld-Mapping in Zapier, Make oder deinem CRM.

lead.created

{
  "id": "00000000-0000-4000-8000-00000000e0e0",
  "event_type": "lead.created",
  "schema_version": "1",
  "occurred_at": "2026-07-04T08:00:00.000Z",
  "object_type": "lead",
  "object_id": "00000000-0000-4000-8000-000000000001",
  "links": {
    "lead_id": "00000000-0000-4000-8000-000000000001",
    "session_id": null
  },
  "data": {
    "lead_id": "00000000-0000-4000-8000-000000000001",
    "name": "Max Mustermann",
    "email": "max.mustermann@example.com",
    "phone": "+49 171 2345678",
    "source_type": "inbound_email",
    "status": "new",
    "product_domain": "kfz"
  }
}

analysis.completed

{
  "id": "00000000-0000-4000-8000-00000000e0e0",
  "event_type": "analysis.completed",
  "schema_version": "1",
  "occurred_at": "2026-07-04T08:00:00.000Z",
  "object_type": "analysis",
  "object_id": "00000000-0000-4000-8000-000000000001",
  "links": {
    "lead_id": "00000000-0000-4000-8000-000000000001",
    "session_id": null
  },
  "data": {
    "channel": "chat",
    "analysis_schema_version": "1",
    "analysis": {
      "kunde_name": "Max Mustermann",
      "kunde_email": "max.mustermann@example.com",
      "kunde_telefon": "+49 171 2345678",
      "gewuenschte_risiken": "Privathaftpflicht, Hausrat",
      "empfehlungen": "Privathaftpflicht mit erhöhter Deckungssumme prüfen."
    }
  }
}

appointment.scheduled

{
  "id": "00000000-0000-4000-8000-00000000e0e0",
  "event_type": "appointment.scheduled",
  "schema_version": "1",
  "occurred_at": "2026-07-04T08:00:00.000Z",
  "object_type": "appointment",
  "object_id": "00000000-0000-4000-8000-000000000001",
  "links": {
    "lead_id": null,
    "session_id": null
  },
  "data": {
    "appointment_id": "00000000-0000-4000-8000-000000000002",
    "title": "Beratungsgespräch Max Mustermann",
    "starts_at": "2026-07-10T09:00:00.000Z",
    "ends_at": "2026-07-10T09:45:00.000Z",
    "platform": "google_meet",
    "meeting_url": "https://meet.google.com/abc-defg-hij",
    "customer_display_name": "Max Mustermann",
    "source": "manual"
  }
}

Fragen oder fehlende Endpunkte?

Die API wächst mit den Integrationen unserer Partner. Schreib uns, wenn dir ein Endpunkt, ein Ereignistyp oder ein Connector fehlt.

info@safebird.ai