Kontakte, Custom Fields & Listen

Alles in WeZend hängt am Kontakt — ein Profil pro Mensch, mit Identifikatoren (E-Mail, Telefon), Attributen, Einwilligungsstatus, Event-Historie, Nachrichten und Scores.

Standard- + Custom Fields

Kontakte bringen die Standardfelder mit, die Sie erwarten (Name, E-Mail, Telefon, Land, Sprache…). Alles andere ist ein Custom Field, das Sie einmal definieren:

curl -X POST https://api.wezend.com/v1/contacts/fields \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Treuestufe" }'

Die /v1/contacts-API akzeptiert entweder einen API-Key (X-API-Key) oder eine Dashboard-Session (ein JWT aus POST /v1/auth/login) — eine serverseitige Integration nutzt den Key. Alles, was Daten anlegt oder ändert, braucht einen Key mit write-Scope; ein Key mit nur read wird mit 403 insufficient_scope abgelehnt. Der Feld-Key (loyalty_tier) wird automatisch aus dem Label abgeleitet. Einmal definiert, ist das Feld überall verfügbar — in Template-Variablen ({{loyalty_tier}}), im Segment-Builder, auf der Kontaktkarte im Dashboard und in CSV-Importen. DELETE /v1/contacts/fields/:id entfernt eine Definition wieder und behält dabei die Werte, die schon an Kontakten hängen — ein gelöschtes Feld verschwindet also aus dem Builder, statt Historie zu löschen.

Erstellen & aktualisieren

# Erstellen
curl -X POST https://api.wezend.com/v1/contacts \
  -H "X-API-Key: $WEZEND_API_KEY" -H "Content-Type: application/json" \
  -d '{ "email": "anna@example.com", "phone": "+4512345678", "first_name": "Anna", "custom_fields": { "loyalty_tier": "gold" } }'

# Aktualisieren (partiell — nur die gesendeten Felder ändern sich)
curl -X PATCH https://api.wezend.com/v1/contacts/c_123 \
  -H "X-API-Key: $WEZEND_API_KEY" -H "Content-Type: application/json" \
  -d '{ "custom_fields": { "loyalty_tier": "platinum" } }'

Kontakte werden über E-Mail/Telefon abgeglichen, sodass der doppelte Import derselben Person aktualisiert statt dupliziert.

CSV-Import

Zielgruppe → Kontakte → Importieren (oder POST /v1/contacts/import). Laden Sie die Datei hoch, ordne Ihre Spalten den Feldern zu (nicht zugeordnete Spalten können direkt zu neuen Custom Fields werden), wählen Sie die Zielliste und bestätige. Importe laufen im Hintergrund mit Fortschrittsanzeige und einem Fehlerbericht pro Zeile — eine falsche Telefonnummer in Zeile 3.481 killt nicht die anderen 50.000 Zeilen.

Listen vs. Segmente — wann man was verwendet

• Eine Liste ist statisch: Kontakte sind darin, weil Sie sie dort hineingesetzt haben (Import, Formularanmeldung, manuelles Hinzufügen). Die Mitgliedschaft ändert sich nur, wenn etwas sie hinzufügt/entfernt.
• Ein Segment ist live: eine Regel ("ausgegeben > 500 € UND 30 Tage inaktiv"), in die Kontakte automatisch ein- und ausfließen, wenn sich ihre Daten ändern.

Faustregel: Listen für Herkunft ("Frühjahrsmesse-Leads 2026"), Segmente für Zustand ("aktuell mit Abwanderungsrisiko"). Kampagnen und Journeys akzeptieren beide.

Die Listen-API

Listen nutzen dieselben zwei Credentials wie Kontakte — einen API-Key (X-API-Key) oder ein Dashboard-JWT. Alles unten außer den Lesezugriffen ist ein Schreibzugriff, ein Key mit nur read-Scope bekommt also 403 insufficient_scope.

# Eine Liste anlegen
curl -X POST https://api.wezend.com/v1/lists \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Frühjahrsmesse-Leads 2026", "description": "Standscans" }'

# Einen bestehenden Kontakt hinzufügen
curl -X POST https://api.wezend.com/v1/lists/$LIST_ID/contacts \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "c_123" }'

# Eine CSV direkt in die Liste importieren (multipart, max. 50 MB)
curl -X POST https://api.wezend.com/v1/lists/$LIST_ID/import \
  -H "X-API-Key: $WEZEND_API_KEY" \
  -F "file=@leads.csv"

GET /v1/lists und GET /v1/lists/:id lesen sie, PATCH /v1/lists/:id benennt eine um, PATCH /v1/lists/:id/favorite heftet sie im Dashboard an, und DELETE /v1/lists/:id sowie DELETE /v1/lists/:id/contacts/:contactId entfernen eine Liste oder eine einzelne Mitgliedschaft. Einen Kontakt zweimal hinzuzufügen ist ein No-op statt eines Fehlers — ein erneut ausgeführter Import dupliziert also niemanden.