Integration Summary

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

## Choose the Integration Model

The right API depends on whether the form flow is fixed or configurable.

Use the **Listbuilding API** when one form always uses one fixed opt-in process and one fixed follow-up path.

Typical examples:

- A simple Google Forms or Jotform signup form that always sends contacts into one newsletter flow
- A fixed lead-magnet form with one predefined source tag
- A landing-page form that only needs one opt-in process and one stable mapping


Use the **Management API** when the integration must load configuration first, map fields dynamically, create or resolve tags, or choose different automations depending on the form submission.

Typical examples:

- A Typeform quiz that maps answer values into custom fields and segmentation tags
- A Gravity Forms workflow that stores ratings, dates, session selections, or feedback values
- A Jotform integration that routes contacts by form name, selected offer, campaign, or answer set
- A Facebook Lead Ads integration that routes leads by form, campaign, or ad set
- A reusable form connector where the account owner chooses the opt-in process, tags, and field mappings in your app


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

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 and tag IDs, and that your own mapping layer uses the correct KlickTipp 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 and the required form fields.
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. Resolve the configured opt-in process, tag strategy, and field mapping for the specific form.
6. Normalize the submitted values into KlickTipp-compatible formats before sending them.
7. Create or update the contact with [Add or Update Contact](/management-api#operation/api.subscriber.create).
8. Assign source, form, campaign, quiz, webinar, or answer tags with [Tag Contact](/management-api#operation/api.subscriber.tag).
9. Optionally remove obsolete tags with [Untag Contact](/management-api#operation/api.subscriber.untag) when your form logic changes contact state.
10. 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.

Your integration should therefore load the available field list, store the selected KlickTipp field keys in its own configuration, and validate input values against the expected KlickTipp field type before submission.

Do not assume that a form tool's native data types automatically match KlickTipp input formats. This matters especially for:

- date and date-time fields from Google Forms, Typeform, Gravity Forms, or Jotform
- lead-source and campaign metadata from Facebook Lead Ads
- multiple-choice or quiz-answer fields that must be converted into plain string values
- numeric or score fields that must be validated before sending
- phone numbers that should be normalized into a safe format for contact updates


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)

## Tool Patterns

The overall integration model is the same across form tools, but the submitted data often differs by platform.

### Google Forms

Google Forms integrations usually submit a row-like response with stable question labels. This makes them a good fit for fixed or semi-configurable form flows.

Typical pattern:

- capture the new Google Forms submission
- map the email address and basic contact fields
- choose one opt-in process for the form
- apply one source tag such as `[Google Forms] [Lead]`
- optionally join multiple selected answers into one text value before storing them in KlickTipp


### Typeform

Typeform is especially common for quizzes, surveys, and branching forms. These integrations usually need the Management API because answers often drive tagging and custom field mapping.

Typical pattern:

- capture the Typeform submission and quiz answers
- normalize phone numbers, dates, and numeric values
- map multiple-choice answers into string values or tags
- create or update the contact
- apply both fixed source tags and dynamic answer tags


### Gravity Forms

Gravity Forms often appears in WordPress-based feedback, webinar, and event-registration flows. These forms commonly include structured values such as ratings, preferred sessions, permissions, and dates.

Typical pattern:

- receive the Gravity Forms submission through a webhook or integration layer
- normalize structured values such as dates, ratings, and session choices
- map the fields into KlickTipp contact fields
- create or update the contact
- tag the contact according to form purpose, selected topic, or follow-up state


### Jotform

Jotform is commonly used for lead capture, event registration, and campaign-specific landing pages. In practice, Jotform integrations often need configurable mappings because individual forms can vary widely.

Typical pattern:

- capture the Jotform submission
- resolve the configured mapping for that specific form
- map contact fields and any custom answers
- create or update the contact
- apply a stable source tag and optional campaign or answer tags


### Facebook Lead Ads

Facebook Lead Ads integrations usually receive lead data together with campaign context such as page, campaign, ad set, or form identifiers. These integrations often benefit from the Management API because account owners commonly want source-aware tagging and reusable mappings.

Typical pattern:

- capture the new lead from Facebook Lead Ads
- map the email address, name, phone number, and any selected answers
- resolve the configured opt-in process and field mapping for the specific lead form
- create or update the contact
- apply source tags for the platform, form, campaign, or ad set


## Reference Data and Mapping Strategy

For configurable form integrations, load reference data before sending Management API submissions.

Recommended preparation flow:

1. Load available opt-in processes with [List Opt-in Processes](/management-api#operation/api.optin.index).
2. Load existing tags with [List Tags](/management-api#operation/api.tag.index).
3. Load available data fields with [List Data Fields](/management-api#operation/api.customfield.index).
4. Let the account owner choose the mappings in your app or integration setup.
5. Store the selected KlickTipp IDs and field keys in your integration configuration.
6. Reuse that saved mapping during form submission processing.


If your integration allows dynamic tagging, use dropdowns for existing tags and optionally offer [Create Tag](/management-api#operation/api.tag.create) when the workflow needs to create a missing tag during setup or runtime.

## 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 manage every tag manually in KlickTipp, your integration can resolve and optionally create 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.

Recommended business keys:

- contact identity by email address
- form identity by form ID, form name, or landing-page source
- submission identity by provider submission ID when available


If the form platform provides a stable submission ID, store it in your processing layer so you can detect accidental duplicate deliveries.

## 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.
- **Treat field mapping as configuration**: Save the selected KlickTipp field keys and validate provider values before every submission.
- **Validate field formats before sending data**: Dates, numbers, URLs, and custom fields must match the configured KlickTipp field types.
- **Normalize provider-specific values**: Convert dates, times, quiz answers, and phone numbers into KlickTipp-compatible formats before calling the API.
- **Use clear source tags**: Make it easy to identify which form, campaign, or lead magnet created the contact.
- **Prefer existing tags, but allow optional tag creation**: This is especially useful for reusable integrations where form names, quiz paths, or campaign tags vary by account.
- **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. This applies equally to Google Forms, Typeform, Gravity Forms, Jotform, Facebook Lead Ads, and similar form tools.