# CRM Integration

This guide is aimed at integrators who want to connect CRM systems such as HubSpot, Close, Zoho, or another sales platform with KlickTipp.

CRM integrations are commonly used to synchronize contacts, lifecycle stages, segments, consent-related information, and deletion requests so that KlickTipp can run targeted email marketing and automation workflows.

## Sync CRM Contacts

The contact sync step is the central entry point for CRM integrations. It creates new contacts in KlickTipp, updates existing contacts, and keeps CRM fields useful for segmentation and automation.

Use the Management API as the default model for CRM integrations. CRM flows usually require dynamic field mapping, segment-to-tag mapping, stable ID storage, and support for email address changes.

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

| Action | Description |
|  --- | --- |
| [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. |
| [Update Contact](/management-api#operation/api.subscriber.update) | Updates an existing contact by Contact ID. Use this when the CRM email address changes. |
| [Search Contact ID](/management-api#operation/api.subscriber.search) | Returns the KlickTipp Contact ID for an email address. |
| [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 a CRM contact event from a CRM webhook, scheduled sync, or another event source. For event-driven outbound flows from KlickTipp, see [Webhooks & Event Subscriptions](/guides/webhoooks-and-events).
2. Apply optional filters, such as lead status, lifecycle stage, owner, or list membership.
3. 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).
4. Create missing CRM segment tags with [Create Tag](/management-api#operation/api.tag.create) if the integration should manage tags dynamically.
5. Identify the contact by stored KlickTipp Contact ID, stored CRM Contact ID, or email address.
6. For new contacts or normal email-based updates, use [Add or Update Contact](/management-api#operation/api.subscriber.create).
7. For CRM updates where the email address changed, update the existing KlickTipp contact by Contact ID with [Update Contact](/management-api#operation/api.subscriber.update).
8. Store the CRM Contact ID in a KlickTipp data field and store the KlickTipp Contact ID in the CRM.
9. Map CRM fields to KlickTipp fields.
10. Add current CRM segment tags with [Tag Contact](/management-api#operation/api.subscriber.tag).
11. Remove CRM segment tags that no longer apply with [Untag Contact](/management-api#operation/api.subscriber.untag).
12. Display the current KlickTipp subscription status in the CRM if needed.


### Add or Update Contact

The Add or Update Contact function is the recommended entry point for creating contacts from CRM data and for email-based contact updates.

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

### Update Contact

The Update Contact function updates an existing contact by KlickTipp Contact ID. Use it when the CRM changes the email address and your integration already knows the matching KlickTipp Contact ID.

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

#### Data Field Types and Input Formats

When syncing CRM data, all submitted field values must match the field types and field keys configured in the KlickTipp account.

Typical CRM mappings include CRM Contact ID, company, phone number, lifecycle stage, lead status, owner, segment, and the displayed KlickTipp subscription status.

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

CRM integrations should handle long-running data changes explicitly, especially email address changes, deleted tags, outdated field mappings, and unsubscribed contacts.

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

## Start CRM Campaigns for Contacts

Tags connect CRM segmentation with KlickTipp automations. They can represent lifecycle stages, lead statuses, CRM lists, CRM tags, product interest, or other segment data.

| 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:

- `[CRM]`
- `[CRM] [Lifecycle Stage]`
- `[CRM] [Lead Status]`
- `[CRM] [List]`
- `[CRM] [Segment]`


When a CRM segment changes, remove tags that no longer apply and add the current tags.

## Manage CRM Segmentation

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

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

**Recommendation**

- Use a stable prefix such as `[CRM]` for integration-managed tags.
- Use dynamic tags for lifecycle stages, lists, CRM tags, or custom CRM segments.
- 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 initial CRM synchronization, the email address can be used to find or create the KlickTipp contact.

For long-running CRM integrations, store stable IDs in both systems: the CRM Contact ID in KlickTipp and the KlickTipp Contact ID in the CRM. This prevents duplicate contacts and allows the integration to keep mapping contacts even when the email address changes.

Subscribe, tag, and untag actions use the email address as the unique identifier. For CRM contact updates where the email address itself changes, use [Update Contact](/management-api#operation/api.subscriber.update) with the KlickTipp Contact ID.

Repeated [Tag Contact](/management-api#operation/api.subscriber.tag) and [Untag Contact](/management-api#operation/api.subscriber.untag) calls should be treated as idempotent from the integration perspective. The integration should track the current CRM segment state and apply the final desired KlickTipp tag state.

## KlickTipp to CRM Events

CRM integrations often need to show KlickTipp status or events inside the CRM. KlickTipp should remain the leading system for email subscription status.

Use [Webhooks & Event Subscriptions](/guides/webhoooks-and-events) for event-driven flows such as contact updates or deletion requests. Batch or polling sync can be used for initial imports and periodic reconciliation.

| Action | Description |
|  --- | --- |
| [Webhooks & Event Subscriptions](/guides/webhoooks-and-events) | Explains how to send contact data or deletion requests from KlickTipp to external systems. |
| [Unsubscribe Contact](/management-api#operation/api.subscriber.unsubscribe) | Unsubscribes a contact, preventing further communication. |


## Essential API Functions

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

| Action | Description |
|  --- | --- |
| [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. |
| [Update Contact](/management-api#operation/api.subscriber.update) | Updates an existing contact by Contact ID. |
| [Search Contact ID](/management-api#operation/api.subscriber.search) | Returns the contact ID for an email address. |
| [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. |
| [Unsubscribe Contact](/management-api#operation/api.subscriber.unsubscribe) | Unsubscribes a contact, preventing further communication. |
| [Create Tag](/management-api#operation/api.tag.create) | Creates a new manual tag. |
| [Webhooks & Event Subscriptions](/guides/webhoooks-and-events) | Describes event-driven outbound sync and deletion request flows. |


## Best Practices

Good CRM integrations keep contact identity, subscription state, and segmentation predictable across both systems.

- **Use the Management API as the default model**: CRM integrations usually need dynamic fields, tags, stable IDs, and update logic.
- **Store stable IDs in both systems**: Store the CRM Contact ID in KlickTipp and the KlickTipp Contact ID in the CRM.
- **Keep KlickTipp authoritative for email subscription status**: The CRM can display subscription status, but it should not overwrite it without a clear opt-in or unsubscribe flow.
- **Use Contact ID for email address changes**: If the CRM email address changes, update the existing KlickTipp contact via Contact ID instead of creating a new contact.
- **Apply the final segment state**: Remove old CRM segment tags and add the current tags so automations match the CRM state.
- **Handle deletion requests deliberately**: Define whether deletion requests should remove CRM data, anonymize CRM data, or create a manual review task.


## Summary

CRM integrations connect sales and customer data with KlickTipp marketing automation.

Use the Management API as the default model. Store stable IDs in both systems, map fields explicitly, represent CRM segments as KlickTipp tags, and keep KlickTipp as the leading system for email subscription status.

Reliable CRM integrations handle email address changes, subscription status, deletion requests, and segment changes without creating inconsistent contact states.