Personyze Wiki Personyze Wiki docs
Deutsch
Open Personyze
Docs/ Entwickler/ REST-API: Objektreferenz
Entwickler

REST-API: Objektreferenz

Jedes Objekt der Personyze-REST-API mit Zweck, Methoden, Spalten, indexierten Spalten und Beispielen.

23 min read Updated 3 Wochen ago

Referenz aller Objekte, die die Personyze-REST-API bereitstellt. Jeder Abschnitt unten behandelt ein Objekt: seinen Zweck, die unterstützten HTTP-Methoden, Spalten (mit Hinweisen zu Typ und Indexierung) und sofort nutzbare curl -Beispiele.

Voraussetzungen — lesen Sie diese zuerst, falls noch nicht geschehen:

Objektverzeichnis

Klicken Sie auf ein Objekt, um zu seinem Abschnitt zu springen. Jeder Abschnitt hat eine eigene Anker-URL — Sie können direkt auf die Referenz jedes Objekts verlinken.

CRUD-Inhalte (Lesen/Schreiben)

Enthalten Ihre Kampagnen, Zielgruppe, Katalog und Konfiguration. Volles CRUD für External API user und höher.

usersKundenprofile. Spaltennamen sind dynamisch.
user_listsBenannte Nutzerlisten (manuell oder importiert).
user_list_usersZugehörigkeit von Nutzern zu user_lists.
actionsPersonalisierungsaktionen. Über REST derzeit nur lesbar.
conditionsZielgruppenbedingungen. Über REST derzeit nur lesbar.
placeholdersDOM-Platzhalter-Container (wo Aktionen rendern).
containers_grab_variableDOM-/JS-Werte zurück ins Besucherprofil übernehmen.
productsZeilen des Produktkatalogs. Spaltennamen sind dynamisch.
articlesZeilen des Artikelkatalogs. Spaltennamen sind dynamisch.

Interaktionen / Ereignisse (überwiegend Schreiben)

Nur angehängte Protokolle von Besucherinteraktionen. Überwiegend von SDKs und Backend-Integrationen genutzt.

products_interactionsEreignisse Ansehen / Warenkorb / Kauf bei Produkten.
eventsAllgemeines Ereignisprotokoll (nur lesbar).
formsProtokoll der Formulareinsendungen (nur lesbar).
doBefehlsverteiler nach dem Prinzip „Fire and Forget“.

Berichte / Archiv (nur lesbar)

sessions_archiveEine Zeile pro Besuchersitzung, mit Metadaten zu Standort/Gerät/Browser.
user_interestsAbgeleitete Interessen, Kategorien, Tags pro Nutzer.
products_stats_*Interaktionszähler pro Produkt über sechs gleitende Zeitfenster.
summary_actionsTäglich aggregierte KPI pro Aktion.

Hilfen für Tracker / SDK

Vom JS-Tracker, nativen SDKs und Integrationen zum Selbststart genutzt. Von Nutzern der REST-API normalerweise nicht direkt aufgerufen.

tracker_codeLiefert das JS-Snippet zum Einbetten in eine Kundenseite (HTML-Ausgabe).

users

Kundenprofile. Jede Zeile ist ein Besucher oder Kunde. Spaltennamen sind dynamisch — über die dokumentierten Verwaltungsspalten hinaus können Sie beliebige eigene Schlüssel/Werte speichern, die Ihr Konto braucht.

GET POST PUT DELETE
✅ ✅ ✅ ✅

Identifizierende / Verwaltungsspalten

Spalte Hinweise
user_id Interner Primärschlüssel von Personyze. Wird beim Einfügen automatisch vergeben. Indexiert.
internal_id Ihre externe Kennung (CRM-ID, Konto-ID, SKU). Indexiert.
fb_id Facebook-Nutzer-ID. Indexiert.
email E-Mail-Adresse des Besuchers. Indexiert.
last_session_time Unix-Sekunden. Indexiert.
data_last_modified Unix-Sekunden. Indexiert.
session_counter Bisher gezählte Sitzungen dieses Nutzers insgesamt.

Gängige Profilfelder (benutzerdefiniert)

first_name, middle_name, last_name, sex, birthday, timezone, current_city, current_state, current_country, religion, political, interests, relationship_status, education_year, plus custom_t_1…custom_t_6 (Text), custom_i_1…custom_i_4 (Ganzzahl), custom_f_1…custom_f_2 (Gleitkomma), custom_d_1, custom_d_2 (Datum) — und alle weiteren Felder, die Sie in Ihrem Konto konfiguriert haben.

Beispiele

# Lookup by your external id
curl 'https://api:KEY@app.personyze.com/rest/users/where/internal_id=42'
# Recent active visitors (last 7 days)
curl 'https://api:KEY@app.personyze.com/rest/users
        /where/last_session_time>1730000000
        /columns/user_id,internal_id,email,first_name,last_session_time
        /order_by_desc/last_session_time
        /limit/1000'
# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/users' \
     -H 'Content-Type: application/json' \
     -d '{"internal_id":"acct-987","email":"alice@example.com","first_name":"Alice","custom_field_x":"vip"}'
# → 5712334  (new user_id)
# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/users/where/internal_id=acct-987' \
     -H 'Content-Type: application/json' \
     -d '{"first_name":"Alicia"}'
# → 1  (rows affected)

Indexierte Spalten / Scan-Grenzen

GET /rest/users ohne where erfordert order_by auf einer indexierten Spalte — user_id, last_session_time, data_last_modified, fb_id, emailoder internal_id. Andernfalls: 400 Cannot do this operation on whole table.

Drosselung

POST /rest/users wird pro Personyze-Konto serialisiert: höchstens ein laufendes Einfügen gleichzeitig. Anfragen, die länger als 1 Sekunde warten, werden abgelehnt mit 400 Too many simultaneous requests — wiederholen Sie mit exponentiellem Backoff.

user_lists

Benannte Nutzerlisten (z. B. „VIPs“, „Newsletter-Abonnenten“). Eine Zeile pro Liste. Die Mitgliedschaft liegt in einem separaten Objekt — siehe user_list_users.

GET POST PUT DELETE
✅ ✅ ✅ ✅

Spalten

Spalte Hinweise
id Primärschlüssel. Automatisch vergeben.
name Anzeigename der Liste. Indexiert.

Beispiele

# All lists
curl 'https://api:KEY@app.personyze.com/rest/user_lists'
# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_lists' \
     -H 'Content-Type: application/json' \
     -d '{"name":"VIPs"}'
# → 17
# Rename
curl -X PUT 'https://api:KEY@app.personyze.com/rest/user_lists/17' \
     -H 'Content-Type: application/json' \
     -d '{"name":"VIP customers"}'
# → 1
# Delete (also clears all memberships in user_list_users via FK cascade)
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/user_lists/17'
# → 1

user_list_users

Mitgliedschaft: welche Nutzer zu welchen user_listsgehören. Eine Zeile pro (user_list_id, user_id) -Paar.

GET POST PUT DELETE
✅ ✅ — ✅

POST akzeptiert entweder eine vorhandene user_idoder einen Suchschlüssel (user_internal_id, user_email) — die API löst ihn zu einer user_idauf und legt bei Bedarf eine Platzhalterzeile in users an.

Spalten

Spalte Hinweise
user_list_id FK → user_lists.id. Teil des zusammengesetzten Schlüssels.
user_id FK → users.user_id. Teil des zusammengesetzten Schlüssels.

Zusätzliche Felder im POST-Body (serverseitig zu user_id aufgelöst und dann verworfen)

Feld Wird aufgelöst zu
user_internal_id user_id für den Nutzer mit dieser internal_id. Legt den Nutzer an, falls er fehlt.
user_email user_id für den Nutzer mit dieser email. Legt den Nutzer an, falls er fehlt.

Beispiele

# Members of list 17
curl 'https://api:KEY@app.personyze.com/rest/user_list_users/where/user_list_id=17/limit/1000'
# Add by user_id
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_list_users' \
     -H 'Content-Type: application/json' \
     -d '{"user_list_id":17,"user_id":5712334}' 
# Add by external id (auto-creates a users row if needed)
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_list_users' \
     -H 'Content-Type: application/json' \
     -d '{"user_list_id":17,"user_internal_id":"acct-987"}' 
# Add by email
curl -X POST 'https://api:KEY@app.personyze.com/rest/user_list_users' \
     -H 'Content-Type: application/json' \
     -d '{"user_list_id":17,"user_email":"alice@example.com"}' 
# Remove
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/user_list_users
        /where/user_list_id=17&user_id=5712334'

actions

Personalisierungsaktionen — was Ihre Kampagnen tun: HTML rendern, ein Pop-up zeigen, eine E-Mail senden, eine Benachrichtigung pushen usw. Über REST derzeit nur lesbar (Anlegen/Bearbeiten über die Oberfläche).

GET POST PUT DELETE
✅ — — —

Spalten

Spalte Hinweise
id Primärschlüssel.
version_tag production oder testing.
name Anzeigename der Aktion.
type_id Der Aktionstyp (HTML / Pop-up / E-Mail / Push / …). Aufgelöst aus dem zugrunde liegenden action_js_id.
placeholders JSON-Array der Platzhalter-IDs, auf die die Aktion zielt.
content_type MIME-Typ / Art des Inhalts (aus actions_js).
content_param Name des JS-Parameterschlüssels, dessen Wert der renderbare Inhalt ist.
content_begin Berechnet: öffnendes Fragment des gerenderten Inhalts (nach Ersetzung des Wrappers).
content_end Berechnet: schließendes Fragment.
presenting_rules JSON: Regeln für Timing / Häufigkeit.
libs_app App-Bibliotheken, von denen die Aktion abhängt.

Beispiele

# All production actions
curl 'https://api:KEY@app.personyze.com/rest/actions
        /where/version_tag=production
        /columns/id,name,type_id,placeholders'
# One action's full content
curl 'https://api:KEY@app.personyze.com/rest/actions/where/id=42
        /columns/id,name,content_type,content_param,content_begin,content_end'

conditions

Zielgruppenbedingungen — das Wann von Kampagnen. Über REST nur lesbar.

GET POST PUT DELETE
✅ — — —

Spalten

Spalte Hinweise
id Primärschlüssel.
name Anzeigename der Bedingung.

Beispiele

# All tracker/offline conditions
curl 'https://api:KEY@app.personyze.com/rest/conditions/limit/1000'

placeholders

Container vom Typ placeholder — DOM-Plätze, an denen Aktionen Inhalte rendern. Verwalten Sie den Katalog der für Ihre Website definierten Platzhalter.

GET POST PUT DELETE
✅ ✅ ✅ ✅

Spalten

Spalte Hinweise
id Primärschlüssel.
name Anzeigename.
html_id DOM-Selektor / ID, an der der Platzhalter eingebunden wird.
units_count_max Maximale Zahl von Aktionseinheiten, die diesen Platzhalter füllen können. Standard 1.

Beispiele

# All placeholders
curl 'https://api:KEY@app.personyze.com/rest/placeholders'
# One
curl 'https://api:KEY@app.personyze.com/rest/placeholders/14'
# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/placeholders' \
     -H 'Content-Type: application/json' \
     -d '{"name":"Hero banner","html_id":"#hero","units_count_max":1}'
# → 88
# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/placeholders/88' \
     -H 'Content-Type: application/json' \
     -d '{"units_count_max":3}'
# → 1
# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/placeholders/88'
# → 1

Bereich des Endpunkts.Der Handler begrenzt alle Abfragen auf container_types='placeholder', sodass andere Container-Typen (z. B. „grab variable“) über diesen Endpunkt nicht sichtbar sind — siehe containers_grab_variable.

containers_grab_variable

Container vom Typ „Grab variable“ — übernehmen DOM-/JS-Werte von der Seite des Besuchers zurück ins Besucherprofil. Jeder Container sagt: „Beobachte diese Variable / dieses DOM-Element; sobald es erscheint, erfasse es als Profilfeld.“

GET POST PUT DELETE
✅ ✅ ✅ ✅

Spalten

Spalte Hinweise
id Primärschlüssel.
name Anzeigename.
is_active 1 / 0.
variable_path DOM-Pfad oder JS-Ausdruck, der erfasst wird.
mask Optionaler Regex/Vorlage, angewendet auf die erfasste Zeichenkette.
constant_value Optionaler Fallback / erzwungener Wert.
watch_variable Erneut erfassen, sobald sich die Variable ändert (1 / 0).
profile_column Profilspalte, in die der Wert geschrieben wird.

Beispiele

# All grab-variable containers
curl 'https://api:KEY@app.personyze.com/rest/containers_grab_variable'
# Create
curl -X POST 'https://api:KEY@app.personyze.com/rest/containers_grab_variable' \
     -H 'Content-Type: application/json' \
     -d '{"name":"Cart total",
          "variable_path":"window.dataLayer[0].cart.total",
          "mask":"^([0-9.]+)$",
          "watch_variable":1}'
# → 153
# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/containers_grab_variable/153' \
     -H 'Content-Type: application/json' \
     -d '{"is_active":0}' 
# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/containers_grab_variable/153'

products

Produktkatalog. Jede Zeile ist eine SKU. Spaltennamen sind dynamisch — über die dokumentierten Verwaltungsspalten hinaus können Sie beliebige eigene Felder speichern, die Ihr Katalog braucht.

GET POST PUT DELETE
✅ ✅ ✅ ✅

Identifizierende / Verwaltungsspalten

Spalte Hinweise
id Primärschlüssel. Automatisch vergeben.
internal_id Ihre SKU / externe Kennung.
data_last_modified Unix-Sekunden.
is_in_stock 'yes' / 'no' Enum (nicht 1/0).

Gängige Produktfelder (benutzerdefiniert)

title, description_short, description_long, price, sale_price, image_big_url, image_medium_url, image_small_url, cart_url, brand, manufacturer, category, inventory, expiration_date, size, color, rank, is_new, age_from, age_to, available_location, not_available_locationusw. Die tatsächlichen Felder hängen von der Konfiguration Ihres Kontos ab.

Umbenannte Eingaben (bei POST / PUT)

Eingabe Gespeichert als
image_1 image_big_url
image_2 image_medium_url
image_3 image_small_url

Beispiele

# In-stock products in a category
curl 'https://api:KEY@app.personyze.com/rest/products
        /where/category=tools&is_in_stock=yes
        /columns/id,internal_id,title,price,inventory
        /order_by/title
        /limit/100'
# Lookup by internal_id
curl 'https://api:KEY@app.personyze.com/rest/products/where/internal_id=SKU-1234'
# Insert (or "patch" — duplicate internal_id will UPDATE rather than fail)
curl -X POST 'https://api:KEY@app.personyze.com/rest/products' \
     -H 'Content-Type: application/json' \
     -d '{"internal_id":"SKU-1234",
          "title":"Cordless Drill",
          "price":129.99,
          "is_in_stock":"yes",
          "image_1":"https://cdn.example.com/big.jpg"}'
# → 51234
# Update by internal_id
curl -X PUT 'https://api:KEY@app.personyze.com/rest/products/where/internal_id=SKU-1234' \
     -H 'Content-Type: application/json' \
     -d '{"price":119.99,"is_in_stock":"no"}' 
# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/products/where/internal_id=SKU-1234'

Upsert-Verhalten bei POST.POST arbeitet mit Patch bei Duplikat: Eine vorhandene internal_id aktualisiert die Zeile, statt fehlzuschlagen. Für den Massenimport aus einer Feed-URL nutzen Sie die geplante Feed-Synchronisierung in der Personyze-Oberfläche statt REST-Aufrufen pro Zeile.

articles

Artikelkatalog (Blogbeiträge, News, Einträge in Wissensdatenbanken). Dieselbe Form wie products , aber für redaktionelle Inhalte.

GET POST PUT DELETE
✅ ✅ ✅ ✅

Identifizierende / Verwaltungsspalten

Spalte Hinweise
id Primärschlüssel. Automatisch vergeben.
internal_id Ihre externe Kennung (Slug, CMS-ID).
data_last_modified Unix-Sekunden.
is_published 'yes' / 'no' Enum.

Gängige Artikelfelder (benutzerdefiniert)

title, description_short, description_long, image_big_url, image_medium_url, image_small_url, author, publish_date, category, tags, rankusw. Die tatsächliche Liste hängt von der Konfiguration other_columns_info Ihrer Website ab.

Umbenannte Eingaben

Eingabe Gespeichert als
image_1 image_big_url
image_2 image_medium_url
image_3 image_small_url

Beispiele

# Recent published articles
curl 'https://api:KEY@app.personyze.com/rest/articles
        /where/is_published=yes
        /columns/id,internal_id,title,author,publish_date
        /order_by_desc/publish_date
        /limit/100'
# Lookup by internal_id
curl 'https://api:KEY@app.personyze.com/rest/articles/where/internal_id=how-to-personalize'
# Insert
curl -X POST 'https://api:KEY@app.personyze.com/rest/articles' \
     -H 'Content-Type: application/json' \
     -d '{"internal_id":"how-to-personalize",
          "title":"How to personalize your site",
          "author":"Alice",
          "is_published":"yes",
          "image_1":"https://cdn.example.com/big.jpg"}' 
# Update
curl -X PUT 'https://api:KEY@app.personyze.com/rest/articles/where/internal_id=how-to-personalize' \
     -H 'Content-Type: application/json' \
     -d '{"is_published":"no"}' 
# Delete
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/articles/where/internal_id=how-to-personalize'

Artikelinteraktionen laufen über den Endpunkt do.POST arbeitet mit Patch bei Duplikat (wie products). Um Besucherinteraktionen mit Artikeln zu tracken (angesehen / kommentiert / gemocht), nutzen Sie do mit den Article … -Befehlen — ein eigenes REST-Objekt gibt es derzeit nicht.

products_interactions

Protokoll der Interaktionen mit Produkten: Aufrufe, Warenkorb-Hinzufügungen, Käufe, „favorite“, „delivered“. Überwiegend angehängt. Gestützt auf eine Archivtabelle.

GET POST PUT DELETE
✅ ✅ ✅ ✅

Spalten

Spalte Hinweise
user_id FK → users.user_id. Indexiert.
product_internal_id FK → products.internal_id. Führende Spalte eines zusammengesetzten Index [product_internal_id, user_id, transaction_time].
quantity Standard 1 beim Einfügen.
status Einer von viewed, delivered, extra (≈ in den Warenkorb gelegt), favorite, goal (Kauf). Indexiert.
action_id Wurde die Interaktion einer Personyze-Aktion zugeordnet, deren ID. Andernfalls null.
transaction_time Unix-Sekunden — Zeitpunkt der Bestellung/Transaktion.
time Unix-Sekunden — wann die Zeile protokolliert wurde. Indexiert.
amount Geldwert (gemäß den Währungseinstellungen der Website).

Einfügen: den Nutzer identifizieren

POST akzeptiert eines davon, um den Nutzer zu identifizieren:

Feld Wird aufgelöst zu
user_id (numerisch) Direkte Suche per Primärschlüssel.
user_internal_id user_id des Nutzers mit dieser internal_id. Legt automatisch eine Platzhalterzeile in users an, falls sie fehlt.
user_email user_id des Nutzers mit dieser email. Wird bei Bedarf automatisch angelegt.

Beispiele

# All purchases in a window, paged
curl 'https://api:KEY@app.personyze.com/rest/products_interactions
        /where/status=goal&time>1730000000
        /order_by_desc/time
        /limit/1000'
# A specific user's history with a product
curl 'https://api:KEY@app.personyze.com/rest/products_interactions
        /where/product_internal_id=SKU-1234
        /columns/user_id,status,quantity,amount,transaction_time'
# Log a purchase
curl -X POST 'https://api:KEY@app.personyze.com/rest/products_interactions' \
     -H 'Content-Type: application/json' \
     -d '{"user_internal_id":"acct-987",
          "product_internal_id":"SKU-1234",
          "quantity":2,
          "status":"goal",
          "transaction_time":1734000000,
          "amount":259.98}' 
# Delete by composite key
curl -X DELETE 'https://api:KEY@app.personyze.com/rest/products_interactions
        /where/user_id=5712334&product_internal_id=SKU-1234&status=viewed'

Indexierte Spalten

user_id, [product_internal_id, user_id, transaction_time], status, time. Abfragen ohne where auf einer davon (oder order_by auf derselben) werden als vollständige Tabellenscans abgelehnt.

events

Allgemeines Ereignisprotokoll — eine Zeile pro getracktem Ereignis, erfasst vom JS-Tracker, SDK oder dem Endpunkt do . Über REST derzeit nur lesbar.

GET POST PUT DELETE
✅ — — —

Spalten

Spalte Hinweise
id Primärschlüssel.
user_id FK → users.user_id. Indexiert.
time Unix-Sekunden.
visit_id FK → Besuchszeile.
container_id FK → containers.id (die Quelle des Ereignisses). Indexiert.
container_types Der Typ des Containers (click event, submit eventusw.).
value Nutzlast-Zeichenkette des Ereignisses.
first_visit_id Erste visit_id der Sitzung.
session_start_time Unix-Sekunden.

Beispiele

# Recent events for a user
curl 'https://api:KEY@app.personyze.com/rest/events
        /where/user_id=5712334
        /order_by_desc/time
        /limit/100'
# Events from a specific container in a window
curl 'https://api:KEY@app.personyze.com/rest/events
        /where/container_id=1234&time>1730000000&time<1731000000
        /columns/id,user_id,time,value
        /order_by_desc/time
        /limit/1000'

Wann events und wann summary_actions.Die Tabelle ist groß; Abfragen müssen auf einer indexierten Spalte filtern (id, user_id, container_id, …), sonst wird die Anfrage abgelehnt. Für aggregierte KPIs über die Zeit nutzen Sie stattdessen summary_actions — es hat vorberechnete Tageszähler pro Aktion.

forms

Protokoll der Formulareinsendungen. Eine Zeile pro vom Tracker erfasstem Absenden eines Formulars. Über REST derzeit nur lesbar.

GET POST PUT DELETE
✅ — — —

Spalten

Spalte Hinweise
user_id FK → users.user_id. Indexiert.
time Unix-Sekunden.
action_id Personyze-Aktion, die dieses Formular ausgelöst hat bzw. zu der es gehört, falls vorhanden.
session_start_time Unix-Sekunden.
plus data (JSON) Die eingesendeten Formulardaten, als JSON gepackt. Inline gelesen (ihre Schlüssel erscheinen als Spalten in der Antwort).

Das data -JSON wird beim Lesen automatisch in Schlüssel der obersten Ebene aufgelöst — fordern Sie bestimmte eigene Felder per Namen an.

Beispiele

# Submissions for a user
curl 'https://api:KEY@app.personyze.com/rest/forms
        /where/user_id=5712334
        /order_by_desc/time
        /limit/100'
# Submissions tied to a specific action
curl 'https://api:KEY@app.personyze.com/rest/forms
        /where/action_id=42&time>1730000000
        /columns/user_id,time,email,name,message
        /limit/1000'

Zu den indexierten Spalten gehören user_id, action_idund time. Abfragen müssen auf einer davon filtern.

do

Befehlsverteiler nach dem Prinzip „Fire and Forget“: Senden Sie eine einzelne Aktualisierung des Nutzerprofils oder ein Interaktionsereignis, ohne das Tracker-Protokoll zu sprechen. Der Body ist ein Array von Befehlen; jeder wird unabhängig verarbeitet.

GET POST PUT DELETE
— ✅ — —

Aufbau der Anfrage

[
    [<key-type>, <key-value>, <command>, <arg1>, <arg2>, ...],
    [<key-type>, <key-value>, <command>, <arg1>, <arg2>, ...],
    ...
]
  • <key-type>: "user_id", "internal_id"oder "email". Optional — weglassen bei Befehlen, die sich nicht an einen Nutzer richten.
  • <key-value>: die entsprechende Kennung.
  • <command>: eine Zeichenkette (ohne Beachtung der Groß-/Kleinschreibung). Siehe Liste unten.
  • <arg…>: befehlsspezifische Positionsargumente.

Ein erfolgreiches POST liefert nichts zurück; Fehler lösen eine Ausnahme aus (der ganze Batch bricht beim ersten Fehler ab).

Befehle

Nutzerprofil

["internal_id", "acct-987", "User profile", "first_name", "Alice", "custom_t_1", "VIP"]

Nach dem Befehlsnamen wechseln die Argumente ab: field, value, field, value, …

Produktinteraktionen

["internal_id", "acct-987", "Product viewed",          "SKU-1234"]
["internal_id", "acct-987", "Product added to cart",   "SKU-1234", "quantity", 2]
["internal_id", "acct-987", "Product liked",           "SKU-1234"]
["internal_id", "acct-987", "Product purchased",       "SKU-1234", "quantity", 2, "amount", 259.98]
["internal_id", "acct-987", "Product removed from cart","SKU-1234"]
["internal_id", "acct-987", "Product unliked",         "SKU-1234"]

Nach der SKU optionale Schlüssel-Wert-Paare: "quantity", "amount", "action_id", "transaction_time".

Artikelinteraktionen

["email", "alice@example.com", "Article viewed",   "how-to-personalize"]
["email", "alice@example.com", "Article liked",    "how-to-personalize"]
["email", "alice@example.com", "Article commented","how-to-personalize"]
["email", "alice@example.com", "Article unliked", "how-to-personalize"]
["email", "alice@example.com", "Article goal",     "how-to-personalize"]

Beispiele

# Tag a user as VIP
curl -X POST 'https://api:KEY@app.personyze.com/rest/do' \
     -H 'Content-Type: application/json' \
     -d '[["internal_id","acct-987","User profile","custom_t_1","VIP","first_name","Alice"]]' 
# Log a purchase + a profile update in one round-trip
curl -X POST 'https://api:KEY@app.personyze.com/rest/do' \
     -H 'Content-Type: application/json' \
     -d '[
       ["email","alice@example.com","Product purchased","SKU-1234","quantity",2,"amount",259.98],
       ["email","alice@example.com","User profile","customer_segment","loyal"]
     ]' 

Wann do und wann typisierte Endpunkte.Suchschlüssel (internal_id / email) legen automatisch eine Platzhalterzeile in users an, wenn kein Nutzer passt. Für Interaktionsprotokollierung mit hohem Durchsatz nutzen Sie lieber products_interactions (typisiert und indexiert) oder die gebündelte Ereignis-API des SDK.

sessions_archive

Eine Zeile pro Besuchersitzung (ein zusammenhängendes Aktivitätsfenster). Gestützt auf die langlebige Archivtabelle — viel breiter als events, mit Metadaten zu Standort, Gerät, Bildschirm und Browser.

GET POST PUT DELETE
✅ — — —

Identifizierend / Verwaltung

Spalte Hinweise
first_visit_id Primärschlüssel. Die ID der ersten visit -Zeile in dieser Sitzung.
user_id FK → users.user_id. Indexiert.
session_start_time Unix-Sekunden.
last_session_time Unix-Sekunden.
session_counter Die wievielte Sitzung dieses Nutzers (1, 2, 3, …).
total_visits In der Sitzung angesehene Seiten.
time_in_focus Sekunden, in denen der Tab tatsächlich im Fokus war.
time_total Sekunden vom Beginn bis zur letzten Aktivität.

Geografie / Locale / Gerät

Spalte Hinweise
time_zone Zeitzonenversatz des Besuchers (Stunden).
country_code, region_code, city Geografie (aus der IP). city wird aus der gemeinsamen Nachschlagetabelle verknüpft und ist daher ein lesbarer Name (null wenn kein Treffer).
lang_0, lang_1, lang_2 Die ersten drei Einträge von Accept-Language.
screen_width, screen_height, screen_depth Pixel / Farbtiefe.

Interaktionszähler

Spalte Hinweise
total_goal_value, total_n_goals Zielaggregate der Sitzung.
page_click, page_right_mouse, page_key_up, page_scroll Zählungen pro Ereignis.

Landing-URL & Referrer

Spalte Hinweise
url_prefix, url_host_port, url_path, url_query, url_fragment URL der ersten Seite der Sitzung, in Teile zerlegt. url_prefix ist die Kodierung von Schema+www.
referrer_prefix, referrer_host_port, referrer_path, referrer_query, referrer_fragment Dieselbe Form, für den Referrer.
referrer_type Numerisches Kennzeichen (Suche / Social / direkt / …).
search_word Suchanfrage bei Ankunft über eine Suchmaschine.

UTM / Werbekampagne

ad_campaign, ad_source, ad_medium, ad_term, ad_content — die Standard-UTM-Parameter, wie beim Landing erfasst.

Beispiele

# Sessions for a user, most recent first
curl 'https://api:KEY@app.personyze.com/rest/sessions_archive
        /where/user_id=5712334
        /columns/first_visit_id,session_start_time,total_visits,country_code,city
        /order_by_desc/session_start_time
        /limit/100'
# Single session by primary key
curl 'https://api:KEY@app.personyze.com/rest/sessions_archive
        /where/first_visit_id=900000000123
        /columns/user_id,session_start_time,total_visits,total_goal_value'

Indexierte Spalten: first_visit_id, user_id, plus mehrere weitere. Abfragen müssen auf einer indexierten Spalte filtern, sonst wird die Anfrage als vollständiger Tabellenscan abgelehnt.

user_interests

Interessen, Kategorien, Tags sowie Family-/Cross-/Upsale-Tags pro Nutzer, abgeleitet von der Tracker-Pipeline. Eine Zeile pro (user_id, value, class, time). Nur lesbar.

GET POST PUT DELETE
✅ — — —

Spalten

Spalte Hinweise
user_id FK → users.user_id. Indexiert.
value Das Interessen-Token (z. B. Kategoriename, Tag, Stichwort).
class interest, category, tag, family, cross category, upsale category.
rank Gleitkomma. Relevanzwert innerhalb der Klasse.
n_times Wie oft dieser Wert für den Nutzer beobachtet wurde.
time Unix-Sekunden — wann das Interesse zuletzt aktualisiert wurde. Indexiert.

Indexierte Spalten: user_id, time. Abfragen müssen auf einer indexierten Spalte filtern.

Beispiele

# All interests for one user, strongest first
curl 'https://api:KEY@app.personyze.com/rest/user_interests
        /where/user_id=5712334
        /columns/value,class,rank,n_times,time
        /order_by_desc/rank
        /limit/100'
# Only categories, recently updated
curl 'https://api:KEY@app.personyze.com/rest/user_interests
        /where/user_id=5712334&class=category
        /order_by_desc/time
        /limit/50'

products_stats_*

Aggregierte Interaktionszähler pro Produkt, gepflegt von der Offline-Zusammenfassungspipeline. Sechs gleitende Zeitfenster stehen unter getrennten Pfaden bereit — wählen Sie das, das zu Ihrem Berichtszeitraum passt. Alle teilen dieselbe Spaltenform und dieselben Indizes; nur das Zeitfenster unterscheidet sich.

GET POST PUT DELETE
✅ — — —

Endpunkte

Pfad Zeitfenster
/rest/products_stats_1day letzter 1 Tag
/rest/products_stats_2day letzte 2 Tage
/rest/products_stats_4day letzte 4 Tage
/rest/products_stats_week letzte 7 Tage
/rest/products_stats_recent kürzlich (gleitend — von der Pipeline festgelegt)
/rest/products_stats_all gesamte Laufzeit

Identifizierend

Spalte Hinweise
internal_id Primärschlüssel. Die externe Kennung des Produkts (Katalog-SKU / von Ihnen gelieferte ID). Indexiert.

Zähler pro Produkt (Zahl der Interaktionen mit diesem Produkt im Zeitfenster)

Spalte Hinweise
n_viewed Zahl der Aufrufereignisse. Indexiert.
n_delivered Zahl der ausgelieferten (angezeigten) Empfehlungen. Indexiert (zusammengesetzt mit n_viewed).
n_extra „Extra“-Interaktionen (z. B. in den Warenkorb). Indexiert (zusammengesetzt mit n_viewed).
n_favorite Favorisiert / auf die Wunschliste gesetzt. Indexiert (zusammengesetzt mit n_viewed).
n_goal Zielabschlüsse (Käufe). Indexiert (zusammengesetzt mit n_viewed).

Verteilungsstatistiken über den ganzen Katalog

Derselbe Wert in jeder Zeile — beschreibt den ganzen Katalog in diesem Zeitfenster. Für jede Kennzahl M ∈ {viewed, delivered, extra, favorite, goal}:

Spalte Hinweise
overall_n_<M> Summe über alle Produkte.
overall_avg_<M> Mittelwert über alle Produkte.
overall_avg_nonzero_<M> Mittelwert über Produkte mit mindestens einem Ereignis.
percentile_<M> Perzentilrang dieser Zeile für die Kennzahl.

Die letzten 3 Zielnutzer (jüngste Käufer dieses Produkts)

Spalte Hinweise
last_goal_user_id_0, last_goal_user_id_1, last_goal_user_id_2 Einzeln indexiert.
last_goal_user_time_0, last_goal_user_time_1, last_goal_user_time_2 Unix-Sekunden.

Indexierte Spalten

internal_id, n_viewed, n_delivered, n_extra, n_favorite, n_goal, last_goal_user_id_0, last_goal_user_id_1, last_goal_user_id_2. Abfragen müssen auf einer davon filtern (oder order_by).

Beispiele

# Top 50 most-viewed products this week
curl 'https://api:KEY@app.personyze.com/rest/products_stats_week
        /where/n_viewed>0
        /columns/internal_id,n_viewed,n_delivered,n_extra,n_goal,percentile_viewed
        /order_by_desc/n_viewed
        /limit/50'
# Lookup one product's lifetime stats
curl 'https://api:KEY@app.personyze.com/rest/products_stats_all
        /where/internal_id=SKU-12345'
# What a specific user purchased recently (matches against last 3 goal users)
curl 'https://api:KEY@app.personyze.com/rest/products_stats_recent
        /where/last_goal_user_id_0=5712334
        /columns/internal_id,n_goal,last_goal_user_time_0'

summary_actions

Täglich aggregierte KPIs pro Aktion — eine Zeile pro (day, action_id) für Aktionen, die an eine bestimmte Kampagne gebunden sind (condition_id). Nur lesbar.

GET POST PUT DELETE
✅ — — —

Strenge Indexanforderung.Nur day ist indexiert. Jede Anfrage muss where/day… enthalten — einen Ausweg nur mit order_bygibt es nicht.

Identifizierend

Spalte Hinweise
day Unix-Zeitstempel (Sekunden) von 0:00 Uhr des Tages in Greenwich (GMT+0000).
action_name Name der Aktion.
action_id ID der Aktion.
campaign_name Name der Kampagne, zu der die Aktion gehört.
campaign_id ID der Kampagne, zu der die Aktion gehört.

Reichweite der Aktion

Spalte Hinweise
n_executed Wie oft ausgeführt (Aktionen gelten als ausgeführt, auch wenn der sichtbare Inhalt noch nicht angezeigt wird).
n_delivered Wie oft wir von der Browserseite die Rückmeldung erhalten haben, dass der Inhalt sichtbar wurde.
n_extra Hängt vom Aktionstyp ab. Bei HTML-Aktionen: Zahl der Klicks. Bei Formularaktionen: Zahl der Einsendungen.
n_failed Nur bei E-Mail-Aktionen gezählt. Wie oft der E-Mail-Versand fehlgeschlagen ist (z. B. ungültige Adresse).
n_closed Wie oft der Nutzer den Button „Schließen“ geklickt hat, nachdem der Inhalt der Aktion sichtbar wurde.
n_sessions_executed In wie vielen verschiedenen Sitzungen es mindestens ein n_executed für diese Aktion gab.
n_sessions_delivered In wie vielen verschiedenen Sitzungen es mindestens ein n_delivered.
n_sessions_extra In wie vielen verschiedenen Sitzungen es mindestens ein n_extra.
n_sessions_failed In wie vielen verschiedenen Sitzungen es mindestens ein n_failed.
n_sessions_closed In wie vielen verschiedenen Sitzungen es mindestens ein n_closed.

Produktzuordnung (wenn diese Aktion Produkte empfohlen hat)

Spalte Hinweise
products_goal_n_times Wie viele Produkte (über alle Besucher) in einer Sitzung, in der diese Aktion ausgeführt wurde, „gekauft“ erreicht haben. Zählt jedes Kaufereignis eines Produkts; eine einzelne Bestellung mit 3 Artikeln zählt also 3.
products_goal_n_sessions In wie vielen verschiedenen Sitzungen nach Ausführung dieser Aktion mindestens ein Produkt gekauft wurde.
products_goal_value Summe der Geldwerte aller gekauften Produkte, gezählt in products_goal_n_times.
products_recom_viewed_n_times Wie oft ein von dieser Aktion empfohlenes Produkt anschließend angesehen wurde.
products_recom_viewed_n_sessions In wie vielen verschiedenen Sitzungen mindestens ein empfohlenes Produkt angesehen wurde.
products_recom_extra_n_times Wie oft ein empfohlenes Produkt anschließend in den Warenkorb gelegt wurde (oder anderweitig die „Extra“-Interaktion erreicht hat).
products_recom_extra_n_sessions In wie vielen verschiedenen Sitzungen mindestens ein empfohlenes Produkt die „Extra“-Interaktion erreicht hat.
products_recom_extra_value Summe der Geldwerte aller empfohlenen Produkte mit „Extra“-Interaktion.
products_recom_goal_n_times Wie oft ein empfohlenes Produkt anschließend gekauft wurde.
products_recom_goal_n_sessions In wie vielen verschiedenen Sitzungen mindestens ein empfohlenes Produkt gekauft wurde.
products_recom_goal_value Summe der Geldwerte aller gekauften empfohlenen Produkte.

Artikelzuordnung

Dieselbe Form wie die Produktzuordnung, aber für Artikel: articles_recom_viewed_n_times, articles_recom_viewed_n_sessions, articles_recom_extra_n_times, articles_recom_extra_n_sessions, articles_recom_extra_value, articles_recom_goal_n_times, articles_recom_goal_n_sessions, articles_recom_goal_value.

Eigene Zielereignisse pro Konto

Ein Konto kann bis zu 12 Zielereignisse konfigurieren. Für jeden in Ihrem Konto konfigurierten Ereignis-Container mit einem von null verschiedenen goal_event_index (N von 1 bis 12) erscheinen in der Antwort vier zusätzliche Spalten:

  • goal_event_N_name — Anzeigename des konfigurierten Zielereignisses. Als literale Zeichenkette zurückgegeben, in jeder Zeile gleich.
  • goal_event_N_n_times — Wie oft dieses Zielereignis in einer Sitzung ausgelöst wurde, in der die Aktion ausgeführt wurde.
  • goal_event_N_n_sessions — In wie vielen verschiedenen Sitzungen dieses Zielereignis nach Ausführung der Aktion mindestens einmal ausgelöst wurde.
  • goal_event_N_value — Summe der Geldwerte, die für dieses Zielereignis über die gezählten Male gemeldet wurden, in goal_event_N_n_times (null, sofern der Container des Zielereignisses nicht so konfiguriert ist, dass er einen Wert erfasst).

Beispiele

# Last 30 days, daily KPIs per action
curl 'https://api:KEY@app.personyze.com/rest/summary_actions
        /where/day>1730000000
        /columns/day,action_name,n_executed,n_delivered,n_extra,products_goal_value
        /order_by_desc/day
        /limit/1000'
# A specific action's lifetime
curl 'https://api:KEY@app.personyze.com/rest/summary_actions
        /where/action_id=42&day>1700000000
        /order_by/day
        /limit/1000'

tracker_code

Liefert das JS-Snippet, das Sie in Ihre Website einbetten, um den Personyze-Tracker zu starten. Der Inhalt ergibt sich aus den Einstellungen Ihres Kontos (Konto-ID, Tracking-Host, Flags für async/no-hide).

GET POST PUT DELETE
✅ — — —

Antwort

Ein einfaches text/html (oder JS in<script>) Snippet, bereit zum Einbinden in einen <head>. Der Body ist kein JSON — das ist der einzige REST-Endpunkt, der rohes HTML liefert.

Beispiel

curl 'https://api:KEY@app.personyze.com/rest/tracker_code'
<script>(function(s){
    s.async = true;
    s.src = '//lcounter.personyze.com/stat-track-lib.js';
    s.onload = function() {
        _S_T.async = true;
        _S_T.setup(5919, "example.com www.example.com");
    };
    (document.querySelector('head') || document.documentElement).appendChild(s);
}(document.createElement('script')))</script>

Konventionen des Tracker-Snippets.Das Snippet enthält Ihre Konto-ID und die Liste der für dieses Konto registrierten zulässigen Hostnamen. Bearbeiten Sie es nicht von Hand; rufen Sie es neu ab, wenn Sie über die Oberfläche neue Domains hinzufügen. Für native SDK-Clients (iOS / Android) ist dieser Endpunkt nicht relevant — das SDK spricht das Tracker-Protokoll direkt über interne Endpunkte.

Nächste Schritte

📖 Syntax der PfadparameterAusführlich zu where/columns/order_by/limit mit allen Operatoren und Beispielen. Lesen →
🔑 AuthentifizierungUmgang mit API-Schlüsseln, Header-Format, Fehlercodes, Setups mit mehreren Konten. Lesen →
🛠 EntwicklerressourcenSDKs, GitHub-Repositorys und weitere Entwicklerwerkzeuge. Lesen →
Did this page answer your question?
Thank you — that goes to whoever maintains this page.