# Add or Update Contact

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

Endpoint: POST /subscriber
Version: 1.0.0

## Request fields (application/json):

  - `email` (string,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"

  - `smsnumber` (string,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"

  - `listid` (integer,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

  - `tagid` (integer,null)
    Tag ID assigned to the contact.

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

  - `fields` (object,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: Hello World
    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":"+492201234567","fieldWebsite":"https://www.klicktipp.example","fieldBirthday":"755222400","fieldLeadValue":"100","field12345":"Custom Field Value"}

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique internal identifier of the contact
    Example: "987654321"

  - `email` (string, required)
    Primary email address of the contact
    Example: "alex.example@klicktipp.example"

  - `status` (string, required)
    Current email subscription status of the contact (state, legacy string value)
    Example: "Subscribed"

  - `bounce` (string, required)
    Bounce status of the contact email address (state, legacy string value)
    Example: "Not Bounced"

  - `listid` (string, required)
    ID of the opt-in process (list) the contact belongs to at the time of subscription
    Example: "12345"

  - `optin` (string, required)
    Time when the opt-in process for email communication was initiated (legacy formatted datetime string)
    Example: "01.01.2025 12:00:00"

  - `optin_ip` (string, required)
    IP address associated with initiating the opt-in process for email communication. Legacy behavior: For API-based subscriptions, this field may contain additional descriptive text and does not represent a pure IP address.
    Example: "0.0.0.0"

  - `date` (string, required)
    Time when the opt-in process for email communication was successfully confirmed (legacy formatted datetime string)
    Example: "01.01.2025 13:00:00"

  - `ip` (string, required)
    IP address associated with confirming the opt-in process for email communication. Legacy behavior: For API-based subscriptions, this field may contain additional descriptive text and does not represent a pure IP address.
    Example: "0.0.0.0"

  - `unsubscription` (string, required)
    Time when the contact unsubscribed from email communication (legacy formatted datetime string). Empty if the contact is subscribed.

  - `unsubscription_ip` (string, required)
    IP address associated with the unsubscription from email communication. Legacy behavior: For API-based unsubscriptions, this field may contain additional descriptive text. Empty if the contact is subscribed.

  - `referrer` (string, required)
    Optional referrer indicating the website where the email subscription form was embedded at the time of opt-in initiation. Legacy best-effort field and often empty.
    Example: "https://integration.example.com/webhooks/payment/ipn"

  - `sms_phone` (string, required)
    Phone number used for SMS communication
    Example: "00491701234567"

  - `sms_status` (string, required)
    Current SMS subscription status of the phone number (state, legacy string value)
    Example: "Subscribed"

  - `sms_bounce` (string, required)
    SMS bounce status of the phone number (state, legacy string value)
    Example: "Not Bounced"

  - `sms_date` (string, required)
    Time when the SMS subscription became active (legacy formatted datetime string)
    Example: "01.02.2025 12:00:00"

  - `sms_unsubscription` (string, required)
    Time when the contact unsubscribed from SMS communication (legacy formatted datetime string). Empty if subscribed.

  - `sms_referrer` (string, required)
    Optional referrer indicating the website where the SMS subscription form was embedded at the time of opt-in initiation. Legacy best-effort field and often empty.
    Example: "https://signup.example.com/sms-form"

  - `fieldFirstName` (string, required)
    Global data field: first name of the contact
    Example: "Alex"

  - `fieldLastName` (string, required)
    Global data field: last name of the contact
    Example: "Example"

  - `fieldCompanyName` (string, required)
    Global data field: company name of the contact
    Example: "Example Corp"

  - `fieldStreet1` (string, required)
    Global data field: primary street address
    Example: "Example Street 1"

  - `fieldStreet2` (string, required)
    Global data field: additional address information

  - `fieldCity` (string, required)
    Global data field: city
    Example: "Berlin"

  - `fieldState` (string, required)
    Global data field: state or region
    Example: "Berlin"

  - `fieldZip` (string, required)
    Global data field: postal or ZIP code
    Example: "10115"

  - `fieldCountry` (string, required)
    Global data field: country code
    Example: "DE"

  - `fieldPrivatePhone` (string, required)
    Global data field: private phone number
    Example: "00491701234567"

  - `fieldMobilePhone` (string, required)
    Global data field: mobile phone number
    Example: "00491707654321"

  - `fieldPhone` (string, required)
    Global data field: business phone number
    Example: "00492207654321"

  - `fieldFax` (string, required)
    Global data field: fax number
    Example: "00492201234567"

  - `fieldWebsite` (string, required)
    Global data field: website URL
    Example: "https://www.klicktipp.example"

  - `fieldBirthday` (string, required)
    Global data field: birthday stored as Unix timestamp (seconds)
    Example: "755222400"

  - `fieldLeadValue` (string, required)
    Global data field: lead score or lead value
    Example: "100"

  - `tags` (array, required)
    List of all tag IDs currently assigned to the contact, including manual and smart tags
    Example: ["17","18","19","20"]

  - `smart_tags` (object, required)
    Smart tag IDs mapped to the Unix timestamp when they were applied (subset of assigned tags)
    Example: {"17":"1758821945","18":"1758822131"}

  - `manual_tags` (object, required)
    Manually assigned tag IDs mapped to the Unix timestamp when they were applied (subset of assigned tags)
    Example: {"19":"1759753677","20":"1758822131"}

  - `notification_emails_sent` (object, required)
    Notification email IDs mapped to the Unix timestamp when they were sent
    Example: {"45":"1758821945"}

  - `notification_emails_opened` (object, required)
    Notification email IDs mapped to the Unix timestamp when they were opened
    Example: {"45":"1758822131"}

  - `notification_emails_clicked` (object, required)
    Notification email IDs mapped to the Unix timestamp when they were clicked
    Example: {"45":"1758822131"}

  - `emails_sent` (object, required)
    Email IDs mapped to the Unix timestamp when they were sent
    Example: {"1":"1758822606","2":"1758822769"}

  - `emails_opened` (object, required)
    Email IDs mapped to the Unix timestamp when they were opened
    Example: {"1":"1758822610","2":"1758884682"}

  - `emails_clicked` (object, required)
    Email IDs mapped to the Unix timestamp when they were clicked
    Example: {"1":"1758822733"}

  - `campaigns_started` (object, required)
    Campaign IDs mapped to the Unix timestamp when they were started
    Example: {"6":"1759753673"}

  - `campaigns_finished` (object, required)
    Campaign IDs mapped to the Unix timestamp when they were finished
    Example: {"6":"1759753677"}