Kunden

Endpoints für die Verwaltung von Kunden — Anlegen, Lesen, Aktualisieren und Löschen — plus alle direkt am Kunden hängenden Unterressourcen (Adressen, Bankverbindungen, Verträge, Schäden, Dokumente …).

Zuletzt geprüft: 12. Mai 2026

Übersicht

Ein Customer ist der zentrale Datensatz für eine Person oder Firma in i-Planner — intern als Kontakt im Bereich „Privatkunden" geführt. Alle weiteren CRM-Objekte (Verträge, Schäden, Aktivitäten, Dokumente, Finanzen …) hängen direkt oder indirekt am Customer.

Das Customer-Schema ist organisationsspezifisch konfigurierbar: Welche Felder dein Tenant für einen Kunden pflegt, definiert die Form-Konfiguration in den Account-Einstellungen. Die API liefert auf Wunsch (with_schema=true) das aktuelle Feld-Schema deiner Organisation mit zurück, damit Integratoren keine Felder hart verdrahten müssen, die ggf. nicht existieren.

Scopes

Jede Ressource-Familie hat ihren eigenen Scope nach dem Schema v3:<resource>:<action>. Der URL-Pfad spielt für die Berechtigung keine Rolle — entscheidend ist, welche Daten angefasst werden.

Customer-Stammdaten (Name, Anrede, Geburtsdatum, Kommentar etc.):

v3:customers:read — GET /v3/customers, GET /v3/customers/<id>
v3:customers:write — POST /v3/customers, PATCH /v3/customers/<id>, DELETE /v3/customers/<id>

Unterressourcen teilen sich entweder den Customer-Scope (direkt am Customer-Datensatz) oder haben eine eigene Scope-Familie (eigenständige Daten-Domäne):

Unterressource	Scope	Domäne
Addresses	`v3:customers:read · v3:customers:write`	direkt am Customer
Contacts	`v3:customers:read · v3:customers:write`	direkt am Customer
Banking	`v3:customers:read · v3:customers:write`	direkt am Customer
Nummern	`v3:customers:read · v3:customers:write`	direkt am Customer
Identity	`v3:customers:read · v3:customers:write`	direkt am Customer
Jobs	`v3:customers:read · v3:customers:write`	direkt am Customer
Tags	`v3:customers:read · v3:customers:write`	direkt am Customer
Comments	`v3:customers:read · v3:customers:write`	direkt am Customer
Followers	`v3:customers:read · v3:customers:write`	direkt am Customer
Contracts	`v3:contracts:read · v3:contracts:write`	eigene Scope-Familie + globally-unique id
Damages	`v3:damages:read · v3:damages:write`	eigene Scope-Familie + globally-unique id
Finances	`v3:finances:read · v3:finances:write`	eigene Scope-Familie + globally-unique id
Goals	`v3:goals:read · v3:goals:write`	eigene Scope-Familie + globally-unique id
Documents	`v3:documents:read · v3:documents:write`	eigene Scope-Familie + globally-unique id

Praxisbeispiel — Geburtstags-Newsletter-Tool braucht:

v3:customers:read     ✓   (Name, Anrede, Geburtsdatum, E-Mail-Adresse)

Mehr nicht. Verträge, Schäden, Finanzen, Dokumente bleiben für dieses Tool unsichtbar — kein versehentlicher Daten-Leak möglich.

Wie die Authentifizierung über Bearer-Token grundsätzlich funktioniert und welche Fehler-Bodies bei fehlendem oder ungültigem Token kommen, siehe Authentication.

Pagination & Limits

Listen-Endpoints sind paginiert. Die Parameter:

page — 1-basierter Seitenindex. Default 1.
limit — Items pro Seite. Default 50, Hard-Cap 5000.

Verhalten bei ungültigen Werten: Die API klemmt ungültige Pagination-Parameter still auf einen sicheren Wert ab, statt mit 400 zu antworten — das hält Listing-Calls auch bei Tipp- oder Encoding-Fehlern stabil:

limit nicht-numerisch (abc), leer, 0, negativ → Default (50)
limit > 5000 → auf 5000 geklemmt
limit mit Dezimalstellen (1.5) → auf den Integer-Anteil geparst (1)
page nicht-numerisch, leer, 0, negativ → 1
page jenseits der letzten Seite → 200 mit items: []

Strikt validiert werden hingegen Pfad-Parameter (kid, id) und die meisten Body-Felder — siehe Errors.

Die Antwort enthält immer page, page_size, total und items. Es gibt keine Cursor-Pagination; Clients berechnen Folgeseiten anhand total / page_size.

Beispiel — Seite 2 mit 50 Items pro Seite:

bash

curl 'https://www.api.i-planner.app/v3/customers?page=2&limit=50' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

{
  "page": 2,
  "page_size": 50,
  "total": 4217,
  "items": [
    { "kid": 12395, "id": 67890, "vorname": "Anna",  "name": "Müller"   },
    { "kid": 12396, "id": 67891, "vorname": "Bernd", "name": "Schmidt" }
    // … 48 weitere Items
  ]
}

Folgeseiten berechnen:

Gesamtseitenzahl: Math.ceil(total / page_size) — im Beispiel: Math.ceil(4217 / 50) = 85
Letzte Seite hat oft weniger Items: total - (page - 1) * page_size
Wenn items.length < page_size, ist die aktuelle Seite die letzte.

Schema

Die Response-Struktur eines einzelnen Customers (mit allen Unterressourcen-Includes aktiviert). Welche tenant-konfigurierbaren Felder dein Customer-Datensatz im Detail hat, kannst du jederzeit über with_schema=true aus der API selbst lernen — siehe GET /v3/customers unten.

json

{
  // ─── System & Identifikation ─────────────────────────────────
  "id": 838,                          // Row-Primary-Key (Postgres-PK)
  "kid": 1485348238,                  // Customer-ID — Source-of-Truth im URL-Pfad (auch bei allen Sub-Resources)
  "nummer": "1430397724",             // organisations-spezifische Customer-Nummer
  "betreuer": 1485503904,             // User-ID des zuständigen Betreuers (siehe /v3/users)
  "insert_datum": "2017-01-25",       // Erstanlage (Date-only, KEIN Time-Anteil)
  "edit_datum": "2020-07-15",         // letzte Änderung (Date-only)

  // ─── Klassifikation & Anrede ─────────────────────────────────
  "kontakt_art": 0,                   // 0=Kunde, 1=Interessent, 2=Inaktiv, 3=Verstorben, 4=Lead, 5=Empfehlung, 6=Kontakt
  "anrede": "Herr",                   // "Frau" | "Herr" | "Firma" | "Familie"
  "briefanrede": "Sehr geehrter Herr Dr. Leier,",   // serverseitig generierte Brief-Anrede

  // ─── Person / Firma — Stammdaten ─────────────────────────────
  "name": "Leier",                    // Nachname oder Firmenname
  "vorname": "Helmut",                // bei anrede="Firma" typisch leer
  "titel": "Dr.",                     // akademischer Titel
  "nation": "deutsch",                // Nationalität — siehe select_fields.customers.nation

  // ─── Geburts- und Familien-Daten (nur bei natürlichen Personen) ─
  "geb": "1970-01-15",                // Geburtsdatum
  "geb_ort": "München",
  "geb_name": "",                     // Geburtsname (geboren als …)
  "familienstand": "verheiratet",     // siehe select_fields.customers.familienstand
  "datum_heirat": null,
  "datum_scheidung": null,
  "datum_erstkontakt": "2017-01-25",  // Datum des Erstkontakts mit dem Customer

  // ─── Inline-Sub-Resources (opt-in via with_*=true, Default false seit Phase C) ─
  // ⚠ Naming-Asymmetrie: das Inline-Array `banks` korrespondiert mit der
  //   URL `/v3/customers/<kid>/banking`, das Inline-Array `identifications`
  //   mit `/v3/customers/<kid>/identity`. Beide laufen unter `v3:customers:*`
  //   — siehe Note unten.

  "addresses": [
    {
      "id": 840,
      "kid": 1485348238,
      "art": 0,                       // numerisch (siehe select_fields.addresses)
      "bezeichnung": "Geschäftlich",  // Freitext-Label, z. B. "Erstanschrift", "Zweitanschrift"
      "adresszusatz": "Herr Michael Absmeier",
      "strasse": "Bahnhofstraße 20",
      "plz": "94099",
      "ort": "Ruhstorf-Sulzbach (Inn)",
      "bundesland": "Bayern",
      "insert_datum": null,
      "edit_datum": null
    }
  ],

  "contacts": [
    {
      "id": 3338,
      "kid": 1485348238,
      "art": "E-Mail",                // "E-Mail" | "Telefon" — capitalized, nicht snake_case
      "wert": "h.leier@example.com",
      "werbung": 1,                   // 0=Marketing-Opt-out, 1=Opt-in — DSGVO-relevant
      "insert_datum": null,
      "edit_datum": null
    }
  ],

  "banks": [
    {
      "id": 4,
      "kid": 1485348238,
      "typ": "0",                     // "0"=Konto, "1"=Depot (siehe select_fields.banks.bank_typ)
      "inhaber": "Helmut Leier",      // NICHT `kontoinhaber`
      "nummer": "",                   // Legacy-Kontonummer (vor IBAN-Pflicht), typisch leer
      "iban": "DE50750700240505025700",
      "bic": "DEUTDEDB750",
      "institut": "Deutsche Bank Privat und Geschäftskunden, Regensburg",
      "insert_datum": null,
      "edit_datum": null
    }
  ],

  "numbers": [
    {
      "id": 6,
      "kid": 1485348238,
      "art": 1,                       // numerische Nummern-Art
      "wert": "143/188/4024",
      "insert_datum": null,
      "edit_datum": null
    }
  ],

  "identifications": [
    {
      "id": 91,
      "kid": 1485348238,
      "art": "Personalausweis",       // "Personalausweis" | "Reisepass" (select_fields.identifications.ident_art)
      "behoerde": "Stadt München",
      "ausgestellt": "2020-03-15",
      "gueltig": "2030-03-14",
      "insert_datum": null,
      "edit_datum": null
    }
  ],

  "jobs": [
    {
      "id": 43,
      "kid": 1485348238,
      "arbeitgeber": "ACME GmbH",
      "beruf": "Geschäftsführer",
      "berufsstatus": "Geschäftsführer",   // siehe select_fields.jobs.berufsstatus
      "datum_eintritt": "2010-04-01",
      "datum_austritt": null,
      "insert_datum": "2021-04-13 11:00:00", // Sub-Resources: Datetime statt Date-only
      "edit_datum":   "2021-04-13 11:00:09"
    }
  ]
}

// Liefert die API bei explizitem `?with_schema=true` zusätzlich
// zum `items`-Array im Listen-Response. Die Metadaten sind pro Entität
// gruppiert; nur angeforderte Inline-Entitäten erscheinen als Gruppe.
{
  "fields": {
    "customers": {
    // Customer-Stammdaten
    "nummer":        { "label": "Nummer",         "data_type": "string", "select_fields_name": null },
    "anrede":        { "label": "Anrede",         "data_type": "string", "select_fields_name": "anrede" },
    "briefanrede":   { "label": "Briefanrede",    "data_type": "string", "select_fields_name": null },
    "betreuer":      { "label": "Betreuer",       "data_type": "number", "select_fields_name": "vermittler" },
    "kontakt_art":   { "label": "Kontaktart",     "data_type": "number", "select_fields_name": "kontakt_art" },
    "name":          { "label": "Name",           "data_type": "string", "select_fields_name": null },
    "vorname":       { "label": "Vorname",        "data_type": "string", "select_fields_name": null },
    "titel":         { "label": "Titel",          "data_type": "string", "select_fields_name": null },
    "nation":        { "label": "Nationalität",   "data_type": "string", "select_fields_name": "nation" },
    "familienstand": { "label": "Familienstand",  "data_type": "string", "select_fields_name": "familienstand" },
    "geb":           { "label": "Geburtsdatum",   "data_type": "date",   "data_format": "0000-00-00", "select_fields_name": null },
    "geb_ort":       { "label": "Geburtsort",     "data_type": "string", "select_fields_name": null },
    "geb_name":      { "label": "Geburtsname",    "data_type": "string", "select_fields_name": null },
    "datum_erstkontakt": { "label": "Erstkontakt",    "data_type": "date", "data_format": "0000-00-00", "select_fields_name": null },
    "datum_heirat":      { "label": "Heiratsdatum",   "data_type": "date", "data_format": "0000-00-00", "select_fields_name": null },
    "datum_scheidung":   { "label": "Scheidungsdatum","data_type": "date", "data_format": "0000-00-00", "select_fields_name": null }
    },

    // Sub-Resource: Adressen
    "addresses": {
    "bezeichnung":   { "label": "Adressbezeichnung", "data_type": "string", "select_fields_name": null },
    "adresszusatz":  { "label": "Adresszusatz",      "data_type": "string", "select_fields_name": null },
    "strasse":       { "label": "Straße",            "data_type": "string", "select_fields_name": null },
    "plz":           { "label": "PLZ",               "data_type": "string", "select_fields_name": null },
    "ort":           { "label": "Ort",               "data_type": "string", "select_fields_name": null },
    "bundesland":    { "label": "Land",              "data_type": "string", "select_fields_name": null }
    },

    // Sub-Resource: Contacts
    "contacts": {
    "wert":          { "label": "Nummer",     "data_type": "string", "select_fields_name": null },
    "werbung":       { "label": "Werbung",    "data_type": "number", "select_fields_name": "janein" }
    },

    // Sub-Resource: Banks
    "banks": {
    "typ":           { "label": "Kontoart",         "data_type": "string", "select_fields_name": "bank_typ" },
    "inhaber":       { "label": "Inhaber",          "data_type": "string", "select_fields_name": null },
    "iban":          { "label": "IBAN",             "data_type": "string", "select_fields_name": null },
    "bic":           { "label": "BIC",              "data_type": "string", "select_fields_name": null },
    "institut":      { "label": "Institut",         "data_type": "string", "select_fields_name": null },
    "bemerkung":     { "label": "Kontobezeichnung", "data_type": "string", "select_fields_name": null }
    },

    // Sub-Resource: Identifications
    "identifications": {
    "art":           { "label": "Ausweisart",  "data_type": "string", "select_fields_name": "ident_art" },
    "behoerde":      { "label": "Behörde",     "data_type": "string", "select_fields_name": null },
    "ausgestellt":   { "label": "Ausgestellt am", "data_type": "date", "data_format": "0000-00-00", "select_fields_name": null },
    "gueltig":       { "label": "Gültig bis",  "data_type": "date",   "data_format": "0000-00-00", "select_fields_name": null }
    },

    // Sub-Resource: Jobs
    "jobs": {
    "arbeitgeber":     { "label": "Arbeitgeber",  "data_type": "string", "select_fields_name": null },
    "beruf":           { "label": "Beruf",        "data_type": "string", "select_fields_name": null },
    "berufsstatus":    { "label": "Berufsstatus", "data_type": "string", "select_fields_name": "berufsstatus" },
    "datum_eintritt":  { "label": "Eintritt",     "data_type": "date",   "data_format": "0000-00-00", "select_fields_name": null },
    "datum_austritt":  { "label": "Austritt",     "data_type": "date",   "data_format": "0000-00-00", "select_fields_name": null }
    }
  },

  "select_fields": {
    "customers": {
    "anrede": [
      { "value": "Frau",    "display": "Frau"    },
      { "value": "Herr",    "display": "Herr"    },
      { "value": "Firma",   "display": "Firma"   },
      { "value": "Familie", "display": "Familie" }
    ],
    "vermittler": [
      { "value": 1485503904, "display": "Zugeordneter Betreuer" }
    ],
    "familienstand": [
      { "value": "---",                      "display": "---"                       },
      { "value": "eheähnliche Gemeinschaft", "display": "Eheähnliche Gemeinschaft" },
      { "value": "geschieden",               "display": "Geschieden"                },
      { "value": "getrennt lebend",          "display": "Getrennt lebend"          },
      { "value": "ledig",                    "display": "Ledig"                     },
      { "value": "verheiratet",              "display": "Verheiratet"               },
      { "value": "verwitwet",                "display": "Verwitwet"                 }
    ],
    "kontakt_art": [
      { "value": 0, "display": "Kunde"              },
      { "value": 1, "display": "Interessent"        },
      { "value": 2, "display": "Inaktiver Kunde"    },
      { "value": 3, "display": "Verstorbener Kunde" },
      { "value": 4, "display": "Lead"               },
      { "value": 5, "display": "Empfehlung"         },
      { "value": 6, "display": "Kontakt"            }
    ],
    "nation": [
      { "value": "", "display": "---" },
      { "value": "deutsch", "display": "Deutsch" }
    ]
    },
    "addresses": {},
    "contacts": {
      "janein": [
        { "value": 1, "display": "Ja" },
        { "value": 0, "display": "Nein" }
      ]
    },
    "banks": {
    "bank_typ": [
      { "value": 0, "display": "Konto" },
      { "value": 1, "display": "Depot" }
    ]
    },
    "identifications": {
    "ident_art": [
      { "value": "Personalausweis", "display": "Personalausweis" },
      { "value": "Reisepass",       "display": "Reisepass"       }
    ]
    },
    "jobs": {
    "berufsstatus": [
      { "value": "Angestellt",                       "display": "Angestellt" },
      { "value": "Angestellt im öffentlichen Dienst","display": "Angestellt im öffentlichen Dienst" },
      { "value": "Arbeiter",                         "display": "Arbeiter" },
      { "value": "Arbeitssuchend",                   "display": "Arbeitssuchend" },
      { "value": "Auszubildender",                   "display": "Auszubildender" },
      { "value": "Beamter",                          "display": "Beamter" },
      { "value": "Beherrschender GGF",               "display": "Beherrschender GGF" },
      { "value": "Elternzeit",                       "display": "Elternzeit" },
      { "value": "Freiberufler",                     "display": "Freiberufler" },
      { "value": "Geschäftsführer",                  "display": "Geschäftsführer" },
      { "value": "Nicht berufstätig",                "display": "Nicht berufstätig" },
      { "value": "Selbständig",                      "display": "Selbständig" },
      { "value": "Rentner",                          "display": "Rentner" },
      { "value": "Student",                          "display": "Student" },
      { "value": "Vorstand",                         "display": "Vorstand" }
    ]
    }
  }
}

external_source zeigt auf externe Lookup-Endpoints: Manche Felder referenzieren eine Quelle, die nicht über system_select_options auflösbar ist — typisch Foreign-Keys auf andere v3-Endpoints. Diese Felder bekommen ausschließlich external_source mit dem Endpoint-Pfad; select_fields_name ist in diesem Fall bewusst null, damit Clients nicht versuchen, select_fields[name] zu dereferenzieren (die Quelle wird nicht in select_fields mit-ausgeliefert).

external_source und select_fields_name schließen sich gegenseitig aus — der Client wählt einen der beiden Pfade:

select_fields_name: "X" → Optionen stehen unter select_fields.<Entität>.X (statische Optionen)
external_source: "/v3/Y" → Optionen via GET /v3/Y selbst nachladen (Foreign-Key auf andere v3-Ressource)

Beispiel: fields.customers.andere_referenz = { …, select_fields_name: null, external_source: "/v3/users" } — der Client lädt die Liste über /v3/users. Der Kunden-Betreuer ist eine Ausnahme: select_fields.customers.vermittler enthält nur den tatsächlich zugeordneten Eintrag.

Endpoints

Kunden abfragen

GET/v3/customers Im Playground testen ↗

Liefert eine paginierte Liste der Kunden deiner Organisation. Unterressourcen sind standardmäßig nicht eingebunden — wer sie braucht, schaltet sie pro Resource über with_*=true ein.

Query-Parameter

page — Seitenindex (Default 1).
limit — Items pro Seite (Default 50, Max 5000).
with_addresses — Adressen inline mitliefern. Default false (opt-in). Auf true oder 1 setzen zum Aktivieren.
with_contacts — Kontaktdaten (E-Mail, Telefon …) inline mitliefern. Default false (opt-in).
with_jobs — Berufsangaben inline mitliefern. Default false (opt-in).
with_banks — Bankverbindungen inline mitliefern. Default false (opt-in).
with_numbers — Nummern (Kundennummer, Vermittler-Nr. …) inline mitliefern. Default false (opt-in).
with_identifications — Ausweisdaten inline mitliefern. Default false (opt-in).
with_schema — Feld-Schema (Labels, Typen, Option-Quellen) im Response unter fields und select_fields mitliefern. Default false (opt-in).
flat — Unterressourcen-Arrays in flache Keys ausrollen statt als Array zurückzugeben. Default false. Das erste Element heißt addresses_strasse, das zweite addresses_1_strasse, das dritte addresses_2_strasse. Leere Sub-Resource-Arrays produzieren keine Keys.

Request

bash

curl 'https://www.api.i-planner.app/v3/customers?page=1&limit=50&with_jobs=false' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

const url = new URL('https://www.api.i-planner.app/v3/customers')
url.searchParams.set('page', '1')
url.searchParams.set('limit', '50')
url.searchParams.set('with_jobs', 'false')

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.IPLANNER_API_TOKEN}` },
})
const { items, total, page, page_size } = await res.json()

import os, requests

res = requests.get(
    'https://www.api.i-planner.app/v3/customers',
    params={'page': 1, 'limit': 50, 'with_jobs': 'false'},
    headers={'Authorization': f'Bearer {os.environ["IPLANNER_API_TOKEN"]}'},
)
data = res.json()

<?php
$query = http_build_query([
  'page' => 1, 'limit' => 50, 'with_jobs' => 'false',
]);
$ch = curl_init("https://www.api.i-planner.app/v3/customers?$query");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('IPLANNER_API_TOKEN')],
]);
$data = json_decode(curl_exec($ch), true);

Response

json

// OK — Pagination-Envelope + `items[]`. Jedes Item ist ein
// vollständiges Customer-Objekt mit Unterressourcen-Arrays — siehe
// „Das Customer-Objekt" oben für die volle Struktur.
{
  "page": 1,
  "page_size": 50,
  "total": 4217,
  "items": [
    {
      "kid": 12345,
      "id": 67890,
      "vorname": "Helmut",
      "name": "Leier",
      // … weitere Felder + addresses[], contacts[], jobs[],
      // banks[], numbers[], identifications[]
    }
  ],
  "fields": {
    "customers": {
      "vorname": { "label": "Vorname", "data_type": "string", "select_fields_name": null }
    }
  },
  "select_fields": { "customers": {} }
}

// Token fehlt oder ist ungültig — Authorization-Header prüfen.
// Mögliche `error`-Werte: missing_bearer_token, empty_token,
// invalid_token, token_expired.
{
  "error": "missing_bearer_token",
  "message": "Authorization header must contain a Bearer token."
}

// Der Token ist gültig, hat aber nicht den nötigen Scope. Der Body
// nennt den fehlenden Scope explizit — Org-Admin um Freischaltung bitten.
{
  "error": "missing_required_scope",
  "message": "The endpoint \"/v3/customers\" requires the \"v3:customers:read\" scope.",
  "required_scope": "v3:customers:read",
  "provided_scope": "v3:customers:read = 0",
  "hint": "Ask your organization admin to enable 'v3:customers:read'."
}

// Rate-Limit überschritten — siehe Overview-Doku zu Rate Limits.
// `retry_after` (in Sekunden) und der `Retry-After`-Header sagen,
// wann ein neuer Versuch sinnvoll ist.
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 12 seconds.",
  "retry_after": 12
}

// Rate-Limit-Service nicht erreichbar (Redis-Outage). Die API
// antwortet fail-closed, damit kein ungedrosselter Traffic
// durchrutscht. Nach 10 Sekunden retrien.
{
  "error": "service_unavailable",
  "message": "Rate limiting service is temporarily unavailable. Please retry shortly.",
  "retry_after": 10
}

Kunden anlegen

POST/v3/customers Im Playground testen ↗

Legt einen oder mehrere Kunden an. Der Request-Body kann entweder ein einzelnes Customer-Objekt oder ein Array von Customer-Objekten sein (Batch, max. 100 Items).

Body-Schema

Der Body enthält nur die direkten Felder des Customer-Objekts (anrede, vorname, name, geb, …). Welche Felder dein Tenant kennt, siehst du im Schema-Tab oben oder live über GET /v3/customers?with_schema=true.

Verhalten bei unbekannten Feldern: Felder, die nicht zum Schema gehören oder system-intern sind (id, kid, guid, insert_datum, edit_datum, del, alle vm_* / push_* / alert_* / Passwort-Felder), werden stillschweigend verworfen — kein 400-Error. Schickst du ein leeres Objekt oder eines mit ausschließlich verworfenen Feldern, antwortet der Server allerdings mit 400 no_valid_fields.

Sonderfeld betreuer: Numerische kid des zuständigen Mitarbeiters. Fehlt das Feld, setzt die API automatisch die kid des authentifizierten Tokens (= „du bist Betreuer").

Batch-Verhalten: Jedes Item wird einzeln in einer eigenen Transaktion angelegt (INSERT + Search-Index + Log + Document-Ordner). Schlägt ein Item fehl, landet es in failed[], der Rest des Batches läuft normal weiter — keine alle-oder-keiner-Semantik. Bis zu 10 Items werden parallel verarbeitet.

Request

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{

    "anrede": "frau",
    "vorname": "Anna",
    "name": "Müller",
    "geb": "1985-03-12"
  }'

curl -X POST 'https://www.api.i-planner.app/v3/customers' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "vorname": "Anna", "name": "Müller" },
    { "vorname": "Bernd", "name": "Schmidt" }
  ]'

const res = await fetch('https://www.api.i-planner.app/v3/customers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IPLANNER_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    vorname: 'Anna',
    name: 'Müller',
    geb: '1985-03-12',
  }),
})

res = requests.post(
    'https://www.api.i-planner.app/v3/customers',
    json={'vorname': 'Anna', 'name': 'Müller'},
    headers={'Authorization': f'Bearer {os.environ["IPLANNER_API_TOKEN"]}'},
)

<?php
$ch = curl_init('https://www.api.i-planner.app/v3/customers');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode(['vorname' => 'Anna', 'name' => 'Müller']),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('IPLANNER_API_TOKEN'),
    'Content-Type: application/json',
  ],
]);
$res = json_decode(curl_exec($ch), true);

Response

json

// Created — nur bei Single-Item-Request UND erfolgreich.
// Der Body ist direkt das angelegte Customer-Objekt (kein Wrapper),
// inkl. der vom Server vergebenen `kid` und `id` plus
// `insert_datum` / `edit_datum`.
{
  "kid": 12346,
  "id": 67890,
  "vorname": "Anna",
  "name": "Müller",
  "geb": "1985-03-12",
  "insert_datum": "2026-05-12",
  "edit_datum": "2026-05-12",
  "betreuer": 42
}

// OK — Batch-Response. Wird auch zurückgegeben, wenn ein Single-Item
// teilweise fehlschlägt (Validation pro Item, keine alle-oder-keiner-
// Atomicity).
//
//   success        true, wenn `failedCount === 0`, sonst false.
//   insertedCount  Anzahl erfolgreich angelegter Items.
//   failedCount    Anzahl gescheiterter Items.
//   inserted[]     Die vollen Customer-Objekte der erfolgreichen Items.
//   failed[]       Pro fehlgeschlagenem Item: `input` (der Original-Body),
//                  `reason` (`invalid_object` | `no_valid_fields` |
//                  `insert_error`) und ggf. `error` (interne Fehler-Message).
{
  "success": true,
  "insertedCount": 2,
  "failedCount": 0,
  "inserted": [
    { "kid": 12346, "id": 67891, "vorname": "Anna",  "name": "Müller"   /* … */ },
    { "kid": 12347, "id": 67892, "vorname": "Bernd", "name": "Schmidt" /* … */ }
  ],
  "failed": []
}

// Bad Request — drei Varianten am `error`-Feld erkennbar:
//
//   1. empty_body       — Body fehlt oder ist kein Objekt.
//   2. empty_array      — Array wurde gesendet, war aber leer.
//   3. batch_too_large  — Mehr als 100 Items im Array (Hard-Limit).
{
  "error": "empty_body",
  "message": "Request body must contain at least one customer object."
}

// {
//   "error": "empty_array",
//   "message": "Array must contain at least one customer object."
// }

// {
//   "error": "batch_too_large",
//   "message": "Maximum 100 items per request."
// }

// Token fehlt oder ist ungültig — Authorization-Header prüfen.
// Mögliche `error`-Werte: missing_bearer_token, empty_token,
// invalid_token, token_expired.
{
  "error": "missing_bearer_token",
  "message": "Authorization header must contain a Bearer token."
}

// Token hat nicht den Schreib-Scope. POST/PATCH/DELETE auf
// Customers brauchen `v3:customers:write`.
{
  "error": "missing_required_scope",
  "message": "The endpoint \"/v3/customers\" requires the \"v3:customers:write\" scope.",
  "required_scope": "v3:customers:write",
  "hint": "Ask your organization admin to enable 'v3:customers:write'."
}

// Rate-Limit überschritten — `retry_after`-Sekunden warten.
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 12 seconds.",
  "retry_after": 12
}

Kunden abrufen

GET/v3/customers/<kid> Im Playground testen ↗

Liefert einen einzelnen Customer-Datensatz inklusive Unterressourcen. <id> ist die numerische kid.

Query-Parameter — identisch zu GET /v3/customers (with_addresses, with_contacts, with_jobs, with_banks, with_numbers, with_identifications, with_schema, flat). Default für alle: false (opt-in) — Sub-Ressourcen müssen explizit per ?with_addresses=true etc. angefordert werden.

Request

bash

curl 'https://www.api.i-planner.app/v3/customers/12345' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Response

json

// OK — Customer-Datensatz inkl. aller Unterressourcen (sofern
// `with_*=true`). Schema-Hinweise siehe „Das Customer-Objekt" oben.
{
  "kid": 12345,
  "id": 67890,
  "vorname": "Helmut",
  "name": "Leier",
  "addresses": [ /* … */ ],
  "contacts":  [ /* … */ ]
}

// Bad Request — `<kid>` ist 0, negativ, kein Integer oder > 2^31-1.
{
  "error": "invalid_kid",
  "message": "Path parameter \"kid\" must be a positive integer between 1 and 2147483647."
}

// Not Found — Customer mit dieser `kid` existiert nicht in deiner Org
// (oder wurde bereits soft-deleted). Bei einem nicht-numerischen Pfad
// schlägt schon die Path-Validierung mit `invalid_kid` (400) zu.
{
  "error": "endpoint_not_found",
  "message": "This API endpoint does not exist."
}

// {
//   "error": "not_found",
//   "message": "No customer record exists for ID 12345."
// }

// Token fehlt oder ist ungültig.
{
  "error": "missing_bearer_token",
  "message": "Authorization header must contain a Bearer token."
}

// Token hat nicht den Lese-Scope `v3:customers:read`.
{
  "error": "missing_required_scope",
  "required_scope": "v3:customers:read",
  "hint": "Ask your organization admin to enable 'v3:customers:read'."
}

// Rate-Limit überschritten — `retry_after`-Sekunden warten.
{
  "error": "rate_limit_exceeded",
  "retry_after": 12
}

Unterscheidung 404-Varianten — endpoint_not_found kommt, wenn <id> nicht numerisch ist (z. B. eine UUID übergeben wurde — die Route existiert für den Pfad nicht). not_found kommt, wenn <id> numerisch und gültig ist, aber kein Kunde mit dieser kid in deiner Organisation existiert oder bereits soft-deleted ist.

Kunden aktualisieren

PATCH/v3/customers/<kid> Im Playground testen ↗

Aktualisiert die im Body gesendeten Felder eines Customers. Felder, die nicht im Body stehen, bleiben unverändert (PATCH-Semantik, kein PUT).

Wie beim POST gilt: Unterressourcen-Arrays werden ignoriert — addresses, contacts, banking etc. im PATCH-Body bewirken nichts. Unterressourcen werden über ihre eigenen Endpoints (PATCH /v3/customers/<kid>/addresses/<id> usw.) aktualisiert. Unbekannte und system-interne Felder werden still verworfen (gleiches Verhalten wie beim Create).

Request

bash

curl -X PATCH 'https://www.api.i-planner.app/v3/customers/12345' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "kommentar": "Aktualisiert per API am 2026-05-12" }'

Response

json

// OK — Update angewendet. Der Body ist kompakt: ein Success-Flag
// und `updated` = Anzahl der tatsächlich geänderten Felder. Der
// volle aktualisierte Datensatz wird NICHT zurückgegeben — wer ihn
// braucht, ruft danach `GET /v3/customers/<id>` auf.
{
  "success": true,
  "updated": 1
}

// Bad Request — zwei Varianten:
//
//   1. empty_body   — kein Body oder Body enthält keine Felder
//                     zum Aktualisieren.
//   2. invalid_kid  — `<kid>` ist 0, negativ, kein Integer oder > 2^31-1.
{
  "error": "empty_body",
  "message": "Request body must contain fields to update."
}

// {
//   "error": "invalid_kid",
//   "message": "Path parameter \"kid\" must be a positive integer between 1 and 2147483647."
// }

// Customer mit dieser `kid` existiert nicht oder wurde soft-deleted.
{
  "error": "not_found",
  "message": "No customer record exists for ID 12345."
}

// Token hat nicht den Schreib-Scope `v3:customers:write`.
{
  "error": "missing_required_scope",
  "required_scope": "v3:customers:write",
  "hint": "Ask your organization admin to enable 'v3:customers:write'."
}

// Rate-Limit überschritten — `retry_after`-Sekunden warten.
{
  "error": "rate_limit_exceeded",
  "retry_after": 12
}

Kunden löschen

DELETE/v3/customers/<kid> Im Playground testen ↗

Markiert den Customer als gelöscht (del=1), entfernt ihn aber nicht hart aus der Datenbank — analog zum „Papierkorb" im UI. Der Datensatz wird aus Listen-Responses und Suchergebnissen ausgeblendet, bleibt aber für Audit-Zwecke erhalten.

Request

bash

curl -X DELETE 'https://www.api.i-planner.app/v3/customers/12345' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Response

json

// OK — Customer wurde als gelöscht markiert (Soft-Delete via `del=1`).
// Der Datensatz bleibt in der Datenbank für Audit-Zwecke erhalten, ist
// aber aus Listen-Responses und Suchergebnissen ausgeblendet.
{
  "success": true,
  "deleted": true,
  "soft_deleted": true,
  "kid": 12345
}

// Bad Request — `<kid>` ist 0, negativ, kein Integer oder > 2^31-1.
{
  "error": "invalid_kid",
  "message": "Path parameter \"kid\" must be a positive integer between 1 and 2147483647."
}

// Customer existiert nicht oder wurde bereits soft-deleted — beide
// Fälle geben dieselbe Antwort, weil der Read-Check `WHERE del = 0`
// soft-deleted Einträge schon ausblendet.
{
  "error": "not_found",
  "message": "No customer record exists for ID 12345."
}

// Token hat nicht den Schreib-Scope `v3:customers:write`.
{
  "error": "missing_required_scope",
  "required_scope": "v3:customers:write",
  "hint": "Ask your organization admin to enable 'v3:customers:write'."
}

// Rate-Limit überschritten — `retry_after`-Sekunden warten.
{
  "error": "rate_limit_exceeded",
  "retry_after": 12
}

Duplikat zusammenführen

POST/v3/customers/<kid>/merge

Führt einen Slave-Customer in den Master zusammen. Alle Sub-Ressourcen des Slave werden auf den Master umgehängt, der Slave-Datensatz wird soft-deleted (del=1). Der Vorgang läuft in einer Transaktion — entweder gehen alle Daten über, oder gar keine.

Anwendungsfall: Derselbe Kunde wurde versehentlich doppelt erfasst (z. B. einmal über Posteingang-Import, einmal manuell). Du wählst eine der beiden Karteien als "die Wahrheit" (Master) und schiebst alles aus der anderen (Slave) hinein.

Was wandert auf den Master?

Bereich	Verhalten
`addresses`, `contacts`, `banking`, `numbers`, `jobs`, `identity`	Slave-Zeilen bleiben als zusätzliche Rows am Master bestehen (kid-Rewrite).
`contracts`, `damages`, `finances`, `goals`, `activities`, `documents` (inkl. Ordner-Baum)	kid-Rewrite — alle CRM-Objekte des Slave gehören danach dem Master.
`comments`, `tags`, `followers`	Annotationen, die per `(section='customers', <row-pk>)` auf den Slave zeigen, werden auf die Master-`crm_kontakte.id` umgeschrieben.
`links` (crm_relations)	Beide Richtungen umgeschrieben; master↔master-Self-Loops, die dabei entstehen, werden direkt gelöscht.
`relations` (Ehe-/Verwandtschaft)	Beide kid-Spalten umgeschrieben; master↔master-Self-Loops werden gelöscht.

Was bleibt am Slave?

Die crm_kontakte-Zeile selbst bekommt del=1 und ist über GET /v3/customers/<slave-kid> ab sofort als 404 not_found markiert.
Das crm_log (Audit-Trail) des Slave bleibt unangetastet — Bewegungen vor dem Merge sollen historisch nachvollziehbar bleiben.
Der Such-Index-Eintrag des Slave wird entfernt (der Master behält seinen eigenen).

Konflikt-Strategie für die Stammdaten — über das mode-Feld steuerbar:

`mode`	Verhalten
`master_wins` (Default)	Master-Stammdaten (Name, Anrede, Geburtsdatum etc.) bleiben unverändert.
`enrich_master`	Leere Master-Felder werden mit Slave-Werten gefüllt. Felder mit Wert am Master werden nie überschrieben. Betrifft nur `crm_kontakte`-Skalare (`vorname`, `name`, `titel`, `anrede`, `geb_name`, `namenszusatz`, `geb`).

Audit-Log: Auf der Master-Seite wird ein CUSTOMERS_MERGE-Eintrag geschrieben, der Master- und Slave-Display-Namen referenziert. Im Activity-Feed erscheint die Zeile "… hat den Kunden <Master> mit <Slave> zusammengeführt."

Body

Feld	Typ	Pflicht	Default	Bemerkung
`slave_kid`	integer \| numerische string	✓	—	Die `kid` des Slave-Customers. Muss `≠ <kid>` aus dem Pfad sein.
`mode`	`master_wins` \| `enrich_master`	—	`master_wins`	Konflikt-Strategie für `crm_kontakte`-Skalare.

Request

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/merge' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "slave_kid": 67890,
    "mode": "master_wins"
  }'

Response

json

// OK — Merge erfolgreich. Slave-kid ist soft-deleted, alle Sub-Resources
// hängen am Master.
{
  "success": true,
  "master_kid": 12345,
  "slave_kid": 67890,
  "mode": "master_wins"
}

// `slave_kid` und Master-`kid` sind identisch.
{
  "error": "self_merge",
  "message": "master and slave kid must differ."
}

// `slave_kid` fehlt, ist kein Integer, oder `mode` ist kein erlaubter Wert.
{
  "error": "validation_failed",
  "message": "Request body has invalid or unknown fields.",
  "issues": [
    {
      "path": "mode",
      "code": "invalid_enum_value",
      "message": "Invalid enum value. Expected 'master_wins' | 'enrich_master'."
    }
  ]
}

// Der Master-`kid` aus dem Pfad existiert nicht oder ist bereits soft-deleted.
{
  "error": "master_not_found",
  "message": "Master customer does not exist or is already deleted."
}

// `slave_kid` aus dem Body existiert nicht oder ist bereits soft-deleted.
{
  "error": "slave_not_found",
  "message": "Slave customer does not exist or is already deleted."
}

// Token hat nicht den Schreib-Scope `v3:customers:write`.
{
  "error": "missing_required_scope",
  "required_scope": "v3:customers:write",
  "hint": "Ask your organization admin to enable 'v3:customers:write'."
}

Unterressourcen

Jede Unterressource hängt über kid an einem Customer und folgt demselben Pagination-Envelope (page, page_size, total, items) wie die Customer-Liste. POST/PATCH/DELETE verhalten sich wie bei den Customer-Endpoints — Unknown- und Protected-Fields werden still verworfen, Fehler-Bodies folgen dem gleichen Muster (empty_body, invalid_id, not_found etc.).

Direkt am Customer — feste Bestandteile des Customer-Schemas. Jede Unterressource hat einen Listen-Endpoint (/v3/customers/<kid>/<sub-resource>), einen Create-Endpoint am gleichen Pfad und einen <id>-Pfad für Retrieve/Update/Delete (/v3/customers/<kid>/<sub-resource>/<id>). Path-kid ist Source-of-Truth — POST/PATCH-Bodies dürfen kid nicht enthalten, sonst antwortet der Server mit 400 body_kid_forbidden.

Addresses

Adressen eines Customers. Pro Customer können mehrere Adressen hinterlegt sein (Erstanschrift, Zweitanschrift, Geschäftlich, …); die Unterscheidung läuft über das Freitext-Feld bezeichnung.

Scopes: v3:customers:read (List + Get) · v3:customers:write (Create + Patch + Delete).

json

{
  "id": 840,                          // numerischer Row-Identifier (Postgres-PK)
  "kid": 1485348238,                  // Customer, an dem die Adresse hängt
  "art": 0,                           // numerischer Adress-Typ — in v3 nur 0 belegt
  "bezeichnung": "Geschäftlich",      // Freitext-Label: "Erstanschrift", "Zweitanschrift", "Geschäftlich", …
  "adresszusatz": "Herr Michael Absmeier",
  "strasse": "Bahnhofstraße 20",
  "plz": "94099",
  "ort": "Ruhstorf-Sulzbach (Inn)",
  "bundesland": "Bayern",
  "insert_datum": null,
  "edit_datum": null
}

// Liefert die API bei `?with_schema=true` zusätzlich zum
// `items[]`-Array im Listen-Response.
{
  "fields": {
    "bezeichnung":  { "label": "Adressbezeichnung", "data_type": "string", "select_fields_name": null },
    "adresszusatz": { "label": "Adresszusatz",      "data_type": "string", "select_fields_name": null },
    "strasse":      { "label": "Straße",            "data_type": "string", "select_fields_name": null },
    "plz":          { "label": "PLZ",               "data_type": "string", "select_fields_name": null },
    "ort":          { "label": "Ort",               "data_type": "string", "select_fields_name": null },
    "bundesland":   { "label": "Land",              "data_type": "string", "select_fields_name": null }
  }
}

GET/v3/customers/<kid>/addresses Im Playground testen ↗

POST/v3/customers/<kid>/addresses Im Playground testen ↗

GET/v3/customers/<kid>/addresses/<id> Im Playground testen ↗

PATCH/v3/customers/<kid>/addresses/<id> Im Playground testen ↗

DELETE/v3/customers/<kid>/addresses/<id> Im Playground testen ↗

Query-Parameter

kid (im Pfad, nicht als Query) — Customer-ID des Parents. Bei Sub-Resources steht die ID jetzt im URL-Pfad statt im Query-String.
page — Seitenindex (Default 1).
limit — Items pro Seite (Default 50, Max 5000).
with_schema — Feld-Schema (fields + select_fields) im Response mitliefern. Default false (opt-in).

Beispiel — Adressen eines Kunden abfragen

bash

curl 'https://www.api.i-planner.app/v3/customers/12345/addresses' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

{
  "page": 1,
  "page_size": 50,
  "total": 2,
  "items": [
    {
      "id": 1340,
      "kid": 1485504800,
      "art": 0,
      "bezeichnung": "Zweitanschrift",
      "adresszusatz": null,
      "strasse": "Maximilianstr. 52",
      "plz": "80538",
      "ort": "München",
      "bundesland": "Bayern",
      "insert_datum": "2019-11-28 08:39:28",
      "edit_datum":   "2020-09-01 07:30:10"
    },
    {
      "id": 844,
      "kid": 1485504800,
      "art": 0,
      "bezeichnung": "Erstanschrift",
      "adresszusatz": "c/o Bürogemeinschaft Süd",
      "strasse": "Bahnhofstraße 20",
      "plz": "94099",
      "ort": "Ruhstorf-Sulzbach (Inn)",
      "bundesland": "Bayern",
      "insert_datum": null,
      "edit_datum":   "2020-09-01 07:30:10"
    }
  ]
}

Beispiel — neue Adresse anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/addresses' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bezeichnung": "Erstanschrift",
    "strasse": "Musterweg 1",
    "plz": "80331",
    "ort": "München",
    "bundesland": "Bayern"
  }'

// Body enthält nur die neue `id` und ein `success`-Flag — NICHT den
// vollen Datensatz. Wer den braucht, ruft danach
// `GET /v3/customers/<kid>/addresses/<id>` auf.
{
  "success": true,
  "id": 78003
}

Beispiel — Adresse löschen

bash

curl -X DELETE 'https://www.api.i-planner.app/v3/customers/12345/addresses/78001' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

// Soft-Delete — der Datensatz bleibt mit `del=1` in der Datenbank,
// ist aber aus Listen-Responses ausgeblendet.
//
// Verhalten bei wiederholtem DELETE: Der zweite Aufruf antwortet
// mit `404 not_found`, weil der Read-Check (`WHERE del = 0`) den
// bereits gelöschten Eintrag nicht mehr findet — gleicher
// Error-Body wie bei einer nie existierenden ID.
//
// Sehr selten: `409 delete_failed` bei Race-Condition (concurrent
// Update zwischen Lesen und Schreiben). Retry ist sicher, weil
// keine Daten verändert wurden.
{
  "success": true,
  "deleted": true,
  "soft_deleted": true,
  "id": 78001
}

Contacts

Kontaktdaten eines Customers — eine Zeile pro Kanal (E-Mail, Telefon, Fax, Website …). Genaue Felder hängen vom Tenant-Schema ab.

Scopes: v3:customers:read (List + Get) · v3:customers:write (Create + Patch + Delete).

json

{
  "id": 3338,
  "kid": 1485348238,
  "art": "E-Mail",                    // "E-Mail" | "Telefon" — capitalized, kein snake_case
  "wert": "michael@absmeierfv.de",
  "werbung": 0,                       // 0=Marketing-Opt-out, 1=Opt-in (DSGVO-relevant)
  "insert_datum": null,
  "edit_datum": null
}

{
  "fields": {
    "art":     { "label": "Art",     "data_type": "string", "select_fields_name": null },
    "wert":    { "label": "Nummer",  "data_type": "string", "select_fields_name": null },
    "werbung": { "label": "Werbung", "data_type": "number", "select_fields_name": "janein" }
  },
  "select_fields": {
    "janein": [
      { "value": 1, "display": "Ja"   },
      { "value": 0, "display": "Nein" }
    ]
  }
}

GET/v3/customers/<kid>/contacts Im Playground testen ↗

POST/v3/customers/<kid>/contacts Im Playground testen ↗

GET/v3/customers/<kid>/contacts/<id> Im Playground testen ↗

PATCH/v3/customers/<kid>/contacts/<id> Im Playground testen ↗

DELETE/v3/customers/<kid>/contacts/<id> Im Playground testen ↗

Query-Parameter

kid (im Pfad, nicht als Query) — Customer-ID des Parents. Bei Sub-Resources steht die ID jetzt im URL-Pfad statt im Query-String.
page — Seitenindex (Default 1).
limit — Items pro Seite (Default 50, Max 5000).
with_schema — Feld-Schema im Response mitliefern. Default false (opt-in).

Beispiel — Kontaktdaten eines Kunden abfragen

bash

curl 'https://www.api.i-planner.app/v3/customers/12345/contacts' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

{
  "page": 1,
  "page_size": 50,
  "total": 2,
  "items": [
    { "id": 3338, "kid": 1485348238, "art": "E-Mail",  "wert": "michael@absmeierfv.de", "werbung": 0 },
    { "id": 3340, "kid": 1485348238, "art": "Telefon", "wert": "08503-923340",          "werbung": 0 }
  ]
}

Beispiel — E-Mail-Adresse anlegen (mit Marketing-Opt-in)

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/contacts' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "art": "E-Mail",
    "wert": "neu@example.com",
    "werbung": 1
  }'

// Body enthält nur die neue `id` — voller Datensatz separat via
// `GET /v3/customers/<kid>/contacts/<id>` abrufen.
{
  "success": true,
  "id": 79004
}

Beispiel — Kontaktdatensatz löschen

bash

curl -X DELETE 'https://www.api.i-planner.app/v3/customers/12345/contacts/79001' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

// Soft-Delete — siehe Addresses oben für Details.
{
  "success": true,
  "deleted": true,
  "soft_deleted": true,
  "id": 79001
}

Banking

Bankverbindungen eines Customers. Genaue Felder hängen vom Tenant-Schema ab.

Scopes: v3:customers:read (List + Get) · v3:customers:write (Create + Patch + Delete).

json

{
  "id": 4,
  "kid": 1485348238,
  "typ": "0",                         // "0"=Konto, "1"=Depot — String (in select_fields auch number)
  "inhaber": "Absmeier, Michael",
  "nummer": "",                       // Legacy-Kontonummer (vor IBAN-Pflicht), typisch leer
  "iban": "DE50750700240505025700",
  "bic": "DEUTDEDB750",
  "institut": "Deutsche Bank Privat und Geschäftskunden, Regensburg",
  "insert_datum": null,
  "edit_datum": null
}

{
  "fields": {
    "typ":       { "label": "Kontoart",        "data_type": "string", "select_fields_name": "bank_typ" },
    "inhaber":   { "label": "Inhaber",         "data_type": "string", "select_fields_name": null },
    "iban":      { "label": "IBAN",            "data_type": "string", "select_fields_name": null },
    "bic":       { "label": "BIC",             "data_type": "string", "select_fields_name": null },
    "institut":  { "label": "Institut",        "data_type": "string", "select_fields_name": null },
    "bemerkung": { "label": "Kontobezeichnung","data_type": "string", "select_fields_name": null }
  },
  "select_fields": {
    "bank_typ": [
      { "value": 0, "display": "Konto" },
      { "value": 1, "display": "Depot" }
    ]
  }
}

GET/v3/customers/<kid>/banking Im Playground testen ↗

POST/v3/customers/<kid>/banking Im Playground testen ↗

GET/v3/customers/<kid>/banking/<id> Im Playground testen ↗

PATCH/v3/customers/<kid>/banking/<id> Im Playground testen ↗

DELETE/v3/customers/<kid>/banking/<id> Im Playground testen ↗

Query-Parameter

kid (im Pfad, nicht als Query) — Customer-ID des Parents. Bei Sub-Resources steht die ID jetzt im URL-Pfad statt im Query-String.
page — Seitenindex (Default 1).
limit — Items pro Seite (Default 50, Max 5000).
with_schema — Feld-Schema im Response mitliefern. Default false (opt-in).

Beispiel — Bankverbindungen abfragen

bash

curl 'https://www.api.i-planner.app/v3/customers/12345/banking' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

{
  "page": 1,
  "page_size": 50,
  "total": 1,
  "items": [
    {
      "id": 4,
      "kid": 1485348238,
      "typ": "0",
      "inhaber": "Absmeier, Michael",
      "nummer": "",
      "iban": "DE50750700240505025700",
      "bic": "DEUTDEDB750",
      "institut": "Deutsche Bank Privat und Geschäftskunden, Regensburg",
      "insert_datum": null,
      "edit_datum": null
    }
  ]
}

Beispiel — Bankverbindung anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/banking' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "typ": "0",
    "inhaber": "Helmut Leier",
    "iban": "DE89370400440532013000",
    "bic": "SSKMDEMM",
    "institut": "Sparkasse München"
  }'

// Body enthält nur die neue `id` — voller Datensatz separat via
// `GET /v3/customers/<kid>/banking/<id>` abrufen.
{
  "success": true,
  "id": 80002
}

Beispiel — Bankverbindung löschen

bash

curl -X DELETE 'https://www.api.i-planner.app/v3/customers/12345/banking/80001' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

// Soft-Delete — siehe Addresses oben für Details.
{
  "success": true,
  "deleted": true,
  "soft_deleted": true,
  "id": 80001
}

Nummern

Kunden-, Vermittler-, Steuer- und sonstige Identifizierungsnummern. Genaue Felder hängen vom Tenant-Schema ab.

Scopes: v3:customers:read (List + Get) · v3:customers:write (Create + Patch + Delete).

json

{
  "id": 6,
  "kid": 1485504800,
  "art": 1,                           // numerischer Nummern-Typ — pro Tenant konfiguriert
  "wert": "143/188/4024",
  "insert_datum": null,
  "edit_datum": null
}

{
  "fields": {
    "art": { "label": "Art", "data_type": "number", "select_fields_name": "nummern" },
    "wert": { "label": "Nummer", "data_type": "string", "select_fields_name": null }
  },
  "select_fields": {
    "nummern": [
      { "value": 1, "display": "Steuernummer" }
    ]
  }
}

GET/v3/customers/<kid>/numbers Im Playground testen ↗

POST/v3/customers/<kid>/numbers Im Playground testen ↗

GET/v3/customers/<kid>/numbers/<id> Im Playground testen ↗

PATCH/v3/customers/<kid>/numbers/<id> Im Playground testen ↗

DELETE/v3/customers/<kid>/numbers/<id> Im Playground testen ↗

Query-Parameter

kid (im Pfad, nicht als Query) — Customer-ID des Parents. Bei Sub-Resources steht die ID jetzt im URL-Pfad statt im Query-String.
page — Seitenindex (Default 1).
limit — Items pro Seite (Default 50, Max 5000).
with_schema — Feld-Schema im Response mitliefern. Default false (opt-in).

Beispiel — Nummern abfragen

bash

curl 'https://www.api.i-planner.app/v3/customers/12345/numbers' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

{
  "page": 1,
  "page_size": 50,
  "total": 2,
  "items": [
    { "id": 6, "kid": 1485504800, "art": 1, "wert": "143/188/4024" },
    { "id": 8, "kid": 1485504800, "art": 1, "wert": "046/105/07277" }
  ]
}

Beispiel — neue Nummer anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/numbers' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "art": 1,
    "wert": "K-9876543"
  }'

// Body enthält nur die neue `id` — voller Datensatz separat via
// `GET /v3/customers/<kid>/numbers/<id>` abrufen.
{ "success": true, "id": 81003 }

Beispiel — Nummer löschen

bash

curl -X DELETE 'https://www.api.i-planner.app/v3/customers/12345/numbers/81001' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

// Soft-Delete — siehe Addresses oben für Details.
{
  "success": true,
  "deleted": true,
  "soft_deleted": true,
  "id": 81001
}

Identity

Ausweisdaten eines Customers — Personalausweis oder Reisepass.

Scopes: v3:customers:read (List + Get) · v3:customers:write (Create + Patch + Delete).

json

{
  "id": 91,
  "kid": 1485348238,
  "art": "Personalausweis",           // "Personalausweis" | "Reisepass" — capitalized String
  "behoerde": "Stadt München",        // ausstellende Behörde
  "ausgestellt": "2020-03-15",        // Ausstellungsdatum (Date)
  "gueltig": "2030-03-14",            // Ablaufdatum (Date)
  "insert_datum": null,
  "edit_datum": null
}

{
  "fields": {
    "art":         { "label": "Ausweisart",     "data_type": "number", "select_fields_name": "ident_art" },
    "behoerde":    { "label": "Behörde",        "data_type": "string", "select_fields_name": null },
    "ausgestellt": { "label": "Ausgestellt am", "data_type": "date",   "data_format": "0000-00-00", "select_fields_name": null },
    "gueltig":     { "label": "Gültig bis",     "data_type": "date",   "data_format": "0000-00-00", "select_fields_name": null }
  },
  "select_fields": {
    "ident_art": [
      { "value": "Personalausweis", "display": "Personalausweis" },
      { "value": "Reisepass",       "display": "Reisepass"       }
    ]
  }
}

GET/v3/customers/<kid>/identity Im Playground testen ↗

POST/v3/customers/<kid>/identity Im Playground testen ↗

GET/v3/customers/<kid>/identity/<id> Im Playground testen ↗

PATCH/v3/customers/<kid>/identity/<id> Im Playground testen ↗

DELETE/v3/customers/<kid>/identity/<id> Im Playground testen ↗

Query-Parameter

kid (im Pfad, nicht als Query) — Customer-ID des Parents. Bei Sub-Resources steht die ID jetzt im URL-Pfad statt im Query-String.
page — Seitenindex (Default 1).
limit — Items pro Seite (Default 50, Max 5000).
with_schema — Feld-Schema im Response mitliefern. Default false (opt-in).

Beispiel — Ausweisdaten abfragen

bash

curl 'https://www.api.i-planner.app/v3/customers/12345/identity' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

{
  "page": 1,
  "page_size": 50,
  "total": 1,
  "items": [
    {
      "id": 91,
      "kid": 1485348238,
      "art": "Personalausweis",
      "behoerde": "Stadt München",
      "ausgestellt": "2020-03-15",
      "gueltig": "2030-03-14"
    }
  ]
}

Beispiel — Reisepass anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/identity' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "art": "Reisepass",
    "behoerde": "Landratsamt München",
    "ausgestellt": "2022-06-10",
    "gueltig": "2032-06-09"
  }'

// Body enthält nur die neue `id` — voller Datensatz separat via
// `GET /v3/customers/<kid>/identity/<id>` abrufen.
{ "success": true, "id": 82002 }

Beispiel — Ausweisdaten löschen

bash

curl -X DELETE 'https://www.api.i-planner.app/v3/customers/12345/identity/82001' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

// Soft-Delete — siehe Addresses oben für Details.
{
  "success": true,
  "deleted": true,
  "soft_deleted": true,
  "id": 82001
}

Jobs

Beruf, Arbeitgeber und Beschäftigungs-Details eines Customers. Genaue Felder hängen vom Tenant-Schema ab.

Scopes: v3:customers:read (List + Get) · v3:customers:write (Create + Patch + Delete).

json

{
  "id": 43,
  "kid": 1485504800,
  "arbeitgeber": "ACME GmbH",
  "beruf": "Geschäftsführer",
  "berufsstatus": "Geschäftsführer",     // siehe select_fields["berufsstatus"]
  "datum_eintritt": "2010-04-01",
  "datum_austritt": null,                 // null = aktuell beschäftigt
  "insert_datum": "2021-04-13 11:00:00",  // Sub-Resources: Datetime statt Date-only
  "edit_datum":   "2021-04-13 11:00:09"
}

{
  "fields": {
    "arbeitgeber":    { "label": "Arbeitgeber",  "data_type": "string", "select_fields_name": null },
    "beruf":          { "label": "Beruf",        "data_type": "string", "select_fields_name": null },
    "berufsstatus":   { "label": "Berufsstatus", "data_type": "string", "select_fields_name": "berufsstatus" },
    "datum_eintritt": { "label": "Eintritt",     "data_type": "date",   "data_format": "0000-00-00", "select_fields_name": null },
    "datum_austritt": { "label": "Austritt",     "data_type": "date",   "data_format": "0000-00-00", "select_fields_name": null }
  },
  "select_fields": {
    "berufsstatus": [
      { "value": "Angestellt",                       "display": "Angestellt" },
      { "value": "Angestellt im öffentlichen Dienst","display": "Angestellt im öffentlichen Dienst" },
      { "value": "Arbeiter",                         "display": "Arbeiter" },
      { "value": "Arbeitssuchend",                   "display": "Arbeitssuchend" },
      { "value": "Auszubildender",                   "display": "Auszubildender" },
      { "value": "Beamter",                          "display": "Beamter" },
      { "value": "Beherrschender GGF",               "display": "Beherrschender GGF" },
      { "value": "Elternzeit",                       "display": "Elternzeit" },
      { "value": "Freiberufler",                     "display": "Freiberufler" },
      { "value": "Geschäftsführer",                  "display": "Geschäftsführer" },
      { "value": "Nicht berufstätig",                "display": "Nicht berufstätig" },
      { "value": "Selbständig",                      "display": "Selbständig" },
      { "value": "Rentner",                          "display": "Rentner" },
      { "value": "Student",                          "display": "Student" },
      { "value": "Vorstand",                         "display": "Vorstand" }
    ]
  }
}

GET/v3/customers/<kid>/jobs Im Playground testen ↗

POST/v3/customers/<kid>/jobs Im Playground testen ↗

GET/v3/customers/<kid>/jobs/<id> Im Playground testen ↗

PATCH/v3/customers/<kid>/jobs/<id> Im Playground testen ↗

DELETE/v3/customers/<kid>/jobs/<id> Im Playground testen ↗

Query-Parameter

kid (im Pfad, nicht als Query) — Customer-ID des Parents. Bei Sub-Resources steht die ID jetzt im URL-Pfad statt im Query-String.
page — Seitenindex (Default 1).
limit — Items pro Seite (Default 50, Max 5000).
with_schema — Feld-Schema im Response mitliefern. Default false (opt-in).

Beispiel — Berufsangaben abfragen

bash

curl 'https://www.api.i-planner.app/v3/customers/12345/jobs' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

{
  "page": 1,
  "page_size": 50,
  "total": 1,
  "items": [
    {
      "id": 43,
      "kid": 1485504800,
      "arbeitgeber": "ACME GmbH",
      "beruf": "Geschäftsführer",
      "berufsstatus": "Geschäftsführer",
      "datum_eintritt": "2010-04-01",
      "datum_austritt": null
    }
  ]
}

Beispiel — Beruf anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/jobs' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arbeitgeber": "ACME GmbH",
    "beruf": "Senior Developer",
    "berufsstatus": "Angestellt",
    "datum_eintritt": "2024-01-15"
  }'

// Body enthält nur die neue `id` — voller Datensatz separat via
// `GET /v3/customers/<kid>/jobs/<id>` abrufen.
{ "success": true, "id": 83002 }

Beispiel — Berufseintrag löschen

bash

curl -X DELETE 'https://www.api.i-planner.app/v3/customers/12345/jobs/83001' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

// Soft-Delete — siehe Addresses oben für Details.
{
  "success": true,
  "deleted": true,
  "soft_deleted": true,
  "id": 83001
}

Contracts

Versicherungs-, Finanzierungs- und sonstige Verträge eines Customers. Genaue Felder hängen vom Tenant-Schema ab.

json

{
  "id": 90001,
  "kid": 12345,
  "nummer": "V-2024-00471",          // interne Vertragsnummer
  "gesellschaft": "Allianz",          // Versicherer / Anbieter
  "sparte": "krankenversicherung",    // siehe Schema-Tab
  "tarif": "Vital BestMed",
  "beitrag": 87.50,                   // periodischer Beitrag in EUR
  "intervall": "monatlich",           // monatlich | jaehrlich | einmalig
  "beginn": "2024-01-01",
  "ende": null,                       // null = unbefristet
  "status": "aktiv",                  // aktiv | gekuendigt | ruht
  "insert_datum": "2024-01-15",
  "edit_datum": "2024-06-02"
}

{
  "fields": {
    "nummer":       { "label": "Vertragsnummer", "data_type": "string", "select_fields_name": null },
    "gesellschaft": { "label": "Gesellschaft",   "data_type": "string", "select_fields_name": "gesellschaften" },
    "sparte":       { "label": "Sparte",         "data_type": "string", "select_fields_name": "sparten" },
    "tarif":        { "label": "Tarif",          "data_type": "string", "select_fields_name": null },
    "beitrag":      { "label": "Beitrag",        "data_type": "number", "data_format": "0.00",      "select_fields_name": null },
    "intervall":    { "label": "Intervall",      "data_type": "string", "select_fields_name": "intervalle" },
    "beginn":       { "label": "Beginn",         "data_type": "string", "data_format": "0000-00-00", "select_fields_name": null },
    "ende":         { "label": "Ende",           "data_type": "string", "data_format": "0000-00-00", "select_fields_name": null },
    "status":       { "label": "Status",         "data_type": "string", "select_fields_name": "vertragsstatus" }
  },
  "select_fields": {
    "sparten": [
      { "value": "krankenversicherung", "display": "Krankenversicherung" },
      { "value": "lebensversicherung",  "display": "Lebensversicherung" },
      { "value": "haftpflicht",          "display": "Haftpflicht" }
    ],
    "intervalle": [
      { "value": "monatlich",  "display": "Monatlich" },
      { "value": "jaehrlich",  "display": "Jährlich" },
      { "value": "einmalig",   "display": "Einmalig" }
    ],
    "vertragsstatus": [
      { "value": "aktiv",      "display": "Aktiv" },
      { "value": "gekuendigt", "display": "Gekündigt" },
      { "value": "ruht",       "display": "Ruht" }
    ]
  }
}

Customer-scoped (Listing + Create only):

GET/v3/customers/<kid>/contracts Im Playground testen ↗

POST/v3/customers/<kid>/contracts Im Playground testen ↗

Read / Update / Delete laufen über die globally-unique Contract-id top-level — siehe Verträge für die vollständige API:

GET /v3/contracts/<id> — Vertrag abrufen
PATCH /v3/contracts/<id> — Vertrag aktualisieren
DELETE /v3/contracts/<id> — Vertrag löschen

Zusätzliche Helper-Endpoints

GET /v3/system/sparten — Liste der verfügbaren Sparten als Reference-Daten. Kein kid-Parameter, weil global. Scope v3:system:read (siehe System).
/v3/contracts/<id>/persons und /v3/contracts/<id>/tariffs — Sub-Resources versicherte Personen und Tarif-Optionen, top-level über die Contract-id.

Query-Parameter (List)

kid (im Pfad, nicht als Query) — Customer-ID des Parents.
page, limit, with_schema — wie bei den direkten Unterressourcen.

Beispiel — Verträge eines Kunden abfragen

bash

curl 'https://www.api.i-planner.app/v3/customers/12345/contracts' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

{
  "page": 1, "page_size": 50, "total": 2,
  "items": [
    { "id": 90001, "kid": 12345, "nummer": "V-2024-00471", "gesellschaft": "Allianz", "sparte": "krankenversicherung", "beitrag": 87.50, "intervall": "monatlich", "status": "aktiv" },
    { "id": 90002, "kid": 12345, "nummer": "L-2023-00198", "gesellschaft": "Cosmos Direkt", "sparte": "lebensversicherung", "beitrag": 145.00, "intervall": "monatlich", "status": "aktiv" }
  ]
}

Beispiel — Vertrag anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/contracts' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nummer": "H-2026-00012",
    "gesellschaft": "HUK24",
    "sparte": "haftpflicht",
    "beitrag": 7.90,
    "intervall": "monatlich",
    "beginn": "2026-06-01"
  }'

{ "success": true, "id": 90003 }

Beispiel — Vertrag löschen (top-level über die globally-unique id)

bash

curl -X DELETE 'https://www.api.i-planner.app/v3/contracts/90001' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

{ "success": true, "deleted": true, "soft_deleted": true, "id": 90001 }

Damages

Schadensfälle / Schadenmeldungen am Customer.

Scopes: v3:damages:read (List + Get) · v3:damages:write (Create + Patch + Delete).

json

{
  "id": 91001,
  "kid": 12345,
  "schadennummer": "S-2026-00018",
  "vertrag_id": 90001,              // optionale Verknüpfung zum Vertrag
  "art": "haftpflicht",
  "datum": "2026-04-21",            // Schadendatum
  "schadenshoehe": 1250.00,
  "status": "in_bearbeitung",       // gemeldet | in_bearbeitung | reguliert | abgelehnt
  "beschreibung": "Wasserschaden in der Küche",
  "insert_datum": "2026-04-22",
  "edit_datum": "2026-04-23"
}

{
  "fields": {
    "schadennummer": { "label": "Schadennummer",  "data_type": "string", "select_fields_name": null },
    "vertrag_id":    { "label": "Vertrag",         "data_type": "number", "select_fields_name": null },
    "art":           { "label": "Art",             "data_type": "string", "select_fields_name": "schadensarten" },
    "datum":         { "label": "Schadendatum",   "data_type": "string", "data_format": "0000-00-00", "select_fields_name": null },
    "schadenshoehe": { "label": "Schadenshöhe",   "data_type": "number", "data_format": "0.00",       "select_fields_name": null },
    "status":        { "label": "Status",          "data_type": "string", "select_fields_name": "schadensstatus" }
  },
  "select_fields": {
    "schadensstatus": [
      { "value": "gemeldet",         "display": "Gemeldet" },
      { "value": "in_bearbeitung",   "display": "In Bearbeitung" },
      { "value": "reguliert",        "display": "Reguliert" },
      { "value": "abgelehnt",        "display": "Abgelehnt" }
    ]
  }
}

Customer-scoped (Listing + Create only):

GET/v3/customers/<kid>/damages Im Playground testen ↗

POST/v3/customers/<kid>/damages Im Playground testen ↗

Read / Update / Delete laufen über die globally-unique Schaden-id top-level — siehe Schäden für die vollständige API.

Query-Parameter (List) — kid (im Pfad), page, limit, with_schema.

Beispiel — Schaden anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/damages' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vertrag_id": 90001,
    "art": "haftpflicht",
    "datum": "2026-04-21",
    "schadenshoehe": 1250.00,
    "beschreibung": "Wasserschaden in der Küche"
  }'

{ "success": true, "id": 91002 }

Finances

Finanz-Positionen am Customer (Einnahmen, Ausgaben, Vermögen, Schulden).

Scopes: v3:finances:read (List + Get) · v3:finances:write (Create + Patch + Delete).

json

{
  "id": 92001,
  "kid": 12345,
  "art": "einnahme",                  // einnahme | ausgabe | vermoegen | verbindlichkeit
  "kategorie": "gehalt",
  "betrag": 4500.00,
  "intervall": "monatlich",
  "beginn": "2024-01-01",
  "ende": null,
  "beschreibung": "Grundgehalt Festanstellung",
  "insert_datum": "2024-01-15",
  "edit_datum": "2024-01-15"
}

{
  "fields": {
    "art":          { "label": "Art",          "data_type": "string", "select_fields_name": "finanz_art" },
    "kategorie":    { "label": "Kategorie",    "data_type": "string", "select_fields_name": "finanz_kategorie" },
    "betrag":       { "label": "Betrag",       "data_type": "number", "data_format": "0.00", "select_fields_name": null },
    "intervall":    { "label": "Intervall",    "data_type": "string", "select_fields_name": "intervalle" }
  },
  "select_fields": {
    "finanz_art": [
      { "value": "einnahme",        "display": "Einnahme" },
      { "value": "ausgabe",         "display": "Ausgabe" },
      { "value": "vermoegen",       "display": "Vermögen" },
      { "value": "verbindlichkeit", "display": "Verbindlichkeit" }
    ]
  }
}

Customer-scoped (Listing + Create only):

GET/v3/customers/<kid>/finances Im Playground testen ↗

POST/v3/customers/<kid>/finances Im Playground testen ↗

Read / Update / Delete laufen über die globally-unique Finanz-id top-level — siehe Finanzen für die vollständige API.

Query-Parameter (List) — kid (im Pfad), page, limit, with_schema.

Beispiel — Finanz-Position anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/finances' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "art": "ausgabe",
    "kategorie": "miete",
    "betrag": 1450.00,
    "intervall": "monatlich"
  }'

{ "success": true, "id": 92002 }

Goals

Finanz-/Lebensziele eines Customers (Altersvorsorge, Hauskauf, Studium der Kinder …).

Scopes: v3:goals:read (List + Get) · v3:goals:write (Create + Patch + Delete).

json

{
  "id": 93001,
  "kid": 12345,
  "titel": "Altersvorsorge",
  "kategorie": "altersvorsorge",      // siehe Schema-Tab
  "zielbetrag": 250000.00,
  "zieldatum": "2055-01-01",
  "prioritaet": 1,                    // 1 = hoch, 3 = niedrig
  "status": "in_planung",             // in_planung | aktiv | erreicht | verworfen
  "beschreibung": "Private Rentenversicherung + ETF-Sparplan",
  "insert_datum": "2024-01-15",
  "edit_datum": "2026-03-12"
}

{
  "fields": {
    "titel":      { "label": "Titel",       "data_type": "string", "select_fields_name": null },
    "kategorie":  { "label": "Kategorie",   "data_type": "string", "select_fields_name": "goal_kategorie" },
    "zielbetrag": { "label": "Zielbetrag",  "data_type": "number", "data_format": "0.00",       "select_fields_name": null },
    "zieldatum":  { "label": "Zieldatum",   "data_type": "string", "data_format": "0000-00-00", "select_fields_name": null },
    "prioritaet": { "label": "Priorität",   "data_type": "number", "select_fields_name": null },
    "status":     { "label": "Status",      "data_type": "string", "select_fields_name": "goal_status" }
  },
  "select_fields": {
    "goal_kategorie": [
      { "value": "altersvorsorge", "display": "Altersvorsorge" },
      { "value": "immobilie",      "display": "Immobilie" },
      { "value": "ausbildung",     "display": "Ausbildung" },
      { "value": "anschaffung",    "display": "Anschaffung" }
    ],
    "goal_status": [
      { "value": "in_planung", "display": "In Planung" },
      { "value": "aktiv",      "display": "Aktiv" },
      { "value": "erreicht",   "display": "Erreicht" },
      { "value": "verworfen",  "display": "Verworfen" }
    ]
  }
}

Customer-scoped (Listing + Create only):

GET/v3/customers/<kid>/goals Im Playground testen ↗

POST/v3/customers/<kid>/goals Im Playground testen ↗

Read / Update / Delete laufen über die globally-unique Ziel-id top-level — siehe Ziele für die vollständige API.

Query-Parameter (List) — kid (im Pfad), page, limit, with_schema.

Beispiel — Ziel anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/goals' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "titel": "Hauskauf",
    "kategorie": "immobilie",
    "zielbetrag": 400000.00,
    "zieldatum": "2030-06-01",
    "prioritaet": 1
  }'

{ "success": true, "id": 93002 }

Aktivitäten & Kollaboration — generische Anhang-Ressourcen am Customer: Kommentare, Dokumente und Follower.

Comments

Freitext-Kommentare am Customer. Full-CRUD: List, Get, Create, Patch, Delete.

Scopes: v3:customers:read (List + Get) · v3:customers:write (Create + Patch + Delete).

json

{
  "id": 95001,
  "kid": 12345,
  "text": "Kunde hat per E-Mail nach einer Vertragsanpassung gefragt.",
  "autor_kid": 7,                     // ausdrücklich angegebener Berater; 0 = Organisationstoken
  "autor_name": "Anna Berater",
  "insert_datum": "2026-05-12T14:23:00.000Z"
}

GET/v3/customers/<kid>/comments Im Playground testen ↗

POST/v3/customers/<kid>/comments Im Playground testen ↗

GET/v3/customers/<kid>/comments/<id> Im Playground testen ↗

PATCH/v3/customers/<kid>/comments/<id> Im Playground testen ↗

DELETE/v3/customers/<kid>/comments/<id> Im Playground testen ↗

Query-Parameter (List) — kid (Pflicht), page, limit. Comments haben kein konfigurierbares Schema; with_schema wird ignoriert.

Beim POST ist text Pflicht. Optional kann autor_kid die KID eines aktiven Beraters derselben Organisation angeben. Die API prüft die Berater-Mitgliedschaft; eine unbekannte, gelöschte oder inaktive KID wird mit HTTP 400 (invalid_author_kid) abgelehnt. Ohne autor_kid erscheint der Name des Organisationstokens als Kommentarautor (autor_kid: 0). Das Änderungsprotokoll nennt in beiden Fällen den ausführenden Token. PATCH ändert nur den Text und lässt den beim POST bestimmten Autor bestehen.

Beispiel — Kommentar anlegen

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/comments' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Telefonat: Kunde möchte Beratungstermin im Juni.",
    "autor_kid": 7
  }'

{ "success": true, "id": 95002 }

Documents

Dokumente am Customer (PDF, Bilder, beliebige Datei-Typen). Werden in einer Ordnerstruktur abgelegt; die Default-Ordner Dokumente wird beim Customer-Create automatisch angelegt.

Scopes: v3:documents:read (List + Get + Folders) · v3:documents:write (Create + Patch + Delete).

json

{
  "id": 96001,
  "kid": 12345,
  "name": "Versicherungsschein-Allianz-2024.pdf",
  "mime_type": "application/pdf",
  "dateigroesse": 142315,             // Bytes
  "ordner_id": 5001,                  // Verweis auf einen Folder, siehe GET .../folders
  "ordner_name": "Verträge",
  "beschreibung": "KV-Police Vital BestMed",
  "insert_datum": "2024-01-16",
  "edit_datum": "2024-01-16"
}

// Antwort-Item von GET /v3/customers/<kid>/documents/folders
{
  "id": 5001,
  "kid": 12345,
  "name": "Verträge",
  "parent_id": null,                  // null = Root-Ordner, sonst Parent-Folder-ID
  "anzahl_dokumente": 7
}

Customer-scoped (Listing + Create only):

GET/v3/customers/<kid>/documents Im Playground testen ↗

POST/v3/customers/<kid>/documents Im Playground testen ↗

GET/v3/customers/<kid>/documents/folders Im Playground testen ↗

Read / Update / Delete laufen über die globally-unique Dokument-id top-level — siehe Dokumente für die vollständige API.

Query-Parameter (List) — kid (im Pfad), page, limit. Optional ordner_id zum Filtern auf einen bestimmten Ordner.

Beispiel — Dokument hochladen (Datei-Inhalt als Base64-String im inhalt-Feld)

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/documents' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vertragsanlage.pdf",
    "mime_type": "application/pdf",
    "ordner_id": 5001,
    "inhalt": "JVBERi0xLjQKJeLjz9MK…"
  }'

{ "success": true, "id": 96002 }

Followers

Mitarbeiter, die einen Customer „abonniert" haben — bekommen Notifications bei Änderungen. Keine eigenen Datensatz-Felder außer der User-Verknüpfung.

Scopes: v3:customers:read (List) · v3:customers:write (Create + Delete).

json

{
  "id": 97001,
  "kid": 12345,                       // beobachteter Customer
  "user_kid": 7,                      // Mitarbeiter, der folgt
  "user_name": "Helmut Leier",
  "insert_datum": "2026-04-20"
}

GET/v3/customers/<kid>/followers Im Playground testen ↗

POST/v3/customers/<kid>/followers Im Playground testen ↗

DELETE/v3/customers/<kid>/followers/<id> Im Playground testen ↗

Query-Parameter (List) — kid (Pflicht), page, limit.

Beispiel — Customer abonnieren

bash

curl -X POST 'https://www.api.i-planner.app/v3/customers/12345/followers' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_kid": 7
  }'

{ "success": true, "id": 97002 }

Anhänge an CRM-Objekten

Comments, Documents, Followers und Tags lassen sich auch an einem konkreten CRM-Objekt anlegen — z. B. ein Kommentar zu einem Vertrag, ein Dokument an einem Schaden.

Pfad-Pattern für Sub-Domains mit globally-unique id (contracts, damages, finances, goals, contact-persons, portals):

/v3/<section>/<sectionId>/<resource>[/<id>]

Pfad-Pattern für Identity — eine customer-direkte Sub-Resource ohne eigenen Top-Level:

/v3/customers/<kid>/identity/<sectionId>/<resource>[/<id>]

<section> — contracts, damages, finances, goals, contact-persons, portals (oder customers/<kid>/identity)
<sectionId> — Integer-ID des konkreten Section-Objekts
<resource> — comments, documents, followers oder tags

Scopes: je nach <resource> — v3:customers:* für comments / followers / tags an Customer-direkten Subs, v3:documents:* für documents. Ein Parent-Scope wie v3:contracts:read ersetzt niemals den Dokument-Scope. Der Parent-Datensatz selbst bleibt an seine eigene Scope-Familie gebunden.

Felder, Methods und Response-Bodies sind identisch zu den Customer-Level-Pendants oben — der einzige Unterschied: kein kid-Body-Feld, kein kid-Query-Param. Beides ergibt sich aus dem Pfad. POST/PATCH-Bodies mit kid-Feld werden mit 400 body_kid_forbidden abgelehnt.

bash

curl -X POST 'https://www.api.i-planner.app/v3/contracts/90001/comments' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Beitragserhöhung 2026 vorgemerkt." }'

{ "success": true, "id": 95012 }