API & Interface
KlickTipp API: Overview of All Functions and Endpoints
Want to seamlessly integrate KlickTipp into your tools and systems? Whether you're creating automations, synchronizing contacts or implementing custom workflows, a solid understanding of the KlickTipp API is critical to your success. This comprehensive guide is for developers and integrators working directly with the KlickTipp API - or using platforms like FunnelTools, Make or Zapier.
You will learn how to avoid typical mistakes and apply best practices around data formats, error handling and authentication. Learn how to format fields correctly, how to use Unix timestamps for date and time and which authentication method (API key, login data or developer-customer key combination) is suitable for your use case. With these tips, your integration will succeed safely and smoothly.
If you are a KlickTipp partner and would like to learn how to make the most of the individual endpoints, take a look at our Developer Guide for KlickTipp Integrations.
Why this is important:
- Prevent avoidable errors: Incorrectly formatted fields and test data often lead to errors that are difficult to trace. This guide will help you get it right the first time.
- Ensure stable integrations: Understand how the different authentication methods work - and which one is right for your application.
- Simplify troubleshooting: Decode the KlickTipp API error codes and solve problems quickly and specifically.
- Proven tips from the field: Benefit from internal know-how and experience from real projects.
From timestamps to authentication logic, this article will help you build integrations that just work.
Good to Know:
Would you prefer to learn about our API functions via our Postman Collection? Then click on the button to open our Collection in Postman.
Run in Postman
Function Overview
Here you will find an overview of the endpoints of our REST API if you code your own automations and therefore want to address our endpoints directly:
Authentication
HTTP requests to the REST API are protected by cookie-based authentication. To obtain a valid session cookie, use the login function with user name and password:
curl -X POST https://api.klicktipp.com/account/login.json \
--data-urlencode "username=username" \
--data-urlencode "password=XXXXXXXX"
Kopieren
You will find your session cookie (consisting of → session_name and → sessid) in the HTTP response header under Set-Cookie. You must send this cookie in the header of all subsequent API requests.
Return Formats
The KlickTipp REST API supports four return formats: XML, JSON, PHP and HTML. When making your API requests, make sure to determine the expected format via the ending of the URL.
You can define your desired format by appending the corresponding extension to the URL - e.g:
https://api.klicktipp.com/list.json
Kopieren
Important to Know:
All meta information, such as timestamps for taggings, is only supplied in full via the JSON format.
Available Functions at a Glance
Authentication
| Function | URL | Method | Parameters | Example parameters JSON |
|---|---|---|---|---|
| Login | https://api.klicktipp.com/account/login | POST | username, password | {"username": "user", "password": "pass"} |
| Logout | https://api.klicktipp.com/account/logout | POST | - | - |
Contact Functions
| Function | URL | Method | Parameters | Example parameters JSON |
|---|---|---|---|---|
| Add or update contact** | https://api.klicktipp.com/subscriber | POST | email, smsnumber, listid, tagid, fields | see example above |
| Unsubscribe contact | https://api.klicktipp.com/subscriber/unsubscribe | POST | {"email": "max@example.com"} | |
| List contacts | https://api.klicktipp.com/subscriber | GET | - | - |
| Get contact | https://api.klicktipp.com/subscriber/<subscriberid> | GET | subscriberid is required in URL | - |
| 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 | {"tagid": 123} |
| Update contact** | https://api.klicktipp.com/subscriber/<subscriberid> | PUT | fields, newemail, newsmsnumber, subscriberid is required in URL | {"fields": {...}, "newemail": "...", "newsmsnumber": "..."} |
| Delete contact | https://api.klicktipp.com/subscriber/<subscriberid> | DELETE | subscriberid is required in URL | - |
*The endpoints → Search Tagged Contacts & → List contacts only return active contacts.
**The end points → Add or update contact & → Update contact differ in that the contact is re-entered in the → Add or update contact function. With the → Update contact function, however, only the contact is updated.
Tag Contacts Functions
| Function | URL | Method | Parameters | Example parameters 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} |
Data Fields Functions
| Function | URL | Method | Example parameters |
|---|---|---|---|
| List data fields | https://api.klicktipp.com/field | GET | - |
Opt-in Process Functions
| Function | URL | Method | Parameters | Example parameters |
|---|---|---|---|---|
| List opt-in processes | https://api.klicktipp.com/list | GET | - | - |
| Get opt-in process | https://api.klicktipp.com/list/<listid> | GET | opt-in id is required in URL | |
| Search Redirect URL | https://api.klicktipp.com/list/redirect | POST | listid, email | {"listid": "123", "email": "max@example.com"} |
Tag Functions
| Function | URL | Method | Parameters | Example parameters JSON |
|---|---|---|---|---|
| List tags | https://api.klicktipp.com/tag | GET | - | - |
| Get tag | https://api.klicktipp.com/tag/<tagid> | GET | tag id is required in URL | - |
| Create tag | https://api.klicktipp.com/tag | POST | name | {"name": "New day"} |
| Update tag | https://api.klicktipp.com/tag/<tagid> | PUT | name, tag id is required in URL | {"name": "Updated tag"} |
| Delete tag | https://api.klicktipp.com/tag/<tagid> | DELETE | tag id is required in URL | - |
API Key Functions
| Function | URL | Method | Parameters | Example parameters 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": "..."} |
Example Payload for the Creation of Contacts
Here you can see an example of a complete payload as it can be used for the Add or update contact function. In addition to standard fields, a user-defined field (field12345) is also included:
{
"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
Field Types & Formats - what you need to consider
When submitting data to the KlickTipp API, it is important that the content corresponds to the correct formats for the respective field type. Otherwise, validation errors or incomplete entries may occur. The formatting differs depending on the field type. This is particularly important when using your own API, but also for third-party forms such as FunnelTools, Make or Zapier.
| Field type | Expected content | Example value | Note |
|---|---|---|---|
| Line | Text in one line | Max Mustermann | No line breaks |
| Paragraph | Text with paragraphs | This is a text.\nwith paragraph. | \n for paragraph |
| Valid address with @ | max@example.com | No space | |
| Number | Whole number (integer) | 42 | No period, no comma |
| Decimal number | Decimal number | Input 1999 → Output 19.99 | Dot as decimal separator in the output |
| URL | Valid web address | https://klicktipp.com | Must start with http:// or https:// |
| Time | Unix timestamp between 0-86399 | 52200 (for 14:30) | Seconds since midnight |
| Date | Unix timestamp (in seconds) | 1715126400 (for 08.05.2024) | No "DD.MM.YYYY" format via API |
| Date & time | Unix timestamp (in seconds) | 1715603400 (for 13.05.2024 15:30:00) | Do not send a space or date format |
| HTML | HTML formatted content | Hello world | Only useful if the field allows HTML |
Format notes for API use
- Always transfer Unix timestamp (in seconds) for time and date fields
- No German date formats (e.g. 31.12.2024) - will not be recognized
- Values such as telephone numbers, links, prices etc. must be formatted to match the field definition (see /field)
Transfer Date and Time correctly
The KlickTipp API only accepts Unix timestamps in seconds for time and date values.
Time
| Time | Unix timestamp |
|---|---|
| 00:00 | 0 |
| 14:30 | 52.200 |
| 23:59:59 | 86.399 |
Only values in the range 0-86399 are valid.
Date
- Expected: Unix timestamp, e.g. 1651276800 for 30.04.2022.
- Display in KlickTipp: DD.MM.YYYY
Date + Time
- Combination also as timestamp, e.g. 1715603400 = 13.05.2024 15:30:00
- Tip: Always use UTC, no time zone strings.
Understanding and intercepting Error Codes
The API usually returns error codes with HTTP 406. The JSON contains an "error" field with a number.
{ "error": 9 }
Kopieren
Overview of common Errors
| Code | Description |
|---|---|
| 4 | E-mail address is unsubscribed - re-registration not possible. |
| 5 | Invalid e-mail address |
| 6 | Confirmation email could not be sent. |
| 7 | E-mail address not found. (Can also occur if fields were sent in the wrong format - e.g. wrong timestamp for date/time). |
| 8 | Invalid value in a user-defined field. |
| 9 | SMS number is already assigned to another contact. SMS numbers must be unique. |
| 10 | Failed to update the contact. |
| 11 | Invalid SMS number |
| 12 | Internal error, please try again later. |
| 30 | E-mail address has been blocked and is not allowed for entries. |
| 31 | SmartTags can only be assigned by the system. |
| 32 | Neither e-mail address nor SMS number given - one of the two is required. |
| 401 | User was not found. |
| 402 | Opt-in process was not found. |
| 403 | Tag was not found. |
| 406 | The server cannot provide the requested content in the format specified by the client. The client uses the so-called “Accept” headers to send information about what type of content it can accept (e.g. file formats in the return value - this can be controlled via the ending of the URL). |
| 507 | E-mail address is already assigned to another contact. |
Best practice: Catch errors in a structured way & display them in the UI so that the user can see suitable feedback for debugging.
Differences in Authentication between the API Functions “subscribe” and “signin”
The two functions are used to enter contacts in KlickTipp - but they differ in terms of scope and authentication:
| Feature | subscribe | signin |
|---|---|---|
| Authentication | Username & Password | API key (list building) |
| Use | Manual, internal (admin, sub-account) | Automated, e.g. from web forms |
| Return | Contact object | URL of the confirmation page |
| Suitable for | Internal tools, interfaces with user account access | External systems, iPaaS platforms, web forms |
| Security | Access to the entire account (if main account is used) | Limited access via API key |
| Opt-In | Optional via listid | Controlled by assigned API key |
Tip: Many of our partners automate their web forms via the Signin endpoint. For authentication, you must create an API key in KlickTipp under the so-called → listbuildings. Otherwise, authentication runs via the access data for the account/sub-account (user name & password) and not always necessarily via the API key.
FAQ - Frequently asked Questions
The KlickTipp API blocks undeliverable addresses such as test@test.com. Use real test addresses with working mailboxes.
As a Unix timestamp in seconds.Example: 30.04.2022 → 1651276800 See also the FAQ on "Date of birth" for more information.
The ID used does not exist or is incorrect. Get valid IDs beforehand via API endpoints such as /tag, /list or /field. Use a GET request via cURL or PHP wrapper, for example.
Common causes: Sub-account does not have the "API" role Username instead of e-mail address was not used correctlyTips:Use dedicated sub-accounts with the "API" role Avoid using the main account for API access
Use hours * 3600 + minutes * 60 → e.g. 14:30 = 14*3600 + 30*60 = 52200.
A Unix timestamp. Example: 1651276800 for 30.04.2022.
Use with:
- Internal tools and workflows
- Tests with the PHP wrapper or CURL
- API calls where no API key or developer key is used
Important:
- Always use the user name, not the e-mail address
- Authentication via login endpoint (/account/login)
- Only recommended with sub-account with "API" role
Use for:
- Simple external integrations (e.g. newsletter forms, lead magnets)
- Tools such as Make, Zapier, Funnelbuilder etc.
- Functions: signin, signout, signoff
Special features:
- API key is directly linked to a list building process
- Is created in the KlickTipp account under → Listbuilding → Entry via API key
- Authentication takes place directly in the body via apikey
Tip:Avoid username/password in external tools - API key is more secure and stable.
Use for:
- Productive integrations that need to run permanently and robustly
- Multi-tenant applications, white label setups or own SaaS integrations
- Integration in systems in which many end users should have access to KlickTipp
Process:
- You as the provider generate the developer key
- Your customer generates their customer key (once) via a special URL
- Authentication is permanent, without login or session handling
Advantage:
- No expiration of the session
- No saving of passwords
- Very good separation of provider and customer access
The most important Facts at a Glance
The KlickTipp API offers many possibilities - provided it is used correctly. With the tips and best practices listed here, you can avoid typical errors, save time when troubleshooting and ensure stable, secure integrations. Pay attention to correct field formats, use suitable authentication methods and interpret error messages correctly. This way, nothing stands in the way of successful automation with KlickTipp.