vulpex | Die beste Lead-Datenbank für DACH

Einführung

Grundlagen zur vulpex REST API.

Die vulpex API bietet programmatischen Zugriff auf die umfangreichste Lead-Datenbank im DACH-Raum. Alle Endpunkte folgen REST-Konventionen, akzeptieren JSON-Bodys und liefern JSON-Antworten zurück.

Base URL

https://vulpex.synetra.de/api

Alle Anfragen müssen über HTTPS erfolgen. HTTP-Anfragen werden abgelehnt.

Authentifizierung

API-Key basierte Authentifizierung für alle Endpunkte.

Jede Anfrage muss einen gültigen API-Key im Authorization-Header enthalten. API-Keys können unter **Einstellungen > API** erstellt und verwaltet werden.

API-Keys beginnen immer mit dem Präfix vx_ und sind an eine Organisation gebunden. Jeder Key kann mit spezifischen Berechtigungen erstellt werden.

GET/api/leads

Anfrage mit API-Key

Jede Anfrage benötigt den Authorization-Header mit deinem API-Key.

Beispiel

bash

curl -X GET "https://vulpex.synetra.de/api/leads" \
  -H "Authorization: Bearer vx_dein_api_key" \
  -H "Content-Type: application/json"

Antwort

json

{
  "leads": [...],
  "total": 1284
}

Leads

Leads suchen, abrufen, freischalten und bewerten.

GET/api/leads

Leads suchen

Durchsuche und filtere die gesamte Lead-Datenbank mit umfangreichen Filteroptionen.

Query-Parameter

Parameter	Typ	Pflicht	Beschreibung
`q`	string	Nein	Volltextsuche (Firmenname, Branche, Stadt)
`plz`	string	Nein	Postleitzahl oder PLZ-Bereich (z.B. 80*)
`stadt`	string	Nein	Stadt oder Ort
`branche`	string	Nein	Branche / Industriezweig
`hasEmail`	boolean	Nein	Nur Leads mit E-Mail-Adresse
`hasPhone`	boolean	Nein	Nur Leads mit Telefonnummer
`hasWebsite`	boolean	Nein	Nur Leads mit Website
`limit`	number	Nein	Ergebnisse pro Seite (max. 100, Standard: 25)
`offset`	number	Nein	Offset für Paginierung

Beispiel

bash

curl -X GET "https://vulpex.synetra.de/api/leads?branche=Software&plz=10*&hasEmail=true&limit=10" \
  -H "Authorization: Bearer vx_dein_api_key"

Antwort

json

{
  "leads": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "firma": "TechVision AG",
      "branche": "Software",
      "plz": "10115",
      "stadt": "Berlin",
      "score": 94,
      "bewertung": 4.7,
      "hasEmail": true,
      "hasPhone": true,
      "hasWebsite": true,
      "isUnlocked": false,
      "createdAt": "2025-11-15T10:30:00Z"
    }
  ],
  "total": 847
}

GET/api/leads/:id

Lead-Details abrufen

Ruft detaillierte Informationen zu einem einzelnen Lead ab. Freigeschaltete Felder werden nur angezeigt, wenn der Lead zuvor unlocked wurde.

Beispiel

bash

curl -X GET "https://vulpex.synetra.de/api/leads/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer vx_dein_api_key"

Antwort

json

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "firma": "TechVision AG",
  "branche": "Software",
  "plz": "10115",
  "stadt": "Berlin",
  "strasse": "Friedrichstraße 123",
  "score": 94,
  "bewertung": 4.7,
  "geschaeftsfuehrer": "Dr. Anna Weber",
  "email": "[email protected]",
  "telefon": "+49 30 1234567",
  "website": "https://techvision.de",
  "umsatz": 48200000,
  "mitarbeiter": 120,
  "isUnlocked": true,
  "enrichment": {
    "linkedin": "linkedin.com/company/techvision",
    "techStack": ["React", "Node.js", "AWS"],
    "handelsregister": "HRB 123456 B"
  }
}

POST/api/leads/:id/unlock

Lead freischalten

Schaltet die geschützten Kontaktdaten eines Leads frei. Kosten: 1 Credit. Idempotent: bereits freigeschaltete Leads werden nicht erneut belastet.

Beispiel

bash

curl -X POST "https://vulpex.synetra.de/api/leads/f47ac10b-58cc-4372-a567-0e02b2c3d479/unlock" \
  -H "Authorization: Bearer vx_dein_api_key"

Antwort

json

{
  "success": true,
  "creditsUsed": 1,
  "remainingCredits": 249
}

POST/api/leads/bulk-unlock

Mehrere Leads freischalten

Schaltet bis zu 100 Leads gleichzeitig frei. Bereits freigeschaltete Leads in der Liste werden übersprungen.

Request Body

json

{
  "leadIds": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ]
}

Beispiel

bash

curl -X POST "https://vulpex.synetra.de/api/leads/bulk-unlock" \
  -H "Authorization: Bearer vx_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{"leadIds": ["f47ac10b-...", "a1b2c3d4-..."]}'

Antwort

json

{
  "unlocked": 2,
  "skipped": 0,
  "creditsUsed": 2,
  "remainingCredits": 247
}

GET/api/leads/score

Lead-Score abrufen

Gibt den berechneten Score und die Aufschlüsselung der einzelnen Scoring-Faktoren zurück.

Query-Parameter

Parameter	Typ	Pflicht	Beschreibung
`leadId`	string	Ja	ID des Leads

Beispiel

bash

curl -X GET "https://vulpex.synetra.de/api/leads/score?leadId=f47ac10b-..." \
  -H "Authorization: Bearer vx_dein_api_key"

Antwort

json

{
  "score": 94,
  "breakdown": {
    "dataCompleteness": 28,
    "contactQuality": 22,
    "financialData": 18,
    "onlinePresence": 14,
    "enrichmentDepth": 12
  }
}

GET/api/leads/duplicates

Duplikate finden

Findet potenzielle Duplikate anhand von Website-Domain, Telefonnummer oder Ähnlichkeit des Firmennamens.

Beispiel

bash

curl -X GET "https://vulpex.synetra.de/api/leads/duplicates" \
  -H "Authorization: Bearer vx_dein_api_key"

Antwort

json

{
  "duplicates": [
    {
      "leadA": "f47ac10b-...",
      "leadB": "a1b2c3d4-...",
      "matchType": "domain",
      "confidence": 0.95
    }
  ]
}

Lead-Listen

Leads in Listen organisieren und verwalten.

GET/api/lead-lists

Listen anzeigen

Gibt alle Lead-Listen der Organisation mit Anzahl der enthaltenen Leads zurück.

Beispiel

bash

curl -X GET "https://vulpex.synetra.de/api/lead-lists" \
  -H "Authorization: Bearer vx_dein_api_key"

Antwort

json

{
  "lists": [
    {
      "id": "abc-123",
      "name": "Softwarefirmen Berlin",
      "leadCount": 42,
      "createdAt": "2025-12-01T09:00:00Z"
    }
  ]
}

POST/api/lead-lists

Liste erstellen

Erstellt eine neue Lead-Liste.

Request Body

json

{
  "name": "Top Leads Q1"
}

Beispiel

bash

curl -X POST "https://vulpex.synetra.de/api/lead-lists" \
  -H "Authorization: Bearer vx_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Top Leads Q1"}'

Antwort

json

{
  "id": "def-456",
  "name": "Top Leads Q1",
  "leadCount": 0,
  "createdAt": "2026-01-15T14:22:00Z"
}

POST/api/lead-lists/:id/items

Leads hinzufügen

Fügt einen oder mehrere Leads zu einer bestehenden Liste hinzu.

Request Body

json

{
  "leadIds": ["f47ac10b-...", "a1b2c3d4-..."]
}

Beispiel

bash

curl -X POST "https://vulpex.synetra.de/api/lead-lists/def-456/items" \
  -H "Authorization: Bearer vx_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{"leadIds": ["f47ac10b-...", "a1b2c3d4-..."]}'

Antwort

json

{
  "added": 2,
  "listId": "def-456"
}

CRM-Integration

Leads mit HubSpot, Close und weiteren CRMs synchronisieren.

GET/api/crm/connections

Verbindungen anzeigen

Listet alle konfigurierten CRM-Verbindungen auf. Erfordert mindestens den Pro-Plan.

Beispiel

bash

curl -X GET "https://vulpex.synetra.de/api/crm/connections" \
  -H "Authorization: Bearer vx_dein_api_key"

Antwort

json

{
  "connections": [
    {
      "id": "conn-1",
      "provider": "hubspot",
      "status": "active",
      "lastSync": "2026-01-14T18:00:00Z"
    }
  ]
}

POST/api/crm/sync

Leads synchronisieren

Synchronisiert ausgewählte Leads mit dem verbundenen CRM-System.

Request Body

json

{
  "connectionId": "conn-1",
  "leadIds": ["f47ac10b-...", "a1b2c3d4-..."]
}

Beispiel

bash

curl -X POST "https://vulpex.synetra.de/api/crm/sync" \
  -H "Authorization: Bearer vx_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{"connectionId": "conn-1", "leadIds": ["f47ac10b-..."]}'

Antwort

json

{
  "synced": 2,
  "provider": "hubspot",
  "syncId": "sync-abc-123"
}

Credits & Billing

Guthaben abfragen und Transaktionen einsehen.

GET/api/billing/credits

Guthaben abfragen

Gibt das aktuelle Credit-Guthaben, letzte Transaktionen und verfügbare Credit-Pakete zurück.

Beispiel

bash

curl -X GET "https://vulpex.synetra.de/api/billing/credits" \
  -H "Authorization: Bearer vx_dein_api_key"

Antwort

json

{
  "balance": 247,
  "transactions": [
    {
      "id": "txn-1",
      "type": "debit",
      "amount": -2,
      "description": "Bulk-Unlock (2 Leads)",
      "createdAt": "2026-01-15T14:30:00Z"
    },
    {
      "id": "txn-2",
      "type": "credit",
      "amount": 500,
      "description": "Monatliche Aufladung (Pro)",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ],
  "packages": [
    { "id": "pkg-100", "credits": 100, "priceEur": 29 },
    { "id": "pkg-500", "credits": 500, "priceEur": 119 }
  ]
}

Fehlerbehandlung

HTTP-Statuscodes und Fehlerformate.

Alle Fehler folgen einem einheitlichen JSON-Format:

json

{
  "error": "Beschreibung des Fehlers",
  "code": "ERROR_CODE"
}

Status	Bedeutung
`400`	Ungültige Anfrage - fehlende oder falsche Parameter
`401`	Nicht authentifiziert - API-Key fehlt oder ungültig
`403`	Keine Berechtigung - unzureichende Rechte oder Plan
`404`	Ressource nicht gefunden
`409`	Konflikt - z.B. Duplikat bei Erstellung
`422`	Validierungsfehler - Body entspricht nicht dem Schema
`429`	Rate Limit erreicht - zu viele Anfragen
`500`	Serverfehler - bitte Support kontaktieren

Rate Limits

Anfragelimits und Throttling.

Die API begrenzt Anfragen pro Zeitfenster, abhängig vom Plan:

Plan	Limit
Starter	60 Anfragen / Minute
Pro	120 Anfragen / Minute
Business	300 Anfragen / Minute
Enterprise	1.000 Anfragen / Minute

Bei Überschreitung wird 429 Too Many Requests zurückgegeben. Die Antwort enthält den Header Retry-After mit der Wartezeit in Sekunden.

text

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{"error": "Rate limit exceeded", "code": "RATE_LIMITED"}

vulpex API

Einführung

Base URL

Authentifizierung

Anfrage mit API-Key

Beispiel

Antwort

Leads

Leads suchen

Query-Parameter

Beispiel

Antwort

Lead-Details abrufen

Beispiel

Antwort

Lead freischalten

Beispiel

Antwort

Mehrere Leads freischalten

Request Body

Beispiel

Antwort

Lead-Score abrufen

Query-Parameter

Beispiel

Antwort

Duplikate finden

Beispiel

Antwort

Lead-Listen

Listen anzeigen

Beispiel

Antwort

Liste erstellen

Request Body

Beispiel

Antwort

Leads hinzufügen

Request Body

Beispiel

Antwort

Tags

Tags abrufen

Beispiel

Antwort

Tag erstellen

Request Body

Beispiel

Antwort

Tag löschen

Beispiel

Antwort

CRM-Integration

Verbindungen anzeigen

Beispiel

Antwort

Leads synchronisieren

Request Body

Beispiel

Antwort

Credits & Billing

Guthaben abfragen

Beispiel

Antwort

Fehlerbehandlung

Rate Limits

Befehlspalette