Integration Summary # Choosing Between the Listbuilding API and the Management API This guide explains when to use the **Listbuilding API** and when to use the **Management API**. The short version is: - Use the **Listbuilding API** for a **fixed opt-in flow** tied to a specific list-building process. - Use the **Management API** for **event-driven integrations** that need to read or change contacts, tags, fields, or opt-in process data in a more flexible way. ## Decision Tree ```text Do you want to send a contact into one predefined opt-in flow? | +-- Yes | | | +-- Is the integration centered around an API key that belongs to that | list-building process? | | | +-- Yes -> Use the Listbuilding API | +-- No -> Re-check your design. A fixed opt-in flow usually belongs in | the Listbuilding API. | +-- No | +-- Do you need to react to business events or manage contact data dynamically? | +-- Yes -> Use the Management API +-- No -> If your only job is still a predefined opt-in path, use the Listbuilding API ``` ## Use the Listbuilding API When Choose the **Listbuilding API** if your integration is essentially a controlled signup flow. Typical fit: - A website form sends leads into one predefined opt-in process - A funnel tool pushes contacts into one fixed subscription flow - An integration only needs API-key-based `signin`, `signout`, or `signoff` - The business logic is intentionally limited to a specific acquisition path Key characteristics: - Authentication is based on an **API key** - The API key is linked to a **list-building process** - The flow is **predefined**, not dynamically assembled at runtime - It is well suited for simple external lead capture scenarios Relevant endpoints: - `POST /subscriber/signin.json` - `POST /subscriber/signout.json` - `POST /subscriber/signoff.json` What this means in practice: - `signin` is the entry point for sending a contact into the fixed opt-in flow - `signout` removes a tag in the API-key-driven flow - `signoff` unsubscribes a contact in the API-key-driven flow ## Use the Management API When Choose the **Management API** if your integration is driven by events, decisions, or ongoing data synchronization. Typical fit: - A workflow reacts to purchases, webinar attendance, CRM changes, or support events - You need to create, update, search, tag, untag, or unsubscribe contacts dynamically - You need to inspect tags, fields, contacts, or opt-in processes before deciding what to do - You are building an iPaaS, SaaS, MCP, automation, or backend integration with flexible runtime behavior Key characteristics: - Designed for **event-driven flows** - Supports broader contact and metadata management - Works for integrations that need to **read first, then decide** - Better fit when logic is based on conditions, branching, or multiple KlickTipp objects Relevant endpoint groups: - Contacts: - `GET /subscriber.json` - `POST /subscriber.json` - `GET /subscriber/{subscriberid}.json` - `PUT /subscriber/{subscriberid}.json` - `DELETE /subscriber/{subscriberid}.json` - `POST /subscriber/search.json` - `POST /subscriber/tagged.json` - `POST /subscriber/unsubscribe.json` - Contact tagging: - `POST /subscriber/tag.json` - `POST /subscriber/untag.json` - Data fields: - `GET /field.json` - Opt-in processes: - `GET /list.json` - `GET /list/{listid}.json` - `POST /list/redirect.json` - Tags: - `GET /tag.json` - `POST /tag.json` - `GET /tag/{tagid}.json` - `PUT /tag/{tagid}.json` - `DELETE /tag/{tagid}.json` ## Side-by-Side Comparison | Question | Listbuilding API | Management API | | --- | --- | --- | | Main purpose | Fixed opt-in flow | Event-driven contact and metadata management | | Best for | Forms, funnels, simple lead capture | Automations, sync jobs, backend logic, iPaaS, AI and MCP tools | | Authentication style | API key | Session auth or partner auth, depending on integration mode | | Runtime flexibility | Low | High | | Reads existing KlickTipp data before acting | Usually no | Yes | | Works well for branching logic | No | Yes | | Contact management beyond one intake flow | Limited | Yes | ## Do Not Use the Listbuilding API When Do **not** use the **Listbuilding API** if: - You need to decide at runtime which tags, fields, or actions to apply - You need to look up existing contacts before acting - You need to manage tags or fields outside the fixed opt-in flow - You need a general-purpose integration for Make, Zapier, n8n, MCP, or custom backend services - You need to support multiple business events such as purchase, cancellation, enrichment, or support-state changes In these cases, use the **Management API** instead. ## Do Not Use the Management API When Do **not** use the **Management API** if: - Your only goal is to send a lead into one predefined list-building flow - You intentionally want a narrow API-key-based signup integration - Your integration is basically a form submission with a fixed opt-in path and no broader contact-management logic In these cases, the **Listbuilding API** is usually the cleaner choice. ## Practical Examples ### Example 1: Newsletter signup form Scenario: A landing page form should send a contact into one predefined double opt-in process. Recommendation: Use the **Listbuilding API**. Why: The flow is fixed, API-key-based, and focused on lead capture. ### Example 2: Purchase automation Scenario: After a payment, the integration should find the contact, update fields, add tags, and maybe trigger a different follow-up path depending on product or amount. Recommendation: Use the **Management API**. Why: This is event-driven logic with branching and dynamic contact management. ### Example 3: CRM sync Scenario: A CRM pushes updates into KlickTipp whenever account data changes. Recommendation: Use the **Management API**. Why: This is not a fixed opt-in flow. It is ongoing synchronization and contact management. ### Example 4: Lead magnet form inside a funnel builder Scenario: A simple external tool should register a lead for one specific opt-in process. Recommendation: Use the **Listbuilding API**. Why: The integration only needs the predefined signup path. ## Recommended Rule of Thumb Use this simple rule: - If the integration starts with **"put this lead into this predefined opt-in flow"**, use the **Listbuilding API**. - If the integration starts with **"when this event happens, inspect data and decide what to do"**, use the **Management API**. ## Related Notes - The Listbuilding API centers on the API-key functions `signin`, `signout`, and `signoff`. - The Management API covers the broader operational surface for contacts, tags, fields, and opt-in-process inspection. - If an integration may grow from a simple signup flow into broader event-driven automation, it is usually better to plan around the **Management API** from the start.