API-Referenz

POST https://app.advision360.de/api/public/leads

Legt einen Lead auf dem Lead-Board der Firma an, zu der der Lead-Schlüssel gehört, oder aktualisiert einen bestehenden Lead (siehe Doppelte Leads).

Authentifizierung: Header X-API-Key oder Feld _key (siehe Authentifizierung).

Content-Type: application/json, application/x-www-form-urlencoded oder multipart/form-data.

Felder

Feld	Typ	Pflicht	Beschreibung
firstName	string	ja	Vorname, maximal 100 Zeichen.
lastName	string	ja	Nachname, maximal 100 Zeichen.
email	string	E-Mail oder Telefon	Gültige E-Mail-Adresse, maximal 255 Zeichen.
phone	string	E-Mail oder Telefon	Telefonnummer, maximal 50 Zeichen.
source	string	nein	Herkunft des Leads, siehe erlaubte Werte. Unbekannte Werte werden ignoriert.
notes	string	nein	Freitext, wird am Lead gespeichert.
additionalFields	object	nein	Eigene Schlüssel-Wert-Paare. Im Formular als additionalFields.<name>. Siehe Eigene Felder.
_meta.url	string	nein	Adresse der Seite, auf der der Lead entstanden ist. In JSON als "_meta": { "url": "…" }. Das JavaScript-SDK setzt den Wert automatisch.
_key	string	ohne Header	Lead-Schlüssel, falls kein Header X-API-Key gesetzt ist.
_redirect	string	nein	Weiterleitungsziel nach Erfolg. Nur für freigegebene Domains, siehe Weiterleitung.
_test	boolean	nein	true, "true" oder "1" markiert den Lead als Test-Lead.

Mindestens eines der Felder email oder phone muss angegeben sein.

Erlaubte Werte für source

website, referral, phone, event, social_media, advertisement, partner, landing_page, registration, other

Antworten

201 Created

Der Lead wurde angelegt oder aktualisiert. Der Body ist ein leeres JSON-Objekt.

{}

302 Found

Der Lead wurde angelegt, und _redirect zeigt auf eine freigegebene Domain. Der Header Location enthält das Weiterleitungsziel.

HTTP/1.1 302 Found
Location: https://www.example.com/danke

400 Bad Request

Die Daten sind ungültig. violations enthält einen Eintrag pro Fehler. Fehlt sowohl E-Mail als auch Telefon, ist field leer. Die Sprache der Meldungen richtet sich nach Accept-Language (de oder en).

{
  "error": "Validation failed",
  "violations": [
    { "field": "firstName", "message": "First name is required" },
    { "field": "email", "message": "Email is not valid" },
    { "field": "", "message": "Email or phone is required" }
  ]
}

401 Unauthorized

Der Lead-Schlüssel fehlt, ist unbekannt oder deaktiviert.

{
  "error": "Invalid or inactive API key"
}

429 Too Many Requests

Das Rate Limit ist erreicht. retryAfter und der Header Retry-After geben die Wartezeit in Sekunden an.

{
  "error": "rate_limit_exceeded",
  "retryAfter": 1800
}

Fehlercodes

Status	Bedeutung	Ursache
400	Bad Request	Pflichtfelder fehlen oder Werte sind ungültig.
401	Unauthorized	Lead-Schlüssel fehlt, ist unbekannt oder deaktiviert.
403	Forbidden	Die Lizenz der Firma enthält das Lead-Modul nicht.
429	Too Many Requests	Rate Limit des Schlüssels erreicht.
500	Server Error	Unerwarteter Fehler. Wiederholen Sie die Anfrage später, bei dauerhaften Fehlern wenden Sie sich an den Support.

Rate Limit

Pro Lead-Schlüssel sind 100 Anfragen pro Stunde erlaubt. Das Kontingent wird jeweils für ein festes Stundenfenster gezählt. Ist es erschöpft, antwortet die API mit 429 und dem Header Retry-After.

Benötigen Sie mehr Anfragen, verteilen Sie den Verkehr auf mehrere Schlüssel, z. B. einen pro Website.