REST-API

Leads

Leads aus deinem Workspace auflisten und neue Leads aus eigenen Formularen oder Systemen anlegen.

Wofür

Leads sind Kontaktanfragen, die deine Assistenten im Gespräch aufnehmen. Über die API holst du sie in dein CRM oder legst selbst Leads an, die dann im Lead-Posteingang erscheinen und dieselben Benachrichtigungen und Abläufe auslösen wie Leads aus dem Widget.

GET /leads

Parameter	Typ	Standard	Bedeutung
`limit`	Zahl	50	Anzahl je Seite, höchstens 100
`offset`	Zahl	0	Einträge überspringen
`botId`	Text	–	Nur Leads dieses Assistenten

curlbash

curl "https://app.lymbe.ai/api/v1/leads?limit=50" \
  -H "x-api-key: lymbe_DEIN_SCHLUESSEL"

Antwort 200json

{
  "leads": [
    {
      "id": "cmg9x8y7z0001",
      "botId": "BOT_ID",
      "name": "Max Mustermann",
      "email": "max@example.com",
      "phone": "+49 30 1234567",
      "company": "Beispiel GmbH",
      "message": "Bitte um Rückruf wegen Angebot",
      "source": "widget",
      "status": "NEW",
      "conversationId": "cmg1a2b3c0001",
      "createdAt": "2026-10-17T09:15:02.000Z"
    }
  ],
  "pagination": { "total": 87, "limit": 50, "offset": 0, "hasMore": true }
}

POST /leads

Legt einen neuen Lead für einen Assistenten an. Der Körper ist JSON.

Feld	Pflicht	Bedeutung
`botId`	ja	Kennung des Assistenten, dem der Lead zugeordnet wird
`name`	nein	Name der Person
`email`	nein	E-Mail-Adresse; muss gültig sein, wenn angegeben
`phone`	nein	Telefonnummer
`company`	nein	Firma
`message`	nein	Anliegen oder Notiz

curlbash

curl -X POST https://app.lymbe.ai/api/v1/leads \
  -H "x-api-key: lymbe_DEIN_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "botId": "BOT_ID",
    "name": "Erika Musterfrau",
    "email": "erika@example.com",
    "message": "Anfrage aus dem Kontaktformular"
  }'

fetchjavascript

const res = await fetch('https://app.lymbe.ai/api/v1/leads', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.LYMBE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    botId: 'BOT_ID',
    name: 'Erika Musterfrau',
    email: 'erika@example.com',
    message: 'Anfrage aus dem Kontaktformular',
  }),
});
if (res.status === 201) {
  const { lead } = await res.json();
  console.log('Lead angelegt:', lead.id);
}

Bei Erfolg antwortet die API mit 201 und {"lead": {…}}.

Was ein neuer Lead auslöst

Er erscheint sofort im Lead-Posteingang.
Die Benachrichtigungen des Assistenten für „Neue Anfrage erfasst“ gehen raus (E-Mail, Slack, Teams, eigener Endpunkt).
Abläufe mit dem Auslöser für neue Leads starten (siehe Auslöser).

Auch beim TestenEin Lead, den du zum Ausprobieren anlegst, ist ein echter Lead und löst alles oben Genannte aus. Teste am besten mit einem eigenen Test-Assistenten.

Fehler

Status	Antwort	Ursache
400	`{"error":"Validation error","details":[…]}`	`botId` fehlt oder E-Mail ungültig
403	`{"code":"NUR_LESEN", …}`	Dein Workspace ist gerade nur lesbar, z. B. wegen offener Zahlung
429	–	100 Anfragen pro Stunde überschritten oder Lead-Grenze deines Tarifs erreicht
500	`{"error":"Internal server error"}`	Häufigster Grund: Die `botId` gibt es in deinem Workspace nicht. Prüfe sie mit GET /bots.

Datenschutz

Lege nur Leads von Personen an, die dir ihre Daten für eine Kontaktaufnahme gegeben haben.
Leads unterliegen der Aufbewahrung deines Workspaces.

Häufige Fragen

Frage	Antwort
Kann ich Leads über die API ändern oder löschen?	Nein. Status ändern und löschen geht im Lead-Posteingang.
Kann ich eigene Felder mitschicken?	Nein, die API nimmt nur die sechs Felder oben an. Weitere Angaben schreibst du in `message`.
Woher bekomme ich die botId?	Aus GET /bots.

VorherigeGespräche NächsteAssistenten