# KlickTipp Listbuilding API

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](/guides/listbuilding-api#error-handling)
---

## 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](/guides/listbuilding-api#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](/guides/listbuilding-api#error-handling)

---

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

Version: 0.0.0

## Servers

KlickTipp REST API
```
https://api.klicktipp.com
```

## Download OpenAPI description

[KlickTipp Listbuilding API](https://developers.klicktipp.com/_bundle/listbuilding-api.yaml)

## 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.

### Signin

 - [POST /subscriber/signin](https://developers.klicktipp.com/listbuilding-api/listbuilding-via-api-key/api.subscriber.signin.md): Creates or updates a contact and associates the tag linked to the API key.

### Signoff

 - [POST /subscriber/signoff](https://developers.klicktipp.com/listbuilding-api/listbuilding-via-api-key/api.subscriber.signoff.md): Unsubscribes a contact via the API key and prevents further communication.

### Signout

 - [POST /subscriber/signout](https://developers.klicktipp.com/listbuilding-api/listbuilding-via-api-key/api.subscriber.signout.md): Removes the tag of a contact associated with the API key.