REST-API-Referenz

Übersicht

LeadHub enthält eine vollständige REST-API, mit der externe Tools Ihre Daten lesen und schreiben können — Leads, Pipelines, Automatisierungen, Formulare und mehr. Nutzen Sie sie für die Integration mit Zapier, den Aufbau benutzerdefinierter Dashboards, die Verbindung Ihrer Website oder die Automatisierung von allem.

Basis-URL

Alle API-Anfragen gehen an:

https://yourdomain.com/api/v1

Ersetzen Sie yourdomain.com durch Ihre tatsächliche LeadHub-Domain.

Authentifizierung

Jede Anfrage (außer dem Health Check) erfordert einen API-Schlüssel.

Erstellen Sie API-Schlüssel im Admin-Panel unter Einstellungen → API-Schlüssel. Anleitungen finden Sie auf der Einstellungsseite.

Fügen Sie Ihren API-Schlüssel bei jeder Anfrage als Bearer-Token im Authorization-Header ein:

Authorization: Bearer lh_your_api_key_here

Wenn Sie eine Anfrage ohne API-Schlüssel oder mit einem ungültigen Schlüssel senden, erhalten Sie eine 401 Unauthorized-Antwort.

Rate Limiting

Jeder API-Schlüssel ist standardmäßig auf 1.000 Anfragen pro Stunde begrenzt (pro Schlüssel konfigurierbar). Wenn Sie dieses Limit überschreiten, erhalten Sie eine 429 Too Many Requests-Antwort.

Jede Antwort enthält diese Header, damit Sie Ihre Nutzung verfolgen können:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711580400

X-RateLimit-Reset ist ein Unix-Timestamp, wann sich Ihr Limit zurücksetzt.

Paginierung

Endpunkte, die Listen von Datensätzen zurückgeben, unterstützen Paginierung. Fügen Sie diese Query-Parameter hinzu:

Parameter	Standard	Maximum
`page`	`1`	—
`per_page`	`15`	`100`

Beispiel: GET /api/v1/leads?page=2&per_page=25

Antwortformat

Erfolgreiche Antwort

{
  "data": { ... },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73,
    "from": 1,
    "to": 15
  },
  "links": {
    "first": "https://yourdomain.com/api/v1/leads?page=1",
    "last": "https://yourdomain.com/api/v1/leads?page=5",
    "prev": null,
    "next": "https://yourdomain.com/api/v1/leads?page=2",
    "self": "https://yourdomain.com/api/v1/leads?page=1"
  }
}

Bei Einzeldatensatz-Antworten (show, create, update) enthält data das Datensatzobjekt und meta wird weggelassen.

Fehlerantwort

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

Häufige Fehlercodes:

Code	HTTP-Status	Bedeutung
`UNAUTHORIZED`	401	Fehlender oder ungültiger API-Schlüssel
`FORBIDDEN`	403	API-Schlüssel fehlt der erforderliche Scope
`NOT_FOUND`	404	Datensatz existiert nicht
`VALIDATION_FAILED`	422	Anfragedaten haben die Validierung nicht bestanden
`RATE_LIMITED`	429	Zu viele Anfragen
`SERVER_ERROR`	500	Unerwarteter Serverfehler

Health Check

Keine Authentifizierung erforderlich.

GET /api/v1/health

Antwort:

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-28T09:15:00+00:00"
}

Damit können Sie prüfen, ob Ihre LeadHub-Instanz erreichbar ist, bevor Sie andere Anfragen stellen.

Leads

Erforderlicher Scope: read:leads zum Abrufen, write:leads zum Erstellen/Aktualisieren, delete:leads zum Löschen.

Leads auflisten

GET /api/v1/leads

Query-Parameter zum Filtern:

Parameter	Beschreibung
`source`	Nach Quelle filtern (z. B. `facebook`, `website`)
`status`	Nach Status filtern (z. B. `new`, `contacted`, `qualified`)
`pipeline_id`	Nach Pipeline-ID filtern
`stage_id`	Nach Pipeline-Stufen-ID filtern
`assigned_user_id`	Nach zugewiesener Benutzer-ID filtern
`tag`	Nach Tag-Name filtern
`search`	Nach Name, E-Mail oder Telefon suchen
`created_after`	ISO-8601-Datum — nur nach diesem Datum erstellte Leads
`created_before`	ISO-8601-Datum — nur vor diesem Datum erstellte Leads
`starred`	`true` um nur markierte Leads anzuzeigen
`sort`	Sortierfeld: `created_at`, `updated_at`, `lead_score`, `first_name`, `last_name`, `email`
`direction`	`asc` oder `desc` (Standard: `desc`)

Lead abrufen

GET /api/v1/leads/{id}

Lead erstellen

POST /api/v1/leads

Anfrage-Body (JSON):

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "[email protected]",
  "phone": "+14155551234",
  "source": "website",
  "status": "new",
  "pipeline_id": 1,
  "pipeline_stage_id": 2,
  "assigned_user_id": 5,
  "notes": "Interested in the enterprise plan.",
  "custom_fields": {
    "budget": "10000"
  },
  "tags": ["hot-lead", "enterprise"]
}

first_name ist erforderlich. Alle anderen Felder sind optional.

Lead aktualisieren

PUT /api/v1/leads/{id}
PATCH /api/v1/leads/{id}

Senden Sie nur die Felder, die Sie aktualisieren möchten. Gleiche Felder wie beim Erstellen.

Lead löschen

DELETE /api/v1/leads/{id}

Tag zu einem Lead hinzufügen

POST /api/v1/leads/{id}/tags

Body: { "tag": "vip-client" }

Tag von einem Lead entfernen

DELETE /api/v1/leads/{id}/tags/{tag}

Pipelines

Erforderlicher Scope: read:pipelines oder write:pipelines

GET    /api/v1/pipelines
POST   /api/v1/pipelines
GET    /api/v1/pipelines/{id}
PUT    /api/v1/pipelines/{id}
PATCH  /api/v1/pipelines/{id}
DELETE /api/v1/pipelines/{id}

Pipeline-Stufen

GET    /api/v1/pipelines/{pipeline_id}/stages
POST   /api/v1/pipelines/{pipeline_id}/stages
GET    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PUT    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PATCH  /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
DELETE /api/v1/pipelines/{pipeline_id}/stages/{stage_id}

Benutzer

Erforderlicher Scope: read:users, write:users oder delete:users

GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/{id}
PUT    /api/v1/users/{id}
PATCH  /api/v1/users/{id}
DELETE /api/v1/users/{id}

Formulare

Erforderlicher Scope: read:forms, write:forms oder delete:forms

GET    /api/v1/forms
POST   /api/v1/forms
GET    /api/v1/forms/{id}
PUT    /api/v1/forms/{id}
PATCH  /api/v1/forms/{id}
DELETE /api/v1/forms/{id}

Formular absenden

POST /api/v1/forms/{id}/submissions

Body: die Formularfeldwerte als Schlüssel-Wert-Paare.

Automatisierungen

Erforderlicher Scope: read:automations, write:automations oder delete:automations

GET    /api/v1/automations
POST   /api/v1/automations
GET    /api/v1/automations/{id}
PUT    /api/v1/automations/{id}
PATCH  /api/v1/automations/{id}
DELETE /api/v1/automations/{id}

Integrationen

Erforderlicher Scope: read:integrations oder write:integrations

GET    /api/v1/integrations/types
GET    /api/v1/integrations
POST   /api/v1/integrations
GET    /api/v1/integrations/{id}
PUT    /api/v1/integrations/{id}
PATCH  /api/v1/integrations/{id}
DELETE /api/v1/integrations/{id}

GET /api/v1/integrations/types gibt die Liste der verfügbaren Integrationstypen zurück (Facebook, Google Ads, Mailgun usw.).

Eingehende Lead-Aufnahme

Ein vereinfachter Endpunkt zum Erstellen von Leads aus externen Quellen, Webhooks oder No-Code-Tools wie Zapier und Make.

POST /api/inbound/leads?tenant={workspace-slug}

Authentifizieren Sie sich mit Authorization: Bearer {api_key} und übergeben Sie den Workspace-Slug als Query-Parameter.

Anfrage-Body:

{
  "email": "[email protected]",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "phone": "+14155551234",
  "company": "Tech Corp",
  "source": "zapier",
  "notes": "Came from newsletter signup",
  "tags": ["newsletter"],
  "custom_fields": {
    "utm_campaign": "spring-promo"
  }
}

email ist erforderlich. Alle anderen Felder sind optional.

Erfolgsantwort (201):

{
  "status": "created",
  "lead_id": 1842,
  "is_duplicate": false
}

Wenn der Lead bereits existiert (identifiziert per E-Mail oder Telefon), ist is_duplicate true und die ID des vorhandenen Leads wird zurückgegeben.

Codebeispiele

cURL

curl -X GET "https://yourdomain.com/api/v1/leads?status=new&per_page=25" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Accept: application/json"

curl -X POST "https://yourdomain.com/api/v1/leads" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Sarah","email":"[email protected]","source":"api"}'

PHP

$apiKey = 'lh_your_api_key_here';
$baseUrl = 'https://yourdomain.com/api/v1';

// List leads
$response = file_get_contents($baseUrl . '/leads', false, stream_context_create([
    'http' => [
        'header' => "Authorization: Bearer {$apiKey}\r\nAccept: application/json\r\n",
    ],
]));
$leads = json_decode($response, true);

// Create a lead
$ch = curl_init($baseUrl . '/leads');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$apiKey}",
    "Content-Type: application/json",
    "Accept: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'first_name' => 'Sarah',
    'email'      => '[email protected]',
    'source'     => 'api',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript (fetch)

const apiKey = 'lh_your_api_key_here';
const baseUrl = 'https://yourdomain.com/api/v1';

// List leads
const response = await fetch(`${baseUrl}/leads?status=new`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Accept': 'application/json',
  },
});
const { data, meta } = await response.json();

// Create a lead
const createResponse = await fetch(`${baseUrl}/leads`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Sarah',
    email: '[email protected]',
    source: 'website',
  }),
});
const newLead = await createResponse.json();

Übersicht​

Basis-URL​

Authentifizierung​

Rate Limiting​

Paginierung​

Antwortformat​

Erfolgreiche Antwort​

Fehlerantwort​

Health Check​

Leads​

Leads auflisten​

Lead abrufen​

Lead erstellen​

Lead aktualisieren​

Lead löschen​

Tag zu einem Lead hinzufügen​

Tag von einem Lead entfernen​

Pipelines​

Pipeline-Stufen​

Tags​

Benutzer​

Formulare​

Formular absenden​

Automatisierungen​

Integrationen​

Eingehende Lead-Aufnahme​

Codebeispiele​

cURL​

PHP​

JavaScript (fetch)​