Setting up an API key in KlickTipp is quick and straightforward. API keys are essential for connecting third-party providers to your KlickTipp account. In this guide, we’ll show you exactly how to create one step-by-step so you can start integrating with ease.
The Listbuilding API is a simplified, purpose-built subset of the KlickTipp API. It is designed for easy contact subscription scenarios and does not expose the full Management API feature set.
Each Listbuilding API Key is permanently linked to exactly one tag. This tag defines the entire behavior of the subscription.
All API actions always apply to the contact in relation to this tag:
- contacts are added or updated with this tag
- the tag can be removed
- or the contact can be unsubscribed entirely
| Action | Description |
|---|---|
| Signin | Creates or updates a contact and associates the tag linked to the API key. |
| Signout | Removes the tag of a contact associated with the API key. |
| Signoff | Unsubscribes a contact via the API key and prevents further communication. |
- Go to List Building → New List Building.
- Select the Entry via API Key button.
- Assign a name to your list building.
- Choose an opt-in process.
- (Optional) Add a manual tag under Additional Tagging.
- Copy the generated API key to your clipboard.
- Click Save.
From this point on, the API key fully defines:
- the opt-in process
- the assigned tag
- the subscription behavior
Now your API key is ready! Use it to integrate with your preferred third-party provider and start connecting seamlessly.
Once the API key is created, you can immediately use it to send API requests to KlickTipp via the Signin function of the Listbuilding API.
Example Request
curl -X POST \
https://api.klicktipp.com/subscriber/signin \
-H 'Content-Type: application/json' \
-d '{
"apikey": "{{API_KEY}}",
"email": "alex.example@klicktipp.example",
"fields": {
"fieldFirstName": "Alex",
"fieldLastName": "Example",
}
}'When submitting contact data via the Listbuilding API, values must match the field type and key defined in the account. The Listbuidling API does not provide endpoints to retrieve field 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 |
The Listbuilding API uses the same error codes as the Management API, limited to subscription-related scenarios.
| 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} |
Use the Management API if you need:
- dynamic tag selection
- opt-in process selection
- contact search or updates without tagging
- advanced automation control
The Listbuilding API is designed for simple and reliable contact subscription flows.
It provides a lightweight integration approach that requires no complex authentication, no metadata lookups, and no dynamic configuration. A single Listbuilding API Key fully defines the subscription behavior, including the opt-in process and the associated tag.
This makes the Listbuilding API ideal for forms, landing pages, and external tools that need a fast and secure way to add or update contacts in KlickTipp without implementing the full Management API.
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.