openapi: 3.0.0
info:
  title: KlickTipp Listbuilding API
  description: >-
    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:
  - url: https://api.klicktipp.com
    description: KlickTipp REST API
paths:
  /subscriber/signin:
    post:
      tags:
        - Listbuilding via API Key
      summary: Signin
      description: >-
        Creates or updates a contact and associates the tag linked to the API
        key.
      operationId: api.subscriber.signin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriberCreateWithApikeySchema'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SubscriberCreateWithApikeySchema'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SubscriberCreateWithApikeySchema'
      responses:
        '200':
          description: Success Response.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
                - https://klick.example.com/pending/1z3z6zzpz7b76
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '406':
          $ref: '#/components/responses/NotAcceptableResponse'
  /subscriber/signoff:
    post:
      tags:
        - Listbuilding via API Key
      summary: Signoff
      description: >-
        Unsubscribes a contact via the API key and prevents further
        communication.
      operationId: api.subscriber.signoff
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriberUnsubscribeWithApikeySchema'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SubscriberUnsubscribeWithApikeySchema'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SubscriberUnsubscribeWithApikeySchema'
      responses:
        '200':
          $ref: '#/components/responses/SuccessBooleanResponse'
        '406':
          $ref: '#/components/responses/NotAcceptableResponse'
  /subscriber/signout:
    post:
      tags:
        - Listbuilding via API Key
      summary: Signout
      description: Removes the tag of a contact associated with the API key.
      operationId: api.subscriber.signout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriberUnsubscribeWithApikeySchema'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SubscriberUnsubscribeWithApikeySchema'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SubscriberUnsubscribeWithApikeySchema'
      responses:
        '200':
          $ref: '#/components/responses/SuccessBooleanResponse'
        '406':
          $ref: '#/components/responses/NotAcceptableResponse'
components:
  schemas:
    SubscriberCreateWithApikeySchema:
      required:
        - apikey
      properties:
        apikey:
          description: API key
          type: string
          example: '{{api_key}}'
        email:
          description: |-
            Valid email address and must contain `@`.

            Either `email` or `smsnumber` is required.
            Email address must be unique per contact.
          type: string
          example: alex.example@klicktipp.example
          nullable: true
        smsnumber:
          description: |-
            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`
          type: string
          example: '+491701234567'
          nullable: true
        fields:
          description: >-
            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>`
          type: object
          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
          nullable: true
          additionalProperties:
            type: string
      type: object
    SubscriberUnsubscribeWithApikeySchema:
      required:
        - apikey
        - email
      properties:
        apikey:
          description: API key
          type: string
          example: '{{api_key}}'
        email:
          description: Email address of the subscriber
          type: string
          example: alex.example@klicktipp.example
      type: object
  responses:
    SuccessBooleanResponse:
      description: Success Response (200).
      content:
        application/json:
          schema:
            type: array
            items:
              type: boolean
            example:
              - true
    BadRequestResponse:
      description: |
        Bad Request Response (400).

        Check your request for malformed or missing parameters.
      content:
        application/json:
          schema:
            type: array
            items:
              type: string
          example:
            - The key "username" must be a string.
    UnauthorizedResponse:
      description: |
        Unauthorized Response (401).

        Check username and password, or possibly other required parameters.
      content:
        application/json:
          schema:
            type: array
            items:
              type: string
          example:
            - Wrong username or password.
    AccessDeniedResponse:
      description: >
        Access Denied Response (403).


        Your account does not have the required permissions to access this
        resource.
      content:
        application/json:
          schema:
            type: array
            items:
              type: string
          example:
            - API access denied.
    NotFoundResponse:
      description: |
        Not Found Response (404).

        The specified resource could not be found.
      content:
        application/json:
          schema:
            type: array
            items:
              type: string
          example:
            - There is no such entity.
    NotAcceptableResponse:
      description: |
        Not Acceptable Response (406).

        Check the response content for further error details.

        In some cases, a detail error code may be returned:

        - `4` - Subscription not found
        - `5` - Email address validation failed
        - `7` - Subscriber email not found
        - `8` - Field validation failed
        - `9` - Subscriber not subscribed
        - `10` - Subscriber update failed
        - `30` - Email address change not allowed
        - `31` - Untag smarttag not allowed
        - `32` - Email address SMS number required
        - `100` - Invalid API key
        - `401` - User not found
        - `402` - List not found
        - `403` - Tag not found
        - `404` - User group not found
        - `405` - Campaign not found
        - `406` - Tier not found
        - `501` - Email address required
        - `502` - Username required
        - `503` - Password required
        - `504` - First name required
        - `505` - Last name required
        - `506` - Username exists
        - `507` - Email address exists
        - `508` - User update failed
      content:
        application/json:
          schema:
            oneOf:
              - type: object
              - type: array
                items:
                  type: string
          example:
            error: 507
tags:
  - name: Listbuilding via API Key
    description: >-
      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.
