API & Interface
KlickTipp Developer Guide: Integrations & Automation
This documentation is aimed at you - tech-savvy marketing professionals who want to integrate KlickTipp smart into existing systems. You will find clear, actionable information on authentication, the most important endpoints and also best practices from tools such as Make, n8n and Zapier.
Documentation for Developers
Base URL
The base URL for the KlickTipp API is:
https://api.klicktipp.com
Kopieren
Authentication: How to integrate KlickTipp securely
To authenticate with KlickTipp, you need one of the following authentication methods. You will receive a key that must be provided with every request.
Developer Key + Customer Key (recommended for productive integrations)
- Secure & stable: No session limits
- Developer key remains with you as the provider
- Customer key is generated and stored by the end user
- Login endpoint: /account/login
- Advantage: Valid even after account recovery
To the instructions: Developer + Customer Key Integration
Cookie-based authentication (for tests only)
- Session-based → expires on logout/timeout
- Do not use productively!
- Good for manual workflows or initial tests
Documentation: 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 (only for list building)
- Ideal for simple newsletter subscriptions
- Access to 3 lean endpoints: signin, signout, signoff
- No access to all API functions
Documentation: KlickTipp REST API with 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 |
Entry of Contacts
The → Add or Update Contact function is one of the core functions of KlickTipp. It assumes that a new contact is entered via a form. If the contact already exists, it will be updated. The following explains how to implement this.
Relevant Endpoints
The endpoints → /list, /tag and /field are relevant to obtain data for Add or Update Contact.
| 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 (recommended)
- Email addresses with @ characters are required for input.
- email or smsnumber must be present
- email and smsnumber may only be assigned to one contact
- smsnumber string (recommended) → email or smsnumber must be present
- Phone numbers in the format 004912345678 or +4912345678 are permitted for input.
- email and smsnumber may only be assigned to one contact
- listid string (recommended)
- A valid opt-in process ID must be used for the input.
- Linked to the opt-in process. If no list ID is specified, a predefined double opt-in process is used, which triggers an email to the contact
- Use /list endpoint to query available opt-in processes
- tagid string (optional)
- A valid tag ID must be used for the input.
- Use tags for segmentation & triggers
- Use /tag endpoint to query available tags
- fields (optional)
- The respective formats for the data type, which are listed in the following sections, apply to the input.
- Use global fields (e.g. fieldFirstName) or custom fields (e.g. field213729)
- Load fields via /field for dynamic display
Example 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
Example 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
Other Data Fields and Formats
| Field type | Contents |
|---|---|
| Line | Text in one line |
| Paragraph | Text with paragraphs |
| Only e-mail addresses, @ sign required | |
| Number | Whole numbers without decimal point, sign or other content |
| Decimal number | Numbers with decimal places |
| URL | Web address must begin with http:// or https:// |
| Time | Display in HH:MM format Only possible in Unix timestamp format via the KlickTipp API. For the time, the API expects a Unix timestamp in seconds since midnight (00:00) on 01.01.1970. Example: 0 = 00:00 52,200 = 14:30 86,399 = 23:59:59 The time must therefore be converted into seconds before sending and be in the value range from 0 to 86,399 seconds (corresponds to 00:00 to 23:59:59). |
| Date | Display in the format DD.MM.YYYY Only possible in Unix timestamp format via the KlickTipp API. |
| Date & time | Display in the format DD.MM.YYYY HH:MM:SS Only possible in Unix timestamp format via the KlickTipp API. |
| HTML | Any HTML code |
Error Handling
Here are the most important error codes for Add or Update Contact - ideal for 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 an 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}. |
Tip: Catch errors in a structured way, show clear user messages in your frontend.
List Opt-in Processes
The /list endpoint is relevant in order to obtain the ID for the opt-in process for Add or Update Contact. It can also be used to create a dynamic selection list using the label and the value.
Example 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
The /tag endpoint is relevant in order to obtain the ID for the tag for Add or Update Contact. It can also be used to generate a dynamic selection list using the label and the value.
{
"value": "12693542",
"label": "Newsletter"
},
{
"value": "12709995",
"label": "Follow-Up E-Mail"
},
{
"value": "12932287",
"label": "Neuer Tag"
}
Kopieren
List Data Fields
The /field endpoint is relevant in order to obtain the fields for Add or Update Contact. It can also be used to generate a dynamic list of fields using the label and the value.
Example 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 Creation for Automations
So that your users don't have to manually create a tag in KlickTipp, you can also do this for your integration via the API.
- Static: integration_partnername
- Dynamic: webinar_june2025
Recommendation: Dropdown filling & create tag button in the UI
| Action | Description | URL | Method | Body parameters |
|---|---|---|---|---|
| Create tag | Creates a new manual tag | /tag | POST | name |
Create Tag
Request body
- name string (required)
- name is the name of the new tag
Example JSON Body
{
"name": "New Tag"
}
Kopieren
Example JSON Response
{
"id": 12985883,
}
Kopieren
Segmentation of Contacts for Email Campaigns
In order to address contacts with an email campaign who have already gone through an opt-in process, the contacts can be linked to several tags without having to specify a new opt-in. The assignment of tags is the trigger in KlickTipp to start email campaigns. You can make these tags available in your integration via a new selection field, for example, so that users can control their email campaigns via the integration.
| Action | Description | URL | Method | Body parameters |
|---|---|---|---|---|
| Tag Contact | Adds one or more tags to a contact | /subscriber/tag | POST | email, tagid |
Tag Contact
Request body
- email string (recommended)
- Email addresses with @ characters are required for input.
- email or smsnumber must be present
- email and smsnumber may only be assigned to one contact
- tagid array (optional)
- A valid tag ID must be used for input.
- Use tags for segmentation & triggers
- Use /tag endpoint to query available tags
Example JSON Body
{
"email": "rene.ludwigs@klick-tipp.team",
"tagids": [
12042204,
12042205,
12042206,
12042207,
12042208
]
}
Kopieren
{
"success": true
}
Kopieren
Essential API Functions
Here you will find the essential calls that you need for robust automations such as in Make, n8n, Zapier. The endpoints /list, /tag and /field are relevant to get data for Add or Update Contact.
| Action | Description | URL | Method | Body parameters |
|---|---|---|---|---|
| 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 | |
| Get Contact ID | Returns the contact ID for an email address | /subscriber/search | POST | |
| 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
Good integrations are not only functional, but also user-friendly. Therefore, observe the following best practices for the user experience within your tool:
- Use Developer + Customer Key: Keys do not expire - they remain active even after account recovery. The developer key remains with you and the customer key is generated once by the end user - no new login or token refresh necessary.
- Dynamic drop-downs with fallback: Load data (e.g. tags, fields, lists) dynamically from KlickTipp via /tag, /field or /list. If the retrieval fails, show a manual input option or a message about the connection.
- Break down error messages: For 406 errors, show meaningful error messages directly in the IPaaS interface, e.g. "This email address has been unsubscribed - no re-entry possible" (Error 4).
- Optional: "Create Tag" function: Enables the creation of tags directly from the interface (if supported by the API) - ideal for quickly ready-to-use segmentations.
Further Documents & References
PHP Wrapper
In addition to the simple API documentation, there is also an exemplary interface class for PHP.
NodeJS / Node-RED
There is also an open source reference to our Node-RED connector, which can be used as the basis for a NodeJS implementation.
OpenAPI
We are also currently working on an OpenAPI specification.
API Documentation
You can find out more about our API and a link to all current requests and responses here.