Developer Guide & Best Practices – KlickTipp API Integrationen

Exzellenter Support auf Deutsch

inkl. Zoom-Live-Trainings Mo. - Fr.

KlickTipp API – Developer Guide & Best Practices

Dieser Developer Guide richtet sich an Dich – Tech-affinen Marketingprofi, der KlickTipp smart in bestehende Systeme integrieren möchte. Du findest hier klare, umsetzbare Informationen zur Authentifizierung, den wichtigsten Endpunkten und zusätzlich noch Best Practices aus Tools wie Make, n8n und Zapier.

Dokumentation für Entwickler

Basis URL

Die Basis URL für die KlickTipp API ist:

https://api.klicktipp.com

Kopieren

Authentifizierung: So integrierst Du KlickTipp sicher

Für die Authentifizierung bei KlickTipp benötigst u eine der folgenden Authentifizierungsverfahren. Du bekommst hierbei jeweils einen Key, der bei jedem Request mitgegeben werden muss.

Developer Key + Customer Key (Empfohlen für produktive Integrationen)

Sicher & stabil: Keine Session-Limits
Developer Key bleibt bei dir als Anbieter
Customer Key wird vom Endnutzer generiert und gespeichert
Login-Endpunkt: /account/login
Vorteil: Gültig auch nach Kontowiederherstellung

Zur Anleitung: Developer + Customer Key Integration

Session-basiert → läuft bei Logout/Timeout ab
Nicht produktiv einsetzen!
Gut für manuelle Workflows oder erste Tests

Doku: KlickTipp REST API

Action	Description	URL	Method	Input parameter in body
Login to API	Logs into the API and retrieves session details for further interactions	account/login	POST	username, password
Logout from API	Logs out of the API and ends the session	account/logout	POST

API-Token (Nur für Listbuilding)

Ideal für einfache Newsletter-Anmeldungen
Zugriff auf 3 schlanke Endpunkte: signin, signout, signoff
Kein Zugriff auf alle API-Funktionen

Doku: KlickTipp REST API mit API-Token

Action	Description	URL	Method	Input parameter in body
Add Contact via API Key	Creates or updates a contact and associates the tag linked to the API key	/subscriber/signin	POST	apikey, email, fields, smsnumber
Remove Contact via API Key	Removes the tag of a contact associated with the API key	/subscriber/signout	POST	apikey, email
Unsubscribe Contact via API Key	Unsubscribes a contact via the API key and prevents further communication	/subscriber/signoff	POST	apikey, email

Eintragung von Kontakten

Die Funktion → Add or Update Contact ist eine der Kernfunktionen von KlickTipp. Diese geht davon aus, dass ein neuer Kontakt über ein Formular eingetragen wird. Sollte der Kontakt bereits vorhanden sein, wird diese aktualisiert.

In folgendem wird erläutert, wie diese zu implementieren ist.

Relevante Endpunkte

Die Endpunkte → /list, /tag und /field sind relevant, um Daten für Add or Update Contact zu erhalten.

Action	Description	URL	Method	Input parameter in body
Add or Update Contact	Adds a new contact. If a contact with the same email already exists, it will be updated.	/subscriber	POST	email, smsnumber, listid, tagid, fields
List Opt-in Processes	Lists the IDs and names of all opt-in processes	/list	GET
List Tags	Lists the IDs and names of all tags	/tag	GET
List Data Fields	Lists the IDs and names of all data fields	/field	GET

Add or Update Contact

Request body

email string (empfohlen)
- Für die Eingabe sind E-Mail-Adressen mit @-Zeichen erforderlich.
- email oder smsnumber muss vorhanden sein
- email und smsnumber dürfen nur einem Kontakt zugewiesen sein
smsnumber string (empfohlen)→ email oder smsnumber muss vorhanden sein
- Für die Eingabe sind Telefonnummer in dem Format 004912345678 oder +4912345678 erlaubt.
- email und smsnumber dürfen nur einem Kontakt zugewiesen sein
listid string (empfohlen)
- Für die Eingabe muss eine gültige Opt-In Prozess ID verwendet werden.
- Verknüpft mit dem Opt-In Prozess. Wenn keine Listen-ID angegeben wird, wird ein Vordefinierter Double-Opt-In-Prozess verwendet, der eine E-Mail an den Kontakt auslöst
- Nutze /list-Endpunkt zur Abfrage verfügbarer Opt-In Prozesse
tagid string (optional)
- Für die Eingabe muss eine gültige Tag ID verwendet werden.
- Verwende Tags für Segmentierung & Trigger
- Nutze /tag-Endpunkt zur Abfrage verfügbarer Tags
fields (optional)
- Für die Eingabe gelten die jeweiligen Formate für den Datentyp, welche in den kommenden Abschnitten aufgelistet werden.
- Nutze global fields (z. B. fieldFirstName) oder custom fields (z. B. field213729)
- Lade Felder über /field zur dynamischen Anzeige

Beispiel JSON Body

{
  "email": "rene.ludwigs@klick-tipp.team",
  "smsnumber": "00491631737743",
  "listid": "353443",
  "tagid": "12042204",
  "fields": {
    "fieldFirstName": "René",
    "fieldLastName": "Ludwigs",
    "fieldCompanyName": "KlickTipp Limited", 
    "fieldStreet1": "Bag End, 1",
    "fieldStreet2": "",
    "fieldCity": "Shire",
    "fieldState": "Shire",
    "fieldZip": "12345",
    "fieldCountry": "Hobbiton",
    "fieldPrivatePhone": "00491631737741",
    "fieldMobilePhone": "00491631737742",
    "fieldPhone": "00491631737744",
    "fieldFax": "0049163173775",
    "fieldWebsite": "https://awesome-website.com",
    "fieldBirthday": "495986091",
    "fieldLeadValue": "1234"
    "field213729": "lorem ipsum",
    "field213736": "lorem ipsum",
  }

Kopieren

Beispiel JSON Response

{
    "id": "162721328",
    "listid": "364353",
    "optin": "2025-04-22T08:26:37.000Z",
    "optin_ip": "0.0.0.0 - By API Request",
    "email": "rene.ludwigs@klick-tipp.team",
    "status": "Opt-In Pending",
    "bounce": "Not Bounced",
    "date": "",
    "ip": "0.0.0.0 - By API Request",
    "unsubscription": "",
    "unsubscription_ip": "0.0.0.0",
    "referrer": "",
    "sms_phone": "00491631737743",
    "sms_status": "Subscribed",
    "sms_bounce": "Not Bounced",
    "sms_date": "2025-04-22T08:25:55.000Z",
    "sms_unsubscription": "",
    "sms_referrer": "",
    "fieldFirstName": "René",
    "fieldLastName": "Ludwigs",
    "fieldCompanyName": "KlickTipp Limited", 
    "fieldStreet1": "Bag End, 1",
    "fieldStreet2": "",
    "fieldCity": "Shire",
    "fieldState": "Shire",
    "fieldZip": "12345",
    "fieldCountry": "Hobbiton",
    "fieldPrivatePhone": "00491631737741",
    "fieldMobilePhone": "00491631737742",
    "fieldPhone": "00491631737744",
    "fieldFax": "0049163173775",
    "fieldWebsite": "https://awesome-website.com",
    "fieldBirthday": "495986091",
    "fieldLeadValue": "1234"
    "field213729": "lorem ipsum",
    "field213736": "lorem ipsum",
    "tags": [
        "12688017"
     ],
    "manual_tags": {
         "12688017": "1745303197"
     }
 }

Kopieren

Weitere Datenfelder und Formate

Feldtyp	Inhalt
Zeile	Text in einer Zeile
Absatz	Text mit Absätzen
E-Mail	Nur E-Mail-Adressen, @-Zeichen erforderlich
Zahl	Ganze Zahlen ohne Komma, Vorzeichen oder sonstigen Inhalt
Dezimalzahl	Zahlen mit Nachkommastellen
URL	Webadresse muss mit http:// bzw. https:// beginnen
Uhrzeit	Anzeige im Format HH:MM Über die KlickTipp API nur im Format Unix-Timestamp möglich. Für die Uhrzeit erwartet die API einen Unix-Zeitstempel in Sekunden seit Mitternacht (00:00 Uhr) des 01.01.1970. Beispiel: 0 = 00:00 Uhr 52.200 = 14:30 Uhr 86.399 = 23:59:59 Uhr Die Uhrzeit muss also vor dem Senden in Sekunden umgerechnet werden und in dem Wertebereich von 0 bis 86.399 Sekunden liegen (entspricht 00:00 bis 23:59:59 Uhr).
Datum	Anzeige im Format TT.MM.JJJJ Über die KlickTipp API nur im Format Unix-Timestamp möglich.
Datum & Uhrzeit	Anzeige im Format TT.MM.JJJJ HH:MM:SS Über die KlickTipp API nur im Format Unix-Timestamp möglich.
HTML	Beliebiger HTML-Code

Fehlerbehandlung

Hier die wichtigsten Fehlercodes für Add or Update Contact – ideal für Logging & User-Feedback:

HTTP Status code	Error
406	4	The email address is unsubscribed. You cannot re-subscribe an email address if the contact has unsubscribed.
406	5	Invalid email address.
406	6	There was an error sending the confirmation email.
406	7	Email address not found.
406	8	Invalid value in custom field. The provided value is not valid for the field type.
406	9	The SMS number is already assigned to another contact. If you subscribe an email address and add a phone number, it must be unique.
406	10	Update of contact failed.
406	11	Invalid phone number.
406	12	Internal error.
406	30	The email address is blocked and cannot be used for subscription.
406	31	SmartTags are only assigned by the system.
406	32	You must specify either an email address or a SMS number.
406	401	Contact not found.
406	402	Opt-in process not found.
406	403	Tag not found.
406	507	You tried to add an email address to a contact that is already assigned to another contact.
406	default	Something went wrong. Please try again later. Error: ${error}.

Tipp: Fange Fehler strukturiert ab, zeige klare User-Meldungen in deinem Frontend.

List Opt-in Processes

Der Endpunkt /list ist relevant, um die ID für den Opt-In Prozess für Add or Update Contact zu erhalten. Zudem kann er genutzt werden, um eine dynamische Auswahlliste mithilfe des label und dem value zu erzeugen.

Beispiel JSON Response

{
        "value": "366979",
        "label": "Single Opt-In"
    },
    {
        "value": "364353",
        "label": "Newsletter Opt-In"
    },
    {
        "value": "358895",
        "label": "Predefined double opt-in process"
    }

Kopieren

List Tags

Der Endpunkt /tag ist relevant, um die ID für den Tag für Add or Update Contact zu erhalten. Zudem kann er genutzt werden, um eine dynamische Auswahlliste mithilfe des label und dem value zu erzeugen.

{
        "value": "12693542",
        "label": "Newsletter"
    },
    {
        "value": "12709995",
        "label": "Follow-Up E-Mail"
    },
    {
        "value": "12932287",
        "label": "Neuer Tag"
    }

Kopieren

List Data Fields

Der Endpunkt /field ist relevant, um die Felder für Add or Update Contact zu erhalten. Zudem kann er genutzt werden, um eine dynamische Liste der Felder mithilfe des label und dem value zu erzeugen.

Beispiel JSON Response

{
        "value": "fieldBirthday",
        "label": "Birthday"
    },
    {
        "value": "fieldCity",
        "label": "City"
    },
    {
        "value": "fieldCompanyName",
        "label": "Company"
    },
    {
        "value": "fieldCountry",
        "label": "Country"
    },
    {
        "value": "fieldFax",
        "label": "Fax"
    },
    {
        "value": "fieldFirstName",
        "label": "First name"
    },
    {
        "value": "fieldLastName",
        "label": "Last name"
    },
    {
        "value": "fieldLeadValue",
        "label": "Lead value"
    },
    {
        "value": "fieldPhone",
        "label": "Phone"
    },
    {
        "value": "fieldMobilePhone",
        "label": "Phone (mobile)"
    },
    {
        "value": "fieldPrivatePhone",
        "label": "Phone (private)"
    },
    {
        "value": "fieldState",
        "label": "State"
    },
    {
        "value": "fieldStreet1",
        "label": "Street 1"
    },
    {
        "value": "fieldStreet2",
        "label": "Street 2"
    },
    {
        "value": "fieldWebsite",
        "label": "Website"
    },
    {
        "value": "fieldZip",
        "label": "Zip"
    },
    {
        "value": "field213729",
        "label": "lorem ipsum"
    },
    {
        "value": "field213736",
        "label": "lorem ipsum"
    }

Kopieren

Tag Erstellung für Automationen

Damit Deine Anwender nicht manuell einen Tag in KlickTipp erstellen müssen, kannst Du dies für Deine Integration auch über die API.

Statisch: integration_partnername
Dynamisch: webinar_juni2025

Empfehlung: Dropdown-Befüllung & Create-Tag Button im UI

Action	Beschreibung	URL	Methode	Body-Parameter
Create Tag	Creates a new manual tag	/tag	POST	name

Create Tag

Request body

name string (erforderlich)
- name ist der Name des neuen Tags

Beispiel JSON Body

{
   "name": "New Tag"
}

Kopieren

Beispiel JSON Response

{
   "id": 12985883,
}

Kopieren

Segmentierung von Kontakt für E-Mail Kampagnen

Um Kontakte mit einer E-Mail Kampagne anzusprechen, welche bereits einen Opt-In Prozess durchlaufen haben, können die Kontakte ohne einen erneuten Opt-In anzugeben mit mehreren Tags verknüpft werden. Die Zuweisung der Tags ist in KlickTipp der Auslöser, um E-Mail Kampagnen zu starten. Diese Tags kannst Du in deiner Integration zum Beispiel über eine neues Auswahlfeld zur Verfügung stellen, sodass die Anwender über die Integration ihr E-Mail Kampagnen steuern können.

Aktion	Beschreibung	URL	Methode	Body-Parameter
Tag Contact	Adds one or more tags to a contact	/subscriber/tag	POST	email, tagid

Tag Contact

Request body

email string (empfohlen)
- Für die Eingabe sind E-Mail-Adressen mit @-Zeichen erforderlich.
- email oder smsnumber muss vorhanden sein
- email und smsnumber dürfen nur einem Kontakt zugewiesen sein
tagid array (optional)
- Für die Eingabe muss eine gültige Tag ID verwendet werden.
- Verwende Tags für Segmentierung & Trigger
- Nutze /tag-Endpunkt zur Abfrage verfügbarer Tags

Beispiel JSON Body

{
  "email": "rene.ludwigs@klick-tipp.team",
  "tagids": [
    12042204,
    12042205,
    12042206,
    12042207,
    12042208
  ]
}

Kopieren

{
  "success": true
}

Kopieren

Wesentliche API-Funktionen

Hier findest Du die essenziellen Calls, die Du für robuste Automationen wie in Make, n8n, Zapier brauchst. Die Endpunkte /list, /tag und /field sind relevant, um Daten für Add or Update Contact zu erhalten.

Action	Beschreibung	URL	Methode	Body-Parameter
Add or Update Contact	Adds a new contact. If a contact with the same email already exists, it will be updated.	/subscriber	POST	email, smsnumber, listid, tagid, fields
List Opt-in Processes	Lists the IDs and names of all opt-in processes	/list	GET
List Tags	Lists the IDs and names of all tags	/tag	GET
List Data Fields	Lists the IDs and names of all data fields	/field	GET
Unsubscribe Contact	Unsubscribes a contact, preventing further communication	/subscriber/unsubscribe	POST	email
Get Contact ID	Returns the contact ID for an email address	/subscriber/search	POST	email
Tag Contact	Adds one or more tags to a contact	/subscriber/tag	POST	email, tagid
Untag Contact	Removes a tag from a contact	/subscriber/untag	POST	email, tagid

Best Practices

Gute Integrationen sind nicht nur funktional, sondern auch nutzerfreundlich. Beachte daher folgende Best Practices für die User Experience innerhalb deines Tools:

Nutze Developer + Customer Key: Keys laufen nicht ab – selbst nach Kontowiederherstellung bleiben sie aktiv. Der Developer Key bleibt bei dir und der Customer Key wird einmalig vom Endnutzer erzeugt – kein erneutes Login oder Token Refresh notwendig.
Dynamische Drop-downs mit Fallback: Lade Daten (z. B. Tags, Felder, Listen) dynamisch aus KlickTipp via /tag, /field oder /list. Sollte der Abruf fehlschlagen, zeige eine manuelle Eingabeoption oder einen Hinweis zur Verbindung.
Fehlermeldungen aufschlüsseln: Zeige bei 406-Fehlern sprechende Fehlermeldungen direkt im IPaaS-Interface, z. B. „Diese E-Mail-Adresse wurde abgemeldet – kein erneutes Eintragen möglich“ (Error 4).
Optional: "Create Tag"-Funktion: Ermögliche die Erstellung von Tags direkt aus dem Interface heraus (wenn von der API unterstützt) – ideal für schnell einsatzbereite Segmentierungen.

Weitere Dokumente & Referenzen

PHP Wrapper

Neben der einfachen API Dokumentation existiert auch eine beispielhafte Schnittstellen-Klassen für PHP.

Der PHP Wrapper: Nutzung der KlickTipp API mit PHP

NodeJS / Node-RED

Es existiert auch eine Open Source Referenz zu unserem Node-RED Konnektor, welche als Grundlage für eine NodeJS Implementieurng genutzt werden kann.

GitHub: Node-RED KlickTipp Connector

OpenAPI

Wir arbeiten zudem gerade an einer OpenAPI Spezifikation.

API Dokumentation

Mehr zu unserer API und auch einen Link zu mit allen aktuellen Requests und Responsen findest Du hier.

KlickTipp REST API nutzen – Überblick & Einstieg

Hat Dir dieser Beitrag weitergeholfen?

Zurück zur Übersicht: API & Schnittstelle

KlickTipp API – Developer Guide & Best Practices

Dokumentation für Entwickler

Basis URL

Authentifizierung: So integrierst Du KlickTipp sicher

Developer Key + Customer Key (Empfohlen für produktive Integrationen)

Cookie-basierte Authentifizierung (nur für Tests)

API-Token (Nur für Listbuilding)

Eintragung von Kontakten

Relevante Endpunkte

Add or Update Contact

Request body

Beispiel JSON Body

Beispiel JSON Response

Weitere Datenfelder und Formate

Fehlerbehandlung

List Opt-in Processes

Beispiel JSON Response

List Tags

List Data Fields

Beispiel JSON Response

Tag Erstellung für Automationen

Create Tag

Request body

Beispiel JSON Body

Beispiel JSON Response

Segmentierung von Kontakt für E-Mail Kampagnen

Tag Contact

Request body

Beispiel JSON Body

Wesentliche API-Funktionen

Best Practices

Weitere Dokumente & Referenzen

PHP Wrapper

NodeJS / Node-RED

OpenAPI

API Dokumentation

Hat Dir dieser Beitrag weitergeholfen?

Verwandte Beiträge:

KlickTipp REST API nutzen – Überblick & Einstieg

Unterschiede der API-Funktionen „subscribe“ und „signin“

Der PHP Wrapper: Nutzung der KlickTipp API mit PHP

Webhook für Löschanfragen – Datensätze sicher löschen