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 & Webhooks → 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. Fehlgeschlagene Authentifizierungen werden zusätzlich pro IP begrenzt.

Scope	Erlaubt
`read:leads`	Leads lesen (/leads, /leads/:id)
`read:analyses`	Bedarfsanalysen lesen (/leads/:id/analysis)
`read:kontakte`	Haushalts-Datensätze lesen (/kontakte, /kontakte/:key/haushalt)
`read:appointments`	Termine lesen (/appointments)
`read:meetings`	Gesprächs-Intelligenz lesen (/meetings/:id/intelligence)
`read:events`	Ereignis-Feed lesen (/events) — Achtung: Ereignis-Payloads enthalten Lead-, Analyse- und Haushalts-Daten. Dieser Scope sieht also mehr als read:leads oder read:analyses einzeln.
`write:hooks`	Webhook-Endpunkte verwalten (/hooks) — Achtung: entspricht einem Datenabfluss-Recht. Wer diesen Scope hat, kann eine beliebige HTTPS-URL für lead.created oder analysis.completed abonnieren und bekommt die vollständigen Payloads zugestellt, auch ohne read:*-Scope. Nur für Zapier/Make-Verbindungen vergeben.

Vergib Scopes sparsam: write:hooks ist datenabfluss-äquivalent und read:events ist eine PII-Obermenge der übrigen Lese-Scopes. Für reine Lese-Integrationen reichen die read:*-Scopes ohne write: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 kanonische DIN-Bedarfsanalyse des Leads: flache Export-Projektion (analysis), nested din_core_v2 (analysis_v2) und DIN-Check.
GET `/kontakte`	`read:kontakte`	Haushalts-Datensätze je Kontakt: Verträge-Zähler, DIN-Lücken je Bedarfsstufe, Parameterstand.Parameter: limit, offset
GET `/kontakte/:key/haushalt`	`read:kontakte`	Das akkumulierte DIN-Bedarfsprofil eines Kontakts (din_core_v2-Form inkl. DIN-Check; ohne Roh-Einkommensbeträge). :key ist der Identity-Schlüssel (email:… / phone:… / lead:…), URL-encodiert.
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	Strukturierte DIN-Bedarfsanalyse (din_core_v2) inkl. DIN-Check, Kanal (Chat/Call) — ohne Roh-Einkommensbeträge
`din.check_completed`	DIN-Check berechnet	Kanal, Parameterstand, Lücken je Bedarfsstufe (Zähler), ungeklärte Themen (Zähler)
`haushalt.updated`	Bedarfsprofil aktualisiert	Kontakt-Schlüssel, Quelle, geänderte Sektionen, Verträge-/Lücken-Zähler
`kontakt.merged`	Kontakte zusammengeführt	Die beiden zusammengeführten Identity-Schlüssel
`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.000000+00:00",
  "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_kontakte`	Zusammengeführte Kontakte auflisten (Person über E-Mail/Telefon vereint)
`get_haushalt`	DIN-Bedarfsprofil eines Kontakts abrufen (Soll/Ist, ohne Roh-Einkommensbeträge)
`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.000000+00:00",
  "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": "2",
  "occurred_at": "2026-07-04T08:00:00.000000+00:00",
  "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": "din_core_v2+property_casualty_sach_pc_v4",
    "analysis": {
      "meta": {
        "version": "din_core_v2",
        "erstellt_am": "2026-07-04T08:00:00.000Z"
      },
      "kunde": {
        "name": "Max Mustermann",
        "alter": 34,
        "adresse": {
          "strasse": null,
          "plz": "50667",
          "ort": "Köln"
        },
        "kontakt": {
          "telefon": "+49 171 2345678",
          "email": "max.mustermann@example.com"
        }
      },
      "haushalt": {
        "haushaltsgroesse": 3,
        "kinder_anzahl": 1,
        "beziehungsstatus": "verheiratet",
        "personen": [
          {
            "rolle": "kunde",
            "alter": 34,
            "taetigkeitsstatus": "angestellt",
            "kv_status": "gkv"
          },
          {
            "rolle": "partner",
            "alter": 33,
            "eigenes_einkommen_vorhanden": true
          }
        ]
      },
      "vertraege": [
        {
          "sparte": "privathaftpflicht",
          "versicherer": "Beispiel Versicherung",
          "status": "aktiv"
        }
      ],
      "din_check": {
        "bewertung": {
          "params_version": "DIN_PARAMS_2026_03",
          "engine_version": "din_engine_v1",
          "zeilen": [
            {
              "rang": "1.06",
              "name": "Berufsunfähigkeit",
              "bedarfsstufe": 1,
              "in_analyse": true,
              "relevant": true,
              "relevanz_quelle": "regel",
              "status": "luecke",
              "sollwert": {
                "typ": "einkommensersatz",
                "wert_eur": 2560,
                "einheit": "eur_monat",
                "beschreibung": "80% des Nettoeinkommens"
              },
              "istwert": {
                "wert_eur": 0,
                "beschreibung": null,
                "quellen": []
              }
            }
          ],
          "luecken_nach_stufe": [
            {
              "stufe": 1,
              "themen": [
                "Berufsunfähigkeit"
              ]
            }
          ],
          "unbekannt_in_analyse": [
            "Pflegevorsorge"
          ]
        },
        "erstellt_am": "2026-07-04T08:00:00.000Z"
      }
    }
  }
}

appointment.scheduled

{
  "id": "00000000-0000-4000-8000-00000000e0e0",
  "event_type": "appointment.scheduled",
  "schema_version": "1",
  "occurred_at": "2026-07-04T08:00:00.000000+00:00",
  "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