Skip to content

KlickTipp Listbuilding API (0.0.0)

This specification describes the KlickTipp Listbuilding API.

It is intended for external tools, websites, and automation platforms that integrate KlickTipp list-building functionality using API Key authentication. Typical use cases include newsletter sign-up forms, lead magnets, landing pages, and no-code or iPaaS-based automations.

The Listbuilding API provides a restricted and purpose-built interface for managing contacts without requiring full account authentication. Using an API key, external systems can add or update contacts, assign or remove a tag, trigger opt-in processes, or unsubscribe contacts from further communication.

Authentication Model

All endpoints in this specification use API Key authentication.

The API key is generated in KlickTipp under:

Listbuilding → New Listbuilding → Entry via API key

Each API key is permanently linked to a specific opt-in process and tag. This defines the scope and behavior of the integration.

Authentication is performed by sending the API key directly in the request body. No session handling or cookies are required.

Documentation:
How to Create an API Key

Intended Usage

This API is optimized for:

  • External signup and opt-in forms
  • Embedded integrations in websites such as WordPress or landing page builders
  • Automated lead processing via third-party platforms

It is not intended for administrative workflows or full account management.

Core Endpoints

The Listbuilding API focuses on a small, stable set of endpoints designed for external systems:

  • 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

Base URL

The base URL for the KlickTipp API production environment is:

  https://api.klicktipp.com

All endpoints defined in this specification are relative to this base URL.

Response Format

The KlickTipp Listbuilding API uses JSON as its response format.

All endpoints return JSON responses containing structured payloads and error information. Integrations are expected to consume and validate JSON responses exclusively.

Data Formats and Validation

Date and time values must always be provided as Unix timestamps (seconds).

For the data field type Time only timestamps representing the first day of the Unix epoch date (00:00:00 UTC) are accepted. Any time-of-day information beyond the day boundary is rejected.

Formatted date strings, locale-specific formats, and timezone annotations are not supported.

Incorrect field formats are one of the most common causes of errors when using the Listbuilding API. Always ensure that submitted values match the expected field type definitions.

Documentation:
Data field types and Inputs

Error Handling

Errors are returned as JSON responses and typically use HTTP status code 403 or 406, depending on the failure type.

Each error includes a numeric error code that should be handled explicitly by the integrating system.

Documentation:
Error Handling

This specification is designed to support simple, secure, and predictable list-building integrations with KlickTipp.

Download OpenAPI description
listbuilding-api.json
listbuilding-api.yaml
Languages
Servers
KlickTipp REST API
https://api.klicktipp.com

Listbuilding via API Key

Endpoints for adding and removing subscribers using an API key–based authentication model. These operations are optimized for secure listbuilding scenarios where full API authentication is not required.

Operations

Signin

Request

Creates or updates a contact and associates the tag linked to the API key.

Body
required
apikeystringrequired

API key

Example: "{{api_key}}"
emailstring or null

Valid email address and must contain @.

Either email or smsnumber is required. Email address must be unique per contact.

Example: "alex.example@klicktipp.example"
smsnumberstring or null

Phone number in international format.

Either email or smsnumber is required. SMS number must be unique per contact.

Accepted input:

  • +4912345678
  • 004912345678

Stored format:

  • 004912345678
Example: "+491701234567"
fieldsobject or null

Additional custom fields for the subscriber.

Keys must match the field names configured in KlickTipp. Each field expects a specific data format depending on its field type.

  • Line: Single-line text without line breaks. Example: Alex Example
  • Paragraph: Text with paragraphs. Use \n to separate paragraphs. Example: Dies ist ein Text.\nMit Absatz.
  • Number: Integer value. No dot, no comma. Example: 42
  • Decimal Number: Decimal value. Output always uses a dot as decimal separator. Example: Input 1999 → Output 19.99
  • URL: Valid web address. Must start with http:// or https://. Example: https://klicktipp.com
  • Time: Unix timestamp between 0 and 86399 (seconds since midnight). Example: 52200 (14:30 GMT)
  • Date: Unix timestamp in seconds. Date formats like DD.MM.YYYY are not supported. Example: 1715126400 (08.05.2024 GMT)
  • Date & Time: Unix timestamp in seconds. Do not send formatted date strings or values with spaces. Example: 1715603400 (13.05.2024 12:30:00 GMT)
  • HTML: HTML-formatted content. Only use this type if the field explicitly allows HTML. Example: <strong>Hello World</strong>
Example: {"fieldFirstName":"Alex","fieldLastName":"Example","fieldCompanyName":"Example Corp","fieldStreet1":"Example Street 1","fieldStreet2":"","fieldCity":"Berlin","fieldState":"Berlin","fieldZip":"10115","fieldCountry":"DE","fieldPrivatePhone":"+491701234567","fieldMobilePhone":"+491701234567","fieldPhone":"+492201234567","fieldFax":"4922012345678","fieldWebsite":"https://www.klicktipp.example","fieldBirthday":"755222400","fieldLeadValue":"100","field12345":"Custom Field Value"}
curl -i -X POST \
  https://api.klicktipp.com/subscriber/signin \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "{{api_key}}",
    "email": "alex.example@klicktipp.example",
    "smsnumber": "+491701234567",
    "fields": {
      "fieldFirstName": "Alex",
      "fieldLastName": "Example",
      "fieldCompanyName": "Example Corp",
      "fieldStreet1": "Example Street 1",
      "fieldStreet2": "",
      "fieldCity": "Berlin",
      "fieldState": "Berlin",
      "fieldZip": "10115",
      "fieldCountry": "DE",
      "fieldPrivatePhone": "+491701234567",
      "fieldMobilePhone": "+491701234567",
      "fieldPhone": "+492201234567",
      "fieldFax": "4922012345678",
      "fieldWebsite": "https://www.klicktipp.example",
      "fieldBirthday": "755222400",
      "fieldLeadValue": "100",
      "field12345": "Custom Field Value"
    }
  }'

Responses

Success Response.

Bodyapplication/jsonArray [
string
]
Response
application/json
[
  "https://klick.example.com/pending/1z3z6zzpz7b76"
]

Signoff

Request

Unsubscribes a contact via the API key and prevents further communication.

Body
required
apikeystringrequired

API key

Example: "{{api_key}}"
emailstringrequired

Email address of the subscriber

Example: "alex.example@klicktipp.example"
curl -i -X POST \
  https://api.klicktipp.com/subscriber/signoff \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "{{api_key}}",
    "email": "alex.example@klicktipp.example"
  }'

Responses

Success Response (200).

Bodyapplication/jsonArray [
boolean
]
Response
application/json
[
  true
]

Signout

Request

Removes the tag of a contact associated with the API key.

Body
required
apikeystringrequired

API key

Example: "{{api_key}}"
emailstringrequired

Email address of the subscriber

Example: "alex.example@klicktipp.example"
curl -i -X POST \
  https://api.klicktipp.com/subscriber/signout \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "{{api_key}}",
    "email": "alex.example@klicktipp.example"
  }'

Responses

Success Response (200).

Bodyapplication/jsonArray [
boolean
]
Response
application/json
[
  true
]
© 2026 KlickTipp. All rights reserved.