# KlickTipp API

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.

<div class="postman-run-button"
data-postman-action="collection/fork"
data-postman-visibility="public"
data-postman-var-1="45081328-af33033f-f8b3-4d38-b2ce-af1b9c3b2a28"
data-postman-collection-url="entityId=45081328-af33033f-f8b3-4d38-b2ce-af1b9c3b2a28&entityType=collection&workspaceId=c516bfec-10fe-4a61-a25e-0d5eb0361079"></div>
<script type="text/javascript">
  (function (p,o,s,t,m,a,n) {
    !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
    !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
      (n = o.createElement("script")),
      (n.id = s+t), (n.async = 1), (n.src = m), n
    ));
  }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
</script>

---

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

---

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


Version: 0.0.0

## Servers

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

## Download OpenAPI description

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

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

### Login

 - [POST /account/login](https://developers.klicktipp.com/management-api/authentication/api.account.login.md): Logs into the API and retrieves session details for further interactions.

### Logout

 - [POST /account/logout](https://developers.klicktipp.com/management-api/authentication/api.account.logout.md): Logs out of the API and ends the session.

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

### List Contacts

 - [GET /subscriber](https://developers.klicktipp.com/management-api/contacts/api.subscriber.index.md): Lists the IDs of all contacts.

### Add or Update Contact

 - [POST /subscriber](https://developers.klicktipp.com/management-api/contacts/api.subscriber.create.md): Adds a new contact. If a contact with the same email already exists, it will be updated.

### Get Contact

 - [GET /subscriber/{subscriberid}](https://developers.klicktipp.com/management-api/contacts/api.subscriber.retrieve.md): Returns the complete data of a contact.

### Update Contact

 - [PUT /subscriber/{subscriberid}](https://developers.klicktipp.com/management-api/contacts/api.subscriber.update.md): Updates a contact.

### Delete Contact

 - [DELETE /subscriber/{subscriberid}](https://developers.klicktipp.com/management-api/contacts/api.subscriber.delete.md): Deletes a contact.

### Unsubscribe Contact

 - [POST /subscriber/unsubscribe](https://developers.klicktipp.com/management-api/contacts/api.subscriber.unsubscribe.md): Unsubscribes a contact, preventing further communication.

### Search Contact ID

 - [POST /subscriber/search](https://developers.klicktipp.com/management-api/contacts/api.subscriber.search.md): Returns the contact ID for an email address.

### Search Tagged Contacts

 - [POST /subscriber/tagged](https://developers.klicktipp.com/management-api/contacts/api.subscriber.tagged.md): Returns the IDs and tagging timestamps of all tagged contacts.

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

### Tag Contact

 - [POST /subscriber/tag](https://developers.klicktipp.com/management-api/contact-tagging/api.subscriber.tag.md): Adds one or more tags to a contact.

### Untag Contact

 - [POST /subscriber/untag](https://developers.klicktipp.com/management-api/contact-tagging/api.subscriber.untag.md): Removes a tag from a contact.

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

### List Data Fields

 - [GET /field](https://developers.klicktipp.com/management-api/data-fields/api.customfield.index.md): Lists the IDs and names of all data fields.

Notice: data field IDs in this endpoint are prefixed with field.

### Get Data Field

 - [GET /field/{fieldid}](https://developers.klicktipp.com/management-api/data-fields/api.customfield.retrieve.md): Gets the ID and the name of a data field.

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

### List Opt-in Processes

 - [GET /list](https://developers.klicktipp.com/management-api/opt-in-processes/api.optin.index.md): Lists the IDs and names of all opt-in processes.

Notice: The Id without a name is the Default Double Opt-In present in each KlickTipp Account.

### Get Opt-in Process

 - [GET /list/{listid}](https://developers.klicktipp.com/management-api/opt-in-processes/api.optin.retrieve.md): Returns the complete data of an opt-in process.

### Search Redirect URL

 - [POST /list/redirect](https://developers.klicktipp.com/management-api/opt-in-processes/api.optin.redirect.md): Search the redirection URL for a specific opt-in process.

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

### List Tags

 - [GET /tag](https://developers.klicktipp.com/management-api/tags/api.tag.index.md): Lists the IDs and names of all tags.

### Create Tag

 - [POST /tag](https://developers.klicktipp.com/management-api/tags/api.tag.create.md): Creates a new manual tag.

### Get Tag

 - [GET /tag/{tagid}](https://developers.klicktipp.com/management-api/tags/api.tag.retrieve.md): Returns the name and description of a tag.

### Update Tag

 - [PUT /tag/{tagid}](https://developers.klicktipp.com/management-api/tags/api.tag.update.md): Updates a tag.

### Delete Tag

 - [DELETE /tag/{tagid}](https://developers.klicktipp.com/management-api/tags/api.tag.delete.md): Deletes a tag and removes it from all contacts.