API & Schnittstelle
KlickTipp REST API nutzen – Überblick & Einstieg
Möchtest Du KlickTipp nahtlos in Deine Tools und Systeme integrieren? Egal, ob Du Automatisierungen erstellst, Kontakte synchronisierst oder individuelle Workflows umsetzt – ein solides Verständnis der KlickTipp REST API ist entscheidend für Deinen Erfolg.
Dieser umfassende Leitfaden richtet sich an Entwickler und Integratoren, die direkt mit der KlickTipp API arbeiten – oder Plattformen wie FunnelTools, Make oder Zapier nutzen. Du erfährst, wie Du typische Fehler vermeidest und Best Practices rund um Datenformate, Fehlerbehandlung und Authentifizierung anwendest.
Lerne, wie Felder korrekt formatiert werden, wie Du Unix-Zeitstempel für Datum und Uhrzeit einsetzt und welche Authentifizierungsmethode (API Key, Login-Daten oder Developer-Customer-Key-Kombination) für Deinen Anwendungsfall geeignet ist. Mit diesen Tipps gelingt Deine Integration sicher und reibungslos.
Wenn Du Partner von KlickTipp bist und erfahren möchtest, wie Du die einzelnen Endpunkte optimal nutzen kannst, wirf am besten einen Blick in unseren Developer Guide für KlickTipp Integrationen.
Warum das wichtig ist:
- Vermeidbare Fehler verhindern: Falsch formatierte Felder und Testdaten führen oft zu schwer nachvollziehbaren Fehlern. Dieser Leitfaden hilft Dir, es direkt richtig zu machen.
- Stabile Integrationen sicherstellen: Verstehe, wie die verschiedenen Authentifizierungsmethoden funktionieren – und welche für Deine Anwendung die richtige ist.
- Fehlersuche vereinfachen: Entschlüssle die Fehlercodes der KlickTipp API und löse Probleme schnell und gezielt.
- Erprobte Tipps aus der Praxis: Profitiere von internem Know-how und Erfahrungen aus realen Projekten.
Von Zeitstempeln bis zur Authentifizierungslogik – dieser Artikel unterstützt Dich dabei, Integrationen aufzubauen, die einfach funktionieren.
Gut zu wissen:
Möchtest Du unsere API Funktionen lieber über unsere Postman Collection kennenlernen? Dann klicke Hier um unsere Collection in Postman zu öffnen.
Run in Postman
Funktionsübersicht
Hier findest Du eine Übersicht der Endpunkte unserer REST API wenn Du eigene Automatisierungen kodierst und daher unsere Endpunkte direkt ansprechen möchtest:
Authentifizierung via Session-Cookie
HTTP-Anfragen an die REST API sind durch eine cookie-basierte Authentifizierung geschützt. Um ein gültiges Session-Cookie zu erhalten, nutze die Login-Funktion mit Benutzername und Passwort:
curl -X POST https://api.klicktipp.com/account/login.json \
--data-urlencode "username=username" \
--data-urlencode "password=XXXXXXXX"
Kopieren
Im HTTP Response Header findest Du unter Set-Cookie Dein Session-Cookie (bestehend aus → session_name und → sessid). Dieses Cookie musst Du in allen folgenden API-Anfragen im Header mitsenden.
Rückgabeformate
Die KlickTipp REST API unterstützt vier Rückgabeformate: XML, JSON, PHP und HTML. Achte bei Deinen API Anfragen darauf das erwartete Format über die Endung der URL zu bestimmen.
Du kannst Dein gewünschtes Format definieren, indem die entsprechende Endung an die URL angehangen wird – z. B.:
https://api.klicktipp.com/list.json
Kopieren
Wichtig zu wissen
Nur über das JSON-Format werden alle Metainformationen wie z. B. Zeitstempel bei Taggings vollständig mitgeliefert.
Verfügbare Funktionen im Überblick
Authentifizierung
| Funktion | URL | Methode | Parameter | Beispiel Parameter JSON |
|---|---|---|---|---|
| Login | https://api.klicktipp.com/account/login | POST | username, password | {"username": "user", "password": "pass"} |
| Logout | https://api.klicktipp.com/account/logout | POST | – | – |
Kontakt Funktionen
| Funktion | URL | Methode | Parameter | Beispiel Parameter JSON |
|---|---|---|---|---|
| Add or update contact* | https://api.klicktipp.com/subscriber | POST | email, smsnumber, listid, tagid, fields | siehe Beispiel oben |
| Unsubscribe contact | https://api.klicktipp.com/subscriber/unsubscribe | POST | {"email": "max@example.com"} | |
| List contacts | https://api.klicktipp.com/subscriber | GET | status: subscribed unsubscribed pending bounceStatus: nobounce hardbounce softbounce spambounce | https://api.klicktipp.com/subscriber?status=subscribed,unsubscribed,pending&bounceStatus=nobounce,hardbounce,softbounce,spambounce (gibt alle Kontakte zurück) |
| Get contact | https://api.klicktipp.com/subscriber/<subscriberid> | GET | subscriberid wird in URL benötigt | – |
| Search Contact ID | https://api.klicktipp.com/subscriber/search | POST | {"email": "max@example.com"} | |
| Search Tagged Contacts | https://api.klicktipp.com/subscriber/tagged | POST | tagid status: subscribed unsubscribed pending bounceStatus: nobounce hardbounce softbounce spambounce | { "tagid": 123, "status": ["subscribed", "unsubscribed", "pending"], "bounceStatus": ["nobounce", "hardbounce", "softbounce", "spambounce"] } (gibt alle Kontakte mit der tagid 123 zurück) |
| Update contact* | https://api.klicktipp.com/subscriber/<subscriberid> | PUT | fields, newemail, newsmsnumber, subscriberid wird in URL benötigt | {"fields": {…}, "newemail": "…", "newsmsnumber": "…"} |
| Delete contact | https://api.klicktipp.com/subscriber/<subscriberid> | DELETE | subscriberid wird in URL benötigt | – |
*Die Endpunkte "Add or update contact" & "Update contact" unterscheiden sich darin, dass bei der Funktion "Add or update contact" der Kontakt neu eingetragen wird. Bei der "Update contact" Funktion hingegen, wird nur der Kontakt aktualisiert.
Kontakte taggen Funktionen
| Funktion | URL | Methode | Parameter | Beispiel Parameter JSON |
|---|---|---|---|---|
| Tag contact | https://api.klicktipp.com/subscriber/tag | POST | email, tagids | {"email": " max@example.com", "tagids": [123, 456]} |
| Untag contact | https://api.klicktipp.com/subscriber/untag | POST | email, tagid | {"email": "max@example.com", "tagid": 123} |
Stammsatz Felder Funktionen
| Funktion | URL | Methode | Beispiel Parameter |
|---|---|---|---|
| List data fields | https://api.klicktipp.com/field | GET | – |
Opt-In Prozess Funktionen
| Funktion | URL | Methode | Parameter | Beispiel Parameter JSON |
|---|---|---|---|---|
| List opt-in processes | https://api.klicktipp.com/list | GET | – | – |
| Get opt-in process | https://api.klicktipp.com/list/<listid> | GET | opt-in id wird in URL benötigt | – |
| Search Redirect URL | https://api.klicktipp.com/list/redirect | POST | listid, email | {"listid": "123", "email": "max@example.com"} |
Tag Funktionen
| Funktion | URL | Methode | Parameter | Beispiel Parameter JSON |
|---|---|---|---|---|
| List tags | https://api.klicktipp.com/tag | GET | – | – |
| Get tag | https://api.klicktipp.com/tag/<tagid> | GET | tagid wird in URL benötigt | – |
| Create tag | https://api.klicktipp.com/tag | POST | name | {"name": "Neuer Tag"} |
| Update tag | https://api.klicktipp.com/tag/<tagid> | PUT | name, tagid wird in URL benötigt | {"name": "Aktualisierter Tag"} |
| Delete tag | https://api.klicktipp.com/tag/<tagid> | DELETE | tagid wird in URL benötigt | – |
API Key Funktionen
| Funktion | URL | Methode | Parameter | Beispiel Parameter JSON |
|---|---|---|---|---|
| Sign in (API Key) | https://api.klicktipp.com/subscriber/signin | POST | apikey, email, fields, smsnumber | {"apikey": "XYZ", "email": "…", "fields": {…}} |
| Sign out (API Key) | https://api.klicktipp.com/subscriber/signout | POST | apikey, email | {"apikey": "XYZ", "email": "…"} |
| Sign off (API Key) | https://api.klicktipp.com/subscriber/signoff | POST | apikey, email | {"apikey": "XYZ", "email": "…"} |
Beispiel-Payload für die Erstellung von Kontakten
Hier siehst Du ein Beispiel für einen vollständigen Payload, wie er für die Funktion Add or update contact genutzt werden kann. Neben Standardfeldern ist auch ein benutzerdefiniertes Feld (field12345) enthalten:
{
"email": "max.mustermann@example.com",
"listid": "12345",
"tagid": "45678",
"smsnumber": "+491701234567",
"fields": {
"fieldFirstName": "Max",
"fieldLastName": "Mustermann",
"fieldCompanyName": "Beispiel GmbH",
"fieldStreet1": "Musterstraße 1",
"fieldStreet2": "",
"fieldCity": "Berlin",
"fieldState": "Berlin",
"fieldZip": "10115",
"fieldCountry": "DE",
"fieldPrivatePhone": "+491701234567",
"fieldMobilePhone": "+491701234567",
"fieldPhone": "+492201234567",
"fieldFax": "4922012345678",
"fieldWebsite": "https://www.klicktipp.com/",
"fieldBirthday": "755222400",
"fieldLeadValue": "5",
"field12345": "Benutzerdefiniertes Feld"
}
Kopieren
Feldtypen & Formate – das musst Du beachten
Beim Übermitteln von Daten an die KlickTipp API ist es wichtig, dass die Inhalte den richtigen Formaten für den jeweiligen Feldtyp entsprechen. Andernfalls kann es zu Validierungsfehlern oder unvollständigen Eintragungen kommen.
Die Formatierung unterscheidet sich je nach Feldtyp. Besonders wichtig ist das bei eigener API-Nutzung, aber auch bei Formularen von Drittanbietern wie FunnelTools, Make oder Zapier.
Damit die Eintragung erfolgreich verläuft, müssen alle Felder das korrekte Format haben. Ist dies nicht der Fall, wird sie abgelehnt.
| Feldtyp | Erwarteter Inhalt | Beispiel-Wert | Hinweis |
|---|---|---|---|
| Zeile | Text in einer Zeile | Max Mustermann | Keine Zeilenumbrüche |
| Absatz | Text mit Absätzen | Dies ist ein Text.\nMit Absatz. | \n für Absatz |
| Gültige Adresse mit @ | max@example.com | Kein Leerzeichen | |
| Zahl | Ganze Zahl (Integer) | 42 | Kein Punkt, kein Komma |
| Dezimalzahl | Kommazahl | Input 1999 → Output 19.99 | Punkt als Dezimaltrennzeichen im Output |
| URL | Gültige Webadresse | https://klicktipp.com | Muss mit http:// oder https:// beginnen |
| Uhrzeit | Unix-Timestamp zwischen 0–86399 | 52200 (für 14:30 Uhr) | Sekunden seit Mitternacht |
| Datum | Unix-Timestamp (in Sekunden) | 1715126400 (für 08.05.2024) | Kein „TT.MM.JJJJ“ Format über API |
| Datum & Uhrzeit | Unix-Timestamp (in Sekunden) | 1715603400 (für 13.05.2024 15:30:00) | Kein Leerzeichen oder Datumsformat senden |
| HTML | HTML-Formatierter Inhalt | <strong>Hallo Welt</strong> | Nur sinnvoll, wenn das Feld HTML erlaubt |
Format-Hinweise für API-Nutzung
- Immer Unix-Zeitstempel (in Sekunden) für Zeit- und Datumsfelder übergeben
- Keine deutschen Datumsformate (z. B. 31.12.2024) – wird nicht erkannt
- Werte wie Telefonnummern, Links, Preise etc. müssen formatiert zur Felddefinition passen (siehe /field)
Datum und Uhrzeit korrekt übergeben
Die KlickTipp API akzeptiert ausschließlich Unix-Zeitstempel in Sekunden für Zeit- und Datumswerte.
Uhrzeit
| Uhrzeit | Unix-Zeitstempel |
|---|---|
| 00:00 | 0 |
| 14:30 | 52.200 |
| 23:59:59 | 86.399 |
Nur Werte im Bereich 0–86399 sind gültig.
Datum
- Erwartet: Unix-Timestamp, z. B. 1651276800 für 30.04.2022.
- Anzeige in KlickTipp: TT.MM.JJJJ
Datum + Uhrzeit
- Kombination ebenfalls als Timestamp, z. B. 1715603400 = 13.05.2024 15:30:00
- Tipp: Immer UTC verwenden, keine Zeitzonen-Strings.
Fehlercodes verstehen und abfangen
Die API gibt Fehlercodes meist mit HTTP 406 zurück. Das JSON enthält ein "error"-Feld mit einer Zahl.
{ "error": 9 }
Kopieren
Übersicht häufiger Fehler
| Code | Beschreibung |
|---|---|
| 4 | E-Mail-Adresse ist abgemeldet – erneutes Eintragen nicht möglich. |
| 5 | Ungültige E-Mail-Adresse |
| 6 | Bestätigungs-E-Mail konnte nicht gesendet werden. |
| 7 | E-Mail-Adresse nicht gefunden. (Kann auch auftreten, wenn Felder im falschen Format gesendet wurden – z. B. falscher Timestamp bei Datum/Uhrzeit.) |
| 8 | Ungültiger Wert in einem benutzerdefinierten Feld. |
| 9 | SMS-Nummer ist bereits einem anderen Kontakt zugewiesen. SMS-Nummern müssen eindeutig sein. |
| 10 | Aktualisierung des Kontakts fehlgeschlagen. |
| 11 | Ungültige SMS-Nummer |
| 12 | Interner Fehler, bitte später erneut versuchen. |
| 30 | E-Mail-Adresse wurde blockiert und ist für Eintragungen nicht zugelassen. |
| 31 | SmartTags können nur vom System vergeben werden. |
| 32 | Weder E-Mail-Adresse noch SMS-Nummer angegeben – eines von beiden ist erforderlich. |
| 401 | Benutzer wurde nicht gefunden. |
| 402 | Opt-In-Prozess wurde nicht gefunden. |
| 403 | Tag wurde nicht gefunden. |
| 406 | Der Server kann die angeforderten Inhalte im vom Client angegebenen Format nicht bereitstellen. Der Client sendet über die sogenannten "Accept"-Header Informationen darüber, welche Art von Inhalten er akzeptieren kann (z.B. Dateiformate im Rückgabewert - diesen kann man über die Endung der URL steuern). |
| 507 | E-Mail-Adresse ist bereits einem anderen Kontakt zugewiesen. |
Best Practice: Fehler strukturiert abfangen & im UI anzeigen, damit der Nutzer passende Rückmeldung für das Debuggen einsehen kann.
Unterschiede in der Authentifizierung zwischen den API-Funktionen „subscribe“ und „signin“
Die beiden Funktionen dienen dazu, Kontakte in KlickTipp einzutragen – unterscheiden sich aber in Anwendungsbereich und Authentifizierung:
| Merkmal | subscribe | signin |
|---|---|---|
| Authentifizierung | Benutzername & Passwort | API-Key (Listbuilding) |
| Einsatz | Manuell, intern (Admin, Unterkonto) | Automatisiert, z. B. aus Webformularen |
| Rückgabe | Kontakt-Objekt | URL der Bestätigungsseite |
| Geeignet für | Interne Tools, Schnittstellen mit Benutzerkontozugriff | Externe Systeme, iPaaS-Plattformen, Webformulare |
| Sicherheit | Zugang zum gesamten Konto (wenn Hauptkonto genutzt) | Begrenzter Zugriff über API-Key |
| Opt-In | Optional über listid | Gesteuert durch zugeordneten API-Key |
Tipp: Viele Partner von uns automatisieren ihre Webformulare über den Signin Endpunkt. Für eine Authentifizierung hierzu musst Du in KlickTipp einen API Key unter den sogenannten → Listbuildings anlegen. Ansonsten läuft die Authentifizierung über die Zugangsdaten zum Konto/Unterkonto (Benutzername & Passwort) und nicht immer zwangsläufig über den API Key.
FAQ – Häufig gestellte Fragen
Die KlickTipp API blockiert nicht zustellbare Adressen wie test@test.com.
Verwende echte Testadressen mit funktionierenden Postfächern.
Als Unix-Zeitstempel in Sekunden.
Beispiel: 30.04.2022 → 1651276800
Mehr dazu siehe auch FAQ zu „Geburtsdatum“.
Die verwendete ID existiert nicht oder ist falsch.
Hole gültige IDs vorher über API-Endpunkte wie /tag, /list oder /field ab.
Nutze dazu z. B. eine GET-Anfrage via cURL oder PHP Wrapper.
Häufige Ursachen:
Unterkonto hat nicht die Rolle „API“
Benutzername statt E-Mail-Adresse wurde nicht korrekt verwendet
Tipps:
Nutze dedizierte Unterkonten mit Rolle „API“
Vermeide die Verwendung des Hauptkontos für API-Zugriffe
Nutze Stunden * 3600 + Minuten * 60 → z. B. 14:30 = 14*3600 + 30*60 = 52200.
Ein Unix-Zeitstempel. Beispiel: 1651276800 für 30.04.2022.
Einsatz bei:
- Internen Tools und Workflows
- Tests mit dem PHP Wrapper oder CURL
- API-Aufrufen, bei denen kein API-Key oder Entwicklerschlüssel verwendet wird
Wichtig:
- Immer Benutzername verwenden, nicht die E-Mail-Adresse
- Authentifizierung per Login-Endpoint (/account/login)
- Nur mit Unterkonto mit Rolle "API" empfohlen
Einsatz bei:
- Einfachen externen Integrationen (z. B. Newsletterformulare, Leadmagneten)
- Tools wie Make, Zapier, Funnelbuilder etc.
- Funktionen: signin, signout, signoff
Besonderheiten:
- API-Key ist direkt mit einem Listbuilding-Prozess verknüpft
- Wird im KlickTipp Konto unter → Listbuilding → Eintragung per API-Key erstellt
- Authentifizierung erfolgt direkt im Body über apikey
Tipp:
Vermeide Benutzername/Passwort in externen Tools – API-Key ist sicherer und stabiler.
Einsatz bei:
- Produktiven Integrationen, die dauerhaft und robust laufen müssen
- Multi-Tenant Anwendungen, White-Label-Setups oder eigenen SaaS-Integrationen
- Integration in Systeme, in denen viele Endnutzer Zugriff auf KlickTipp erhalten sollen
Ablauf:
- Du als Anbieter generierst den Developer Key
- Dein Kunde generiert (einmalig) seinen Customer Key über eine spezielle URL
- Authentifizierung erfolgt damit dauerhaft, ohne Login oder Sessionhandling
Vorteil:
- Kein Ablauf der Session
- Kein Speichern von Passwörtern
- Sehr gute Trennung von Anbieter- und Kundenzugriff
Das Wichtigste auf einen Blick
Die KlickTipp API bietet viele Möglichkeiten – vorausgesetzt, sie wird korrekt verwendet. Mit den hier aufgeführten Tipps und Best Practices vermeidest Du typische Fehler, sparen Zeit bei der Fehlersuche und sorgen für stabile, sichere Integrationen. Achte auf korrekte Feldformate, nutze geeignete Authentifizierungsmethoden und interpretiere Fehlermeldungen richtig. So steht erfolgreichen Automatisierungen mit KlickTipp nichts im Weg.
