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.
The Subscribe Contact action is the central entry point for adding new contacts to KlickTipp or updating existing ones. It is typically used when contact data is submitted via forms, landing pages, or external tools.
Before calling this endpoint, integrations should load the required reference data from other endpoints, such as opt-in processes, tags, and data fields. This ensures that valid IDs are used and allows users to configure subscriptions dynamically and reliably.
In practice, a robust integration first fetches the necessary metadata via List Endpoints and then uses the Add or Update Contact endpoint to create or update contacts and trigger the corresponding opt-in and automation workflows.
| Action | Description |
|---|---|
| Add or Update Contact | Adds a new contact. If a contact with the same email already exists, it will be updated. |
| List Opt-in Processes | Lists the IDs and names of all opt-in processes. |
| List Tags | Lists the IDs and names of all tags. |
| List Data Fields | Lists the IDs and names of all data fields. |
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.
Here are the most important field types for Add or Update Contact - ideal for individual contact data.
| Data field type | Input |
|---|---|
| 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 | Displayed as HH:MM (Unix timestamp required via API) |
| Date | Displayed as DD.MM.YYYY (Unix timestamp required via API) |
| Date & time | Displayed as DD.MM.YYYY HH:MM:SS (Unix timestamp required via API) |
| HTML | Any HTML code |
Here are the most important error codes for Add or Update Contact - ideal for logging & user feedback.
| HTTP Status | Error Code | Description |
|---|---|---|
| 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} |
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.
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.
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.
Tags serve as the main trigger for automations and email campaigns in KlickTipp. Contacts can hold multiple tags simultaneously, and adding or removing a tag can be used to start or stop automated workflows without affecting the original opt-in.
| Action | Description |
|---|---|
| Tag Contact | Adds one or more tags to a contact |
| Untag Contact | Removes a tag from a contact. |
So that your users don't have to manually create a tag in KlickTipp, you can also manage Tags for your integration via the API.
Recommendation
- Use static tag names for integrations (e.g.
webinartool) - Use dynamic tags for specific events (e.g.
webinar_june_2026) - Provide a dropdown and optional “Create Tag” action in the UI
| Action | Description |
|---|---|
| Create Tag | Creates a new manual tag |
Here you will find the essential calls that you need for robust automations.
| Action | Description |
|---|---|
| Add or Update Contact | Adds a new contact. If a contact with the same email already exists, it will be updated. |
| List Opt-in Processes | Lists the IDs and names of all opt-in processes. |
| List Tags | Lists the IDs and names of all tags. |
| List Data Fields | Lists the IDs and names of all data fields. |
| Unsubscribe Contact | Unsubscribes a contact, preventing further communication. |
| Search Contact ID | Returns the contact ID for an email address. |
| Tag Contact | Adds one or more tags to a contact. |
| Untag Contact | Removes a tag from a contact. |
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. 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 your interface, e.g. "This email address has been unsubscribed - no re-entry possible" (Error 4).
- Optional: "Create Tag" function: Enable the creation of tags directly from the interface (if supported by the API) - ideal for quickly ready-to-use segmentations.
The KlickTipp Management API enables you to build powerful, production-ready integrations with full control over contacts, tags, opt-in processes, and automations.
Robust integrations follow a clear pattern: first load reference data such as opt-in processes, tags, and data fields via list endpoints, then create or update contacts using stable IDs, and finally control automations through tag assignment and removal. This approach ensures predictable behavior, reliable configurations, and a smooth user experience inside your integration.
By combining the Management API with best practices such as dynamic configuration, meaningful error handling, and tag-based automation logic, you can build scalable integrations that work reliably across different customer accounts and use cases.
Remember that API access requires a Premium plan or higher. If you’re not on the appropriate plan, you’ll need to upgrade to unlock this feature.