# Form Integration

This guide is aimed at integrators who want to connect form tools such as Jotform, Gravity Forms, Typeform, Facebook Lead Ads, or custom form backends with KlickTipp.

Form integrations are commonly used to create or update contacts, transfer submitted form data, assign source tags, and start follow-up automations for lead magnets, quizzes, surveys, webinar registrations, or event signups.

## Submit Form Contacts

The contact subscription step is the central entry point for form integrations. It creates a new contact in KlickTipp or updates an existing one when the same email address is submitted again.

For simple forms with one fixed opt-in process and one fixed tag, use the Listbuilding API. For configurable integrations with dynamic opt-in selection, dynamic tags, custom field mapping, or advanced validation, use the Management API.

Before creating or updating a contact with the Management API, load the required reference data from KlickTipp. This ensures that your integration uses valid opt-in process IDs, tag IDs, and field keys.

| Action | Description |
|  --- | --- |
| [Listbuilding Signin](/listbuilding-api#operation/api.subscriber.signin) | Subscribes a contact through a fixed Listbuilding API key. Use this for simple form flows. |
| [Add or Update Contact](/management-api#operation/api.subscriber.create) | Adds a new contact. If a contact with the same email already exists, it will be updated. |
| [List Opt-in Processes](/management-api#operation/api.optin.index) | Lists the IDs and names of all opt-in processes. |
| [List Tags](/management-api#operation/api.tag.index) | Lists the IDs and names of all tags. |
| [List Data Fields](/management-api#operation/api.customfield.index) | Lists the IDs and names of all data fields. |


### Step-By-Step Integration Flow

1. Receive the form submission in your backend, webhook, or automation tool.
2. Validate that the submission contains a valid email address.
3. For fixed API-key flows, call [Listbuilding Signin](/listbuilding-api#operation/api.subscriber.signin).
4. For configurable flows, load setup data with [List Opt-in Processes](/management-api#operation/api.optin.index), [List Tags](/management-api#operation/api.tag.index), and [List Data Fields](/management-api#operation/api.customfield.index).
5. Map submitted fields to KlickTipp fields.
6. Create or update the contact with [Add or Update Contact](/management-api#operation/api.subscriber.create).
7. Assign source, form, campaign, or answer tags with [Tag Contact](/management-api#operation/api.subscriber.tag).
8. Handle validation and subscription errors with the [Error Handling and Validation](/guides/error-handling) guide.


### Add or Update Contact

The Add or Update Contact function is the recommended Management API action for configurable form integrations. It assumes that a contact is submitted via a form. If the contact already exists, it will be updated.

[View full API reference](/management-api#operation/api.subscriber.create)

#### Data Field Types and Input Formats

When creating or updating contacts via the Management API, all submitted field values must match the field types and field keys configured in the KlickTipp account.

Field metadata and field types should be retrieved before submitting contact data.

For a complete overview of supported field types, required formats, and common pitfalls, see:
[Data Field Types and Input Formats](/guides/data-field-types)

#### Error Handling

KlickTipp can return business-level validation and subscription errors, typically using HTTP status code 406.

These errors should not be retried blindly. Correct the submitted data or configuration first.

For a complete explanation of the error model, validation errors, and subscription-related error codes, see:
[Error Handling and Validation](/guides/error-handling)

## Start Form Follow-Up Campaigns

Tags are the main trigger for form follow-up automations in KlickTipp. They can identify the form source, selected interests, quiz answers, lead magnets, events, or webinar registrations.

| Action | Description |
|  --- | --- |
| [Tag Contact](/management-api#operation/api.subscriber.tag) | Adds one or more tags to a contact. |
| [Untag Contact](/management-api#operation/api.subscriber.untag) | Removes a tag from a contact. |


Recommended tag patterns:

- `[Tool] [Form]`
- `[Tool] [Form] [Answer]`
- `[Campaign] [Lead Magnet]`
- `[Event] Registered`


Use static tags for stable flows and dynamic tags when each form, quiz, or campaign needs its own automation path.

## Manage Segmentation for Forms

So that users do not have to manually create tags in KlickTipp, your integration can manage tags through the API.

[View full API reference](/management-api#operation/api.tag.create)

**Recommendation**

- Use fixed source tags for each form tool or form type.
- Use dynamic tags for form names, campaigns, quizzes, or selected answers.
- Provide dropdowns for existing tags and an optional "Create Tag" action.


| Action | Description |
|  --- | --- |
| [Create Tag](/management-api#operation/api.tag.create) | Creates a new manual tag. |
| [List Tags](/management-api#operation/api.tag.index) | Lists the IDs and names of all tags. |


## Contact Mapping and Idempotency

For form integrations, the email address is the unique identifier for subscription, update, tag, and untag actions.

Repeated [Add or Update Contact](/management-api#operation/api.subscriber.create) calls with the same email address should update the existing contact instead of creating duplicates.

Repeated [Tag Contact](/management-api#operation/api.subscriber.tag) or [Untag Contact](/management-api#operation/api.subscriber.untag) calls should be treated as idempotent from the integration perspective. The integration can safely retry these actions after transient failures, but it should not create duplicate business events in the connected form system.

## Essential API Functions

Here you will find the essential calls that you need for robust form integrations.

| Action | Description |
|  --- | --- |
| [Listbuilding Signin](/listbuilding-api#operation/api.subscriber.signin) | Subscribes a contact through a fixed Listbuilding API key. |
| [Add or Update Contact](/management-api#operation/api.subscriber.create) | Adds a new contact. If a contact with the same email already exists, it will be updated. |
| [List Opt-in Processes](/management-api#operation/api.optin.index) | Lists the IDs and names of all opt-in processes. |
| [List Tags](/management-api#operation/api.tag.index) | Lists the IDs and names of all tags. |
| [List Data Fields](/management-api#operation/api.customfield.index) | Lists the IDs and names of all data fields. |
| [Tag Contact](/management-api#operation/api.subscriber.tag) | Adds one or more tags to a contact. |
| [Untag Contact](/management-api#operation/api.subscriber.untag) | Removes a tag from a contact. |
| [Create Tag](/management-api#operation/api.tag.create) | Creates a new manual tag. |


## Best Practices

Good form integrations are reliable, configurable, and clear for the user who owns the form flow.

- **Use the Listbuilding API for fixed forms**: If the form always uses one API key, one opt-in process, and one tag, the Listbuilding API is usually the fastest model.
- **Use the Management API for configurable apps**: Load opt-in processes, tags, and fields dynamically when users can configure mappings.
- **Validate field formats before sending data**: Dates, numbers, URLs, and custom fields must match the configured KlickTipp field types.
- **Use clear source tags**: Make it easy to identify which form, campaign, or lead magnet created the contact.
- **Show actionable errors**: For validation or subscription errors, show the reason in the integration UI instead of silently retrying.


## Summary

Form integrations move external lead data into KlickTipp and start automated follow-up campaigns.

Use the Listbuilding API for fixed, simple form flows. Use the Management API when the integration needs dynamic opt-in selection, dynamic tags, configurable field mapping, or tag management.

Reliable form integrations validate submitted data, map fields explicitly, assign clear source tags, and handle subscription errors in a predictable way.