Skip to content
/
Get Contact

KlickTipp API (0.0.0)

This specification describes the KlickTipp Management API.

It is intended for developers and integrators who want to interact directly with KlickTipp to manage contacts, tags, custom fields, opt-in processes, and automation workflows.
The API can be used standalone or through third-party platforms.

The specification focuses on correct request formats, authentication mechanisms, response structures, and error handling to ensure reliable and predictable integrations.

Good to know: This API uses session-based cookie authentication. Interactive Try-It requests do not fully support this login flow. For production testing click on the button to open our Collection in Postman.

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.

Getting Started

To access the API, you must authenticate and maintain a valid session.

  1. Authentication
    Most endpoints require cookie-based authentication.
    Use the login endpoint with your KlickTipp username and password to obtain a session cookie, which must be sent with all subsequent requests.

  2. Request Preparation
    Replace all placeholder values such as email addresses, IDs, or timestamps with valid test data.
    Invalid formats are a common source of errors.

  3. Response Handling
    The API returns structured payloads and numeric error codes.
    Always validate HTTP status codes and response bodies programmatically.

Authentication Overview

The KlickTipp Management API supports multiple authentication models, depending on the integration scenario.

  • Username and password authentication via session cookie
    Typically used for internal tools and administrative workflows.

  • Developer key and customer key authentication
    Intended for long-running, production-grade, or multi-tenant integrations.
    This model does not rely on session handling.

Documentation:
How to authenticate and access the Management API

Response Format

The KlickTipp Management API uses JSON as its response format.

All endpoints return JSON responses, including structured data, timestamps, and error details.
Integrations are expected to consume and validate JSON exclusively.

Data Formats and Validation

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

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

Incorrect field formats are a frequent cause of validation errors. Always ensure that submitted values match the expected field type definitions.

Documentation:
Data field types and Inputs

Error Handling

Errors are typically returned with HTTP status code 406 and include a numeric error code in the response body.

Integrations should handle errors explicitly and provide meaningful diagnostics for debugging and monitoring.

Documentation:
Error Handling

This specification is designed to support stable, predictable, and maintainable integrations with the KlickTipp platform.

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

Authentication

Endpoints for authenticating against the KlickTipp API and managing API access. These operations are used to establish and terminate authenticated sessions or to validate credentials required for protected API requests.

Operations

Contacts

Endpoints for creating, updating, and retrieving subscriber data in KlickTipp. These operations allow external systems to manage contact records, including core profile information and custom data fields.

Operations

List Contacts

Request

Lists the IDs of all contacts.

Query
statusArray of strings

Filter by subscriber status (pending, subscribed, unsubscribed)

bounceStatusArray of strings

Filter by bounce status (hardbounce, softbounce, spambounce, nobounce)

curl -i -X GET \
  https://api.klicktipp.com/subscriber

Responses

Success Response.

Bodyapplication/json
subscribersArray of strings

Array of subscribers

Response
application/json
[
  "123",
  "456"
]

Add or Update Contact

Request

Adds a new contact. If a contact with the same email already exists, it will be updated.

Body
required
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"
listidinteger or null

Opt-in process ID.

If provided, this opt-in process is used. If omitted, the predefined double opt-in process is triggered automatically, which may trigger an email to the contact.

Retrieve available opt-in process IDs via GET /list.

Example: 12345
tagidinteger or null

Tag ID assigned to the contact.

Used for segmentation and automation triggers. Retrieve available tag IDs via GET /tag.

Example: 56789
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 \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alex.example@klicktipp.example",
    "smsnumber": "+491701234567",
    "listid": 12345,
    "tagid": 56789,
    "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/json
idstringrequired
Example: "1"
listidstringrequired
Example: "12345"
optinstringrequired
Example: "25.09.2025"
optin_ipstringrequired
Example: "0.0.0.0"
emailstringrequired
Example: "t1@example.com"
statusstringrequired
Example: "Subscribed"
bouncestringrequired
Example: "Not Bounced"
datestringrequired
Example: "25.09.2025"
ipstringrequired
Example: "0.0.0.0"
unsubscriptionstringrequired
Example: ""
unsubscription_ipstringrequired
Example: "0.0.0.0"
referrerstringrequired
Example: ""
sms_phonestringrequired
Example: "004968211034234"
sms_statusstringrequired
Example: "Subscribed"
sms_bouncestringrequired
Example: "Not Bounced"
sms_datestringrequired
Example: "15.12.2025"
sms_unsubscriptionstringrequired
Example: ""
sms_referrerstringrequired
Example: null
fieldFirstNamestringrequired
Example: "Alex"
fieldLastNamestringrequired
Example: "Example"
fieldCompanyNamestringrequired
Example: "Example Corp"
fieldStreet1stringrequired
Example: "Example Street 1"
fieldStreet2stringrequired
Example: ""
fieldCitystringrequired
Example: "Berlin"
fieldStatestringrequired
Example: "Berlin"
fieldZipstringrequired
Example: "10115"
fieldCountrystringrequired
Example: "DE"
fieldPrivatePhonestringrequired
Example: "00491701234567"
fieldMobilePhonestringrequired
Example: "00491701234567"
fieldPhonestringrequired
Example: "004968211034234"
fieldFaxstringrequired
Example: "004922012345678"
fieldWebsitestringrequired
Example: "https://www.klicktipp.example"
fieldBirthdaystringrequired
Example: "755222400"
fieldLeadValuestringrequired
Example: "100"
tagsArray of stringsrequired
Example: ["17","18"]
smart_tagsobjectrequired
Example: {"17":"1758821945","18":"1758822131"}
notification_emails_sentobjectrequired
Example: {"45":"1758821945"}
notification_emails_openedobjectrequired
Example: {"45":"1758822131"}
notification_emails_clickedobjectrequired
Example: {"45":"1758822131"}
manual_tagsobjectrequired
Example: {"21":"1759753677"}
emails_sentobjectrequired
Example: {"1":"1758822606","2":"1758822769"}
emails_openedobjectrequired
Example: {"1":"1758822610","2":"1758884682"}
emails_clickedobjectrequired
Example: {"1":"1758822733"}
campaigns_startedobjectrequired
Example: {"6":"1759753673"}
campaigns_finishedobjectrequired
Example: {"6":"1759753677"}
Response
application/json
{
  "id": "1",
  "listid": "12345",
  "optin": "25.09.2025",
  "optin_ip": "0.0.0.0",
  "email": "t1@example.com",
  "status": "Subscribed",
  "bounce": "Not Bounced",
  "date": "25.09.2025",
  "ip": "0.0.0.0",
  "unsubscription": "",
  "unsubscription_ip": "0.0.0.0",
  "referrer": "",
  "sms_phone": "004968211034234",
  "sms_status": "Subscribed",
  "sms_bounce": "Not Bounced",
  "sms_date": "15.12.2025",
  "sms_unsubscription": "",
  "sms_referrer": null,
  "fieldFirstName": "Alex",
  "fieldLastName": "Example",
  "fieldCompanyName": "Example Corp",
  "fieldStreet1": "Example Street 1",
  "fieldStreet2": "",
  "fieldCity": "Berlin",
  "fieldState": "Berlin",
  "fieldZip": "10115",
  "fieldCountry": "DE",
  "fieldPrivatePhone": "00491701234567",
  "fieldMobilePhone": "00491701234567",
  "fieldPhone": "004968211034234",
  "fieldFax": "004922012345678",
  "fieldWebsite": "https://www.klicktipp.example",
  "fieldBirthday": "755222400",
  "fieldLeadValue": "100",
  "tags": [
    "17",
    "18"
  ],
  "smart_tags": {
    "17": "1758821945",
    "18": "1758822131"
  },
  "notification_emails_sent": {
    "45": "1758821945"
  },
  "notification_emails_opened": {
    "45": "1758822131"
  },
  "notification_emails_clicked": {
    "45": "1758822131"
  },
  "manual_tags": {
    "21": "1759753677"
  },
  "emails_sent": {
    "1": "1758822606",
    "2": "1758822769"
  },
  "emails_opened": {
    "1": "1758822610",
    "2": "1758884682"
  },
  "emails_clicked": {
    "1": "1758822733"
  },
  "campaigns_started": {
    "6": "1759753673"
  },
  "campaigns_finished": {
    "6": "1759753677"
  }
}

Get Contact

Request

Returns the complete data of a contact.

Path
subscriberidstringrequired
curl -i -X GET \
  'https://api.klicktipp.com/subscriber/{subscriberid}'

Responses

Success Response.

Bodyapplication/json
idstringrequired
Example: "1"
listidstringrequired
Example: "12345"
optinstringrequired
Example: "25.09.2025"
optin_ipstringrequired
Example: "0.0.0.0"
emailstringrequired
Example: "t1@example.com"
statusstringrequired
Example: "Subscribed"
bouncestringrequired
Example: "Not Bounced"
datestringrequired
Example: "25.09.2025"
ipstringrequired
Example: "0.0.0.0"
unsubscriptionstringrequired
Example: ""
unsubscription_ipstringrequired
Example: "0.0.0.0"
referrerstringrequired
Example: ""
sms_phonestringrequired
Example: "004968211034234"
sms_statusstringrequired
Example: "Subscribed"
sms_bouncestringrequired
Example: "Not Bounced"
sms_datestringrequired
Example: "15.12.2025"
sms_unsubscriptionstringrequired
Example: ""
sms_referrerstringrequired
Example: null
fieldFirstNamestringrequired
Example: "Alex"
fieldLastNamestringrequired
Example: "Example"
fieldCompanyNamestringrequired
Example: "Example Corp"
fieldStreet1stringrequired
Example: "Example Street 1"
fieldStreet2stringrequired
Example: ""
fieldCitystringrequired
Example: "Berlin"
fieldStatestringrequired
Example: "Berlin"
fieldZipstringrequired
Example: "10115"
fieldCountrystringrequired
Example: "DE"
fieldPrivatePhonestringrequired
Example: "00491701234567"
fieldMobilePhonestringrequired
Example: "00491701234567"
fieldPhonestringrequired
Example: "004968211034234"
fieldFaxstringrequired
Example: "004922012345678"
fieldWebsitestringrequired
Example: "https://www.klicktipp.example"
fieldBirthdaystringrequired
Example: "755222400"
fieldLeadValuestringrequired
Example: "100"
tagsArray of stringsrequired
Example: ["17","18"]
smart_tagsobjectrequired
Example: {"17":"1758821945","18":"1758822131"}
notification_emails_sentobjectrequired
Example: {"45":"1758821945"}
notification_emails_openedobjectrequired
Example: {"45":"1758822131"}
notification_emails_clickedobjectrequired
Example: {"45":"1758822131"}
manual_tagsobjectrequired
Example: {"21":"1759753677"}
emails_sentobjectrequired
Example: {"1":"1758822606","2":"1758822769"}
emails_openedobjectrequired
Example: {"1":"1758822610","2":"1758884682"}
emails_clickedobjectrequired
Example: {"1":"1758822733"}
campaigns_startedobjectrequired
Example: {"6":"1759753673"}
campaigns_finishedobjectrequired
Example: {"6":"1759753677"}
Response
application/json
{
  "id": "1",
  "listid": "12345",
  "optin": "25.09.2025",
  "optin_ip": "0.0.0.0",
  "email": "t1@example.com",
  "status": "Subscribed",
  "bounce": "Not Bounced",
  "date": "25.09.2025",
  "ip": "0.0.0.0",
  "unsubscription": "",
  "unsubscription_ip": "0.0.0.0",
  "referrer": "",
  "sms_phone": "004968211034234",
  "sms_status": "Subscribed",
  "sms_bounce": "Not Bounced",
  "sms_date": "15.12.2025",
  "sms_unsubscription": "",
  "sms_referrer": null,
  "fieldFirstName": "Alex",
  "fieldLastName": "Example",
  "fieldCompanyName": "Example Corp",
  "fieldStreet1": "Example Street 1",
  "fieldStreet2": "",
  "fieldCity": "Berlin",
  "fieldState": "Berlin",
  "fieldZip": "10115",
  "fieldCountry": "DE",
  "fieldPrivatePhone": "00491701234567",
  "fieldMobilePhone": "00491701234567",
  "fieldPhone": "004968211034234",
  "fieldFax": "004922012345678",
  "fieldWebsite": "https://www.klicktipp.example",
  "fieldBirthday": "755222400",
  "fieldLeadValue": "100",
  "tags": [
    "17",
    "18"
  ],
  "smart_tags": {
    "17": "1758821945",
    "18": "1758822131"
  },
  "notification_emails_sent": {
    "45": "1758821945"
  },
  "notification_emails_opened": {
    "45": "1758822131"
  },
  "notification_emails_clicked": {
    "45": "1758822131"
  },
  "manual_tags": {
    "21": "1759753677"
  },
  "emails_sent": {
    "1": "1758822606",
    "2": "1758822769"
  },
  "emails_opened": {
    "1": "1758822610",
    "2": "1758884682"
  },
  "emails_clicked": {
    "1": "1758822733"
  },
  "campaigns_started": {
    "6": "1759753673"
  },
  "campaigns_finished": {
    "6": "1759753677"
  }
}

Update Contact

Request

Updates a contact.

Path
subscriberidintegerrequired

Contact ID.

Body
required
newemailstring 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"
newsmsnumberstring 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 PUT \
  'https://api.klicktipp.com/subscriber/{subscriberid}' \
  -H 'Content-Type: application/json' \
  -d '{
    "newemail": "alex.example@klicktipp.example",
    "newsmsnumber": "+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 (200).

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

Delete Contact

Request

Deletes a contact.

Path
subscriberidintegerrequired

Contact ID.

curl -i -X DELETE \
  'https://api.klicktipp.com/subscriber/{subscriberid}'

Responses

Success Response (200).

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

Unsubscribe Contact

Request

Unsubscribes a contact, preventing further communication.

Body
required
emailstringrequired

Email address of the subscriber

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

Responses

Success Response (200).

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

Search Contact ID

Request

Returns the contact ID for an email address.

Body
required
emailstringrequired

Email address of the subscriber

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

Responses

Success Response.

Bodyapplication/jsonArray [
integer
]
Response
application/json
[
  3
]

Search Tagged Contacts

Request

Returns the IDs and tagging timestamps of all tagged contacts.

Body
required
tagidintegerrequired
Example: "17"
statusFilterArray of stringsrequired

Filter by subscriber status (pending, subscribed, unsubscribed)

Example: ["subscribed","pending"]
bounceStatusFilterArray of stringsrequired

Filter by bounce status (hardbounce, softbounce, spambounce, nobounce)

Example: ["nobounce","softbounce"]
curl -i -X POST \
  https://api.klicktipp.com/subscriber/tagged \
  -H 'Content-Type: application/json' \
  -d '{
    "tagid": "17",
    "statusFilter": [
      "subscribed",
      "pending"
    ],
    "bounceStatusFilter": [
      "nobounce",
      "softbounce"
    ]
  }'

Responses

Success Response.

Bodyapplication/json
property name*stringadditional property
Response
application/json
{
  "3": "1760530436"
}

Contact Tagging

Endpoints for assigning and removing tags from subscribers. Tagging operations are used to control automations, trigger workflows, and reflect changes in subscriber state based on external events.

Operations

Data Fields

Endpoints for managing custom data fields associated with subscribers. These operations are used to define, retrieve, and map structured subscriber data for personalization and integration purposes.

Operations

Opt-In Processes

Endpoints related to opt-in workflows and subscription confirmation processes. These operations support compliant subscriber onboarding, including single and double opt-in flows.

Operations

Tags

Endpoints for managing and querying available tags in KlickTipp. These operations allow systems to retrieve tag metadata and understand which tags can be used for segmentation and automation control.

Operations
© 2026 KlickTipp. All rights reserved.