API Keys
Pelatis bietet eine RESTful Public API unter /api/v1/ für individuelle Integrationen, Skripte und Drittanbieter-Tools. Der Zugriff wird über API Keys authentifiziert.
API Key erstellen
- Gehe zu Einstellungen > API Keys
- Klicke auf API Key erstellen
- Gib einen beschreibenden Namen ein (z.B. "Zapier-Integration" oder "Marketing-Sync-Skript")
- Klicke auf Erstellen
- Kopiere den generierten Key sofort — er wird nur einmal angezeigt
Bewahre den Key sicher auf. Wenn du ihn verlierst, musst du einen neuen erstellen.
Wer kann API Keys erstellen
Nur Owner und Admins können API Keys erstellen und verwalten.
Authentifizierung
Füge deinen API Key im X-API-Key-Header bei jeder Anfrage ein:
curl -H "X-API-Key: dein_api_key_hier" \
https://app.pelatiscrm.com/api/v1/leads
Anfragen ohne gültigen API Key erhalten 401 Unauthorized.
Rate Limits
API-Anfragen sind pro Key limitiert:
| Plan | Rate Limit |
|---|---|
| Pro | 100 Anfragen pro Minute |
| Business | 300 Anfragen pro Minute |
Bei Überschreitung des Limits gibt die API 429 Too Many Requests mit einem Retry-After-Header zurück, der angibt, wie viele Sekunden gewartet werden soll.
Der Starter-Plan beinhaltet keinen API-Zugang. Upgrade auf Pro oder Business, um die API zu nutzen.
Verfügbare Endpoints
Die API folgt RESTful-Konventionen. Alle Endpoints geben JSON zurück. Die Basis-URL ist:
https://app.pelatiscrm.com/api/v1/
Leads
| Methode | Endpoint | Beschreibung |
|---|---|---|
| GET | /leads |
Leads auflisten (mit Paginierung, Filtern) |
| GET | /leads/:id |
Einzelnen Lead abrufen |
| POST | /leads |
Lead erstellen |
| PATCH | /leads/:id |
Lead aktualisieren |
| DELETE | /leads/:id |
Lead soft-löschen |
Kontakte
| Methode | Endpoint | Beschreibung |
|---|---|---|
| GET | /leads/:id/contacts |
Kontakte eines Leads auflisten |
| POST | /leads/:id/contacts |
Kontakt erstellen |
| PATCH | /contacts/:id |
Kontakt aktualisieren |
| DELETE | /contacts/:id |
Kontakt löschen |
Chancen
| Methode | Endpoint | Beschreibung |
|---|---|---|
| GET | /leads/:id/opportunities |
Chancen eines Leads auflisten |
| POST | /leads/:id/opportunities |
Chance erstellen |
| PATCH | /opportunities/:id |
Chance aktualisieren |
| DELETE | /opportunities/:id |
Chance löschen |
Aufgaben
| Methode | Endpoint | Beschreibung |
|---|---|---|
| GET | /tasks |
Aufgaben auflisten (mit Filtern) |
| POST | /tasks |
Aufgabe erstellen |
| PATCH | /tasks/:id |
Aufgabe aktualisieren |
| PATCH | /tasks/:id/complete |
Aufgabe als erledigt markieren |
Aktivitäten
| Methode | Endpoint | Beschreibung |
|---|---|---|
| GET | /leads/:id/activities |
Aktivitäten eines Leads auflisten |
| POST | /leads/:id/activities |
Aktivität erstellen (Notiz, Anrufprotokoll) |
Metadaten
| Methode | Endpoint | Beschreibung |
|---|---|---|
| GET | /pipelines |
Pipelines und Stufen auflisten |
| GET | /tags |
Tags auflisten |
| GET | /custom-fields |
Benutzerdefinierte Felddefinitionen auflisten |
| GET | /users |
Organisationsmitglieder auflisten |
Webhooks
| Methode | Endpoint | Beschreibung |
|---|---|---|
| GET | /webhooks |
Konfigurierte Webhooks auflisten |
| POST | /webhooks |
Webhook erstellen |
| DELETE | /webhooks/:id |
Webhook löschen |
Paginierung
Listen-Endpoints unterstützen cursorbasierte Paginierung:
# Erste Seite
GET /api/v1/leads?limit=50
# Nächste Seite (Cursor aus der vorherigen Antwort verwenden)
GET /api/v1/leads?limit=50&cursor=eyJjcmVhdGVkQXQiOi...
Die Antwort enthält ein nextCursor-Feld. Wenn es null ist, gibt es keine weiteren Ergebnisse.
Filtern
Listen-Endpoints unterstützen Query-Parameter zum Filtern:
# Leads in einer bestimmten Pipeline
GET /api/v1/leads?pipelineId=abc-123
# Leads mit einem bestimmten Tag
GET /api/v1/leads?tag=Enterprise
# Leads, die einem Benutzer zugewiesen sind
GET /api/v1/leads?assignedTo=user-456
Fehlerantworten
Die API gibt Standard-HTTP-Statuscodes zurück:
| Code | Bedeutung |
|---|---|
| 200 | Erfolg |
| 201 | Erstellt |
| 400 | Ungültige Anfrage (ungültige Parameter) |
| 401 | Nicht autorisiert (fehlender oder ungültiger API Key) |
| 403 | Verboten (unzureichende Berechtigungen) |
| 404 | Nicht gefunden |
| 429 | Rate Limit überschritten |
| 500 | Interner Serverfehler |
Fehlerantworten enthalten einen JSON-Body mit einem message-Feld:
{
"error": "validation_error",
"message": "Field 'name' is required"
}
Interaktive API-Dokumentation
Pelatis bietet interaktive API-Dokumentation powered by Scalar. Erreichbar unter:
https://app.pelatiscrm.com/api/docs
Die Scalar-Dokumentation ermöglicht es dir, alle Endpoints zu durchsuchen, Request/Response-Schemas einzusehen und API-Aufrufe direkt im Browser zu testen.
API Keys verwalten
Keys einsehen
Gehe zu Einstellungen > API Keys, um alle aktiven Keys zu sehen. Jeder Eintrag zeigt den Key-Namen, das Erstelldatum und das Datum der letzten Nutzung.
Key widerrufen
Klicke auf das Löschen-Symbol neben einem Key, um ihn zu widerrufen. Dies tritt sofort in Kraft — jede Integration, die diesen Key nutzt, funktioniert nicht mehr.
Best Practices
- Separate Keys für jede Integration erstellen. So kannst du einen widerrufen, ohne andere zu beeinträchtigen.
- Keys regelmäßig rotieren. Neuen Key erstellen, Integration aktualisieren, alten Key widerrufen.
- Keys nie in Versionskontrolle committen. Nutze Umgebungsvariablen oder Secrets Management.
- Nutzung überwachen. Prüfe das "Zuletzt verwendet"-Datum, um ungenutzte Keys zu identifizieren.