Benutzer

Benutzer deiner Organisation — User-Stammdaten, Rollen, Lizenzen und Aktivierungs-Status. Strukturell identisch zu Customers (gleiche Stammdaten-Felder, gleiche Sub-Resources), unter eigenem API-Pfad und eigener Scope-Familie `v3:users:*`.

Zuletzt geprüft: 14. September 2026

Übersicht

Ein Benutzer ist ein interner Account deiner Organisation — Mitarbeiter, Berater, Administrator. Benutzer haben dieselben Stammdaten und Sub-Resources wie Customers (Adressen, Bankverbindungen, Kontaktdaten, …) — nur unter eigenem API-Pfad und eigener Scope-Familie:

Gleiche Sub-Resources wie Customers (Addresses, Banking, Contacts, …) — 10 direkte Familien plus Aktivitäten und Links parent-scoped (12 Familien insgesamt).
Eigene Scope-Familie v3:users:* — Sub-Resource-Endpoints nutzen NICHT die Per-Resource-Scopes von Customers, sondern fallen unter den v3:users:*-Bucket. Ausnahme: Aktivitäten am User laufen weiterhin auf v3:activities:* (eigene Daten-Domäne).
Keine Verträge, Schäden, Finanzen, Ziele am Benutzer — diese CRM-Objekte hängen ausschließlich an Customers.

Die CRUD-Mechanik (Pagination, Schema-Tab, Single-vs-Batch-POST, Soft-Delete, Error-Codes) ist 1:1 dieselbe wie bei Customers — auf dieser Seite wird sie nicht erneut ausgebreitet.

Scopes

Benutzer-Stammdaten und direkte Sub-Resources verwenden v3:users:read|write. Dokumente und Aktivitäten behalten ihre eigenen Scopes:

Endpoint-Familie	Scope
`GET /v3/users` / `GET /v3/users/<id>`	`v3:users:read`
`POST /v3/users`	`v3:users:write`
`PATCH /v3/users/<id>`	`v3:users:write`
`DELETE /v3/users/<id>`	`v3:users:write`
Direkte Sub-Resource `GET`-Endpoints	`v3:users:read`
Direkte Sub-Resource `POST`/`PATCH`/`DELETE`	`v3:users:write`
Dokumente unter `/v3/users/{kid}/documents`	`v3:documents:read` / `v3:documents:write`
Aktivitäten unter `/v3/users/{kid}/activities`	`v3:activities:read` / `v3:activities:write`

Auth-Mechanik und Fehler siehe Authentifizierung. Vollständige Scope-Referenz mit Token-Beispielen: Scopes.

Pagination & Limits

Identisch zu Customers > Pagination & Limits — page, limit, Default 50, Max 5000, Envelope { page, page_size, total, items }.

Schema

json

{
  "id": 4001,
  "anrede": "Herr",
  "vorname": "Helmut",
  "name": "Leier",
  "geb": "1970-01-15",
  "email": "h.leier@example.de",
  "rolle": "vertrieb",                // siehe select_fields.users.rollen
  "lizenz": true,                     // hat der User eine aktive Lizenz?
  "lizenz_typ": "vollzugang",         // siehe select_fields.users.lizenztypen
  "aktiv": true,                      // false = deaktiviert, kein Login mehr
  "letzter_login": "2024-06-15T08:42:00Z",
  "insert_datum": "2023-01-15",
  "edit_datum": "2024-06-15",

  // Sub-Resources — opt-in via ?with_*=true (Default false seit Phase C, Mai 2026)
  "addresses": [ /* siehe /rest/v3/customers#addresses */ ],
  "contacts":  [ /* siehe /rest/v3/customers#contacts */ ],
  "banking":   [ /* siehe /rest/v3/customers#banking */ ]
}

// Bei `?with_schema=true` (opt-in, Default `false`) zusätzlich zum `items[]`-Array.
{
  "fields": {
    "users": {
    "rolle":      { "label": "Rolle",       "data_type": "string", "select_fields_name": "rollen" },
    "lizenz":     { "label": "Lizenz",      "data_type": "boolean", "select_fields_name": null },
    "lizenz_typ": { "label": "Lizenz-Typ",  "data_type": "string", "select_fields_name": "lizenztypen" },
    "aktiv":      { "label": "Aktiv",       "data_type": "boolean", "select_fields_name": null }
    }
  },
  "select_fields": {
    "users": {
    "rollen": [
      { "value": "vertrieb",   "display": "Vertrieb" },
      { "value": "backoffice", "display": "Backoffice" },
      { "value": "admin",      "display": "Administrator" }
    ],
    "lizenztypen": [
      { "value": "vollzugang", "display": "Vollzugang" },
      { "value": "lesezugang", "display": "Nur lesen" }
    ]
    }
  }
}

Sensitive Felder werden nie ausgeliefert. Folgende Spalten der crm_kontakte-Zeile eines Benutzers werden vom Server aus jeder Response konsequent entfernt — sowohl in GET /v3/users, GET /v3/users/<id> als auch in hydratisierten Suchergebnissen (POST /v3/search mit return: 'full'):

pass, pass_open — Passwort-Hash bzw. -Klartext
two_factor_auth, two_factor_auth_code, two_factor_auth_questions — 2FA-Geheimnisse + Sicherheitsfragen
vm_konto_provision, vm_konto_stornoreserve — Provisionskonto-Salden
vm_stornoreserve, vm_stornoreserve_prozent, vm_stornoreserve_verrechnung — Stornoreserve-Konfiguration

Die Felder existieren in der DB und sind über das interne Backoffice für Admins zugänglich; die v3-API zeigt sie aber niemandem, unabhängig vom Token-Scope. Auch ein Token mit v3:users:read bekommt diese Felder nicht.

Endpoints

Verhalten und Response-Shapes sind 1:1 wie bei Customers. Für Detail-Beispiele zu Query-Parametern, Batch-POST, Soft-Delete-Mechanik etc. siehe die entsprechenden Customer-Sektionen.

Benutzer abfragen

GET/v3/users Im Playground testen ↗

Liefert eine paginierte Liste aller Benutzer deiner Organisation. Query-Parameter und Response-Envelope identisch zu Customers abfragen.

Einzelnen Benutzer abrufen

GET/v3/users/<id> Im Playground testen ↗

Verhalten wie Customer abrufen.

Benutzer anlegen

POST/v3/users Im Playground testen ↗

Body folgt dem Customer-POST-Pattern — Single-Item oder Array (max. 100), per-item Transaktion, gescheiterte Items in failed[]. Pflicht-Felder zusätzlich: email (eindeutig pro Org). Sub-Resources im Body werden ignoriert — separate Endpoints nutzen.

bash

curl -X POST https://www.api.i-planner.app/v3/users \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "anrede": "Frau",
    "vorname": "Maria",
    "name": "Schmidt",
    "email": "m.schmidt@example.de",
    "rolle": "vertrieb",
    "lizenz": true,
    "lizenz_typ": "vollzugang"
  }'

Response: 201 mit { success, id }. Fehler: 400 email_not_unique (E-Mail existiert bereits in der Org), 400 license_quota_exceeded (Lizenzkontingent voll).

Benutzer aktualisieren

PATCH/v3/users/<id> Im Playground testen ↗

Verhalten wie Customer aktualisieren. Response: { success, updated }.

Benutzer löschen

DELETE/v3/users/<id> Im Playground testen ↗

Soft-Delete (del=1 in der Datenbank). Verhalten wie Customer löschen. Response: { success, soft_deleted, kid }.

Unterressourcen

Alle 12 Sub-Resource-Familien hängen path-scoped am Benutzer ({kid} = User-ID) und folgen demselben Pattern wie die Customer-Sub-Resources. Verhalten, Query-Parameter, Schema-Felder und Fehler-Codes sind identisch — nur der Scope wechselt auf v3:users:* (siehe Scopes oben).

Direkte Sub-Resource	Pfad	Doku am Customer-Pattern
Addresses	`/v3/users/{kid}/addresses`	Addresses
Contacts	`/v3/users/{kid}/contacts`	Contacts
Banking	`/v3/users/{kid}/banking`	Banking
Nummern	`/v3/users/{kid}/numbers`	Nummern
Identity	`/v3/users/{kid}/identity`	Identity
Jobs	`/v3/users/{kid}/jobs`	Jobs
Tags	`/v3/users/{kid}/tags`	Tags
Comments	`/v3/users/{kid}/comments`	Comments
Documents	`/v3/users/{kid}/documents`	Documents — Scope `v3:documents:*` (Cross-Domain)
Followers	`/v3/users/{kid}/followers`	Followers
Activities (List + Create scoped)	`/v3/users/{kid}/activities`	Aktivitäten — Scope `v3:activities:*`, Update/Delete top-level über `/v3/activities/{id}`
Links (List + Create + Delete scoped)	`/v3/users/{kid}/links[/{id}]`	Links — Scope `v3:users:*`

POST/PATCH dürfen kid nicht im Body führen (path ist Source-of-Truth → 400 body_kid_forbidden).

Nicht verfügbar an Benutzern: Contracts, Damages, Finances, Goals — diese CRM-Objekte hängen ausschließlich an Customers (Typ 0), nicht an Benutzern (Typ 4).

kid-Bindung: Die User-kid steht im URL-Pfad (/v3/users/{kid}/...) und ist Source-of-Truth — POST/PATCH-Body darf kid nicht enthalten (400 body_kid_forbidden). Es gibt keinen ?kid=-Query-Parameter mehr; der frühere customer-scope-style ist mit dem Path-Refactor (Mai 2026) ausgelaufen.