Leads API

Übersicht

Die Leads API ermöglicht den Zugriff auf alle erfassten Leads. Leads werden automatisch während Chat-Gesprächen erfasst oder können programmatisch über die API erstellt werden.

Leads auflisten

GET /api/v1/leads

Query-Parameter

Beispiel-Request

curl -X GET "https://app.lymbe.ai/api/v1/leads?limit=20&search=musterfirma" \
  -H "X-API-Key: lymbe_sk_dein_api_key"

Beispiel-Response

{
  "leads": [
    {
      "id": "lead_abc123",
      "name": "Anna Müller",
      "email": "anna.mueller@musterfirma.de",
      "phone": "+49 176 12345678",
      "company": "Musterfirma GmbH",
      "message": "Interesse am Enterprise-Plan für 50 Mitarbeiter",
      "botId": "bot_xyz789",
      "conversationId": "conv_def456",
      "source": "widget",
      "status": "new",
      "tags": ["enterprise", "hohe-prioritaet"],
      "createdAt": "2026-03-15T09:30:00Z",
      "updatedAt": "2026-03-15T09:30:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Lead erstellen

POST /api/v1/leads

Request Body

Zod-Validierungsschema

import { z } from 'zod';

export const createLeadSchema = z.object({
  name: z.string().min(1).max(200),
  email: z.string().email(),
  phone: z.string().max(50).optional(),
  company: z.string().max(200).optional(),
  message: z.string().max(5000).optional(),
  botId: z.string().uuid().optional(),
  tags: z.array(z.string().max(50)).max(20).optional(),
});

export type CreateLeadInput = z.infer<typeof createLeadSchema>;

Beispiel-Request

curl -X POST "https://app.lymbe.ai/api/v1/leads" \
  -H "X-API-Key: lymbe_sk_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Max Mustermann",
    "email": "max@example.com",
    "phone": "+49 170 9876543",
    "company": "Beispiel AG",
    "message": "Interesse am Pro-Plan",
    "botId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Beispiel-Response

{
  "lead": {
    "id": "lead_new789",
    "name": "Max Mustermann",
    "email": "max@example.com",
    "phone": "+49 170 9876543",
    "company": "Beispiel AG",
    "message": "Interesse am Pro-Plan",
    "botId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "conversationId": null,
    "source": "api",
    "status": "new",
    "tags": [],
    "createdAt": "2026-03-18T11:00:00Z",
    "updatedAt": "2026-03-18T11:00:00Z"
  }
}

Node.js Beispiel

const API_KEY = process.env.LYMBE_API_KEY!;
const BASE = 'https://app.lymbe.ai/api/v1';

// Lead über die API erstellen
async function createLead(data: {
  name: string;
  email: string;
  phone?: string;
  company?: string;
  message?: string;
  botId?: string;
}) {
  const res = await fetch(`${BASE}/leads`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(data),
  });

  if (!res.ok) {
    const error = await res.json();
    throw new Error(`Lead-Erstellung fehlgeschlagen: ${error.error.message}`);
  }

  const result = await res.json();
  return result.lead;
}

// Alle Leads der letzten 30 Tage abrufen
async function getRecentLeads() {
  const from = new Date();
  from.setDate(from.getDate() - 30);

  let allLeads: any[] = [];
  let offset = 0;
  let hasMore = true;

  while (hasMore) {
    const params = new URLSearchParams({
      from: from.toISOString(),
      limit: '100',
      offset: String(offset),
    });

    const res = await fetch(`${BASE}/leads?${params}`, {
      headers: { 'X-API-Key': API_KEY },
    });

    const data = await res.json();
    allLeads = allLeads.concat(data.leads);
    hasMore = data.pagination.hasMore;
    offset += 100;
  }

  return allLeads;
}