Über die REST-API von Personyze lesen und ändern Anwendungen von Drittanbietern Daten in Ihrem Konto: Kundenprofile, Produkt- und Artikelkataloge, Platzhalter, Aktionen, Zielgruppenlisten, tägliche Berichtszusammenfassungen — dieselben Daten, mit denen auch die Personyze-Oberfläche arbeitet. Sie nutzt Standard-HTTPS, nimmt JSON an und gibt JSON zurück und unterstützt die vier Standardverben (GET, POST, PUT, DELETE).
Diese Seite ist der Einstiegspunkt. Die vollständige Einrichtung finden Sie unter Authentifizierung. Zur Syntax der Pfadparameter (dem Muster where/columns/order_by/limit , das sich durch jeden Endpunkt zieht) siehe Pfadparameter. Spaltenlisten und unterstützte Methoden pro Objekt finden Sie in der Objektreferenz.
Schnellstart
Den Nutzer mit der internen ID abrufen 42:
curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'Das ist der gesamte Aufbau jeder Anfrage:
https://api:<API_KEY>@app.personyze.com/rest/<object>[/<modifier>/<value>...]- Nur HTTPS. Reines HTTP erhält
401 Unauthorized— auch beilocalhost-Proxys. - HTTP-Basic-Authentifizierung mit dem Benutzernamen
apiund Ihrem API-Schlüssel als Passwort (oder übergeben Sie ihn direkt wie imcurl-Beispiel oben). - Alle Pfadargumente werden vor dem Parsen URL-dekodiert — Spaltenwerte, die
/,=,&oder%enthalten, müssen prozentkodiert werden.
HTTP-Methoden
| Methode | Zweck | Body | Rückgabe |
|---|---|---|---|
GET |
lesen | keiner | Array von Datensätzen (oder ein Datensatz bei der Form mit einer einzelnen ID) |
POST |
anlegen | JSON-Objekt | Numerische ID des neuen Datensatzes |
PUT |
aktualisieren | JSON-Objekt | Anzahl der betroffenen Zeilen |
DELETE |
löschen | keiner | Anzahl der betroffenen Zeilen |
POST und PUT -Bodies verwenden Content-Type: application/json. application/x-www-form-urlencoded wird als Fallback für ältere Clients akzeptiert, JSON ist aber vorzuziehen.
Antwortcodes
| Code | Bedeutung |
|---|---|
200 OK |
Erfolg — der Body hängt von der Methode ab (siehe Tabelle der HTTP-Methoden oben). Spalten vom Typ Datum werden serialisiert als YYYY-MM-DD HH:MM:SS; Zeitstempel sind Unix-Sekunden in UTC. |
400 Bad Request |
Ihre Eingabe wurde abgelehnt. Der Body ist eine für Menschen lesbare Beschreibung in reinem Text (z. B. „Cannot do this operation on whole table: column ‚uset_id‘ is not indexed.“). Häufige Ursachen: Tippfehler im Spaltennamen, fehlende where -Klausel bei einer großen Tabelle, fehlerhafter JSON-Body. |
401 Unauthorized |
Falscher oder fehlender API-Schlüssel, oder die Anfrage lief nicht über HTTPS. |
500 Internal Server Error |
Unerwarteter Fehler auf Seiten der API — die Meldung steht im Body. Ein erneuter Versuch nach einigen Sekunden lohnt sich; hält der Fehler an, wenden Sie sich an den Support. |
503 Service Unavailable |
Vorübergehender Fehler (Deadlock, verlorene DB-Verbindung usw.). Ein erneuter Versuch mit Backoff ist sicher. |
Konventionen für alle Endpunkte
id vs. internal_id
Die meisten Objekte bieten zwei Identifikatoren:
id— der interne numerische Primärschlüssel von Personyze, beim Einfügen automatisch vergeben. Dauerhaft stabil, aber nur innerhalb von Personyze aussagekräftig.internal_id— die externe Kennung, die Sie liefern (Ihre E-Commerce-SKU, Ihre CRM-Nutzer-ID usw.). Verfügbar bei Objekten, bei denen die Zuordnung zu einem externen System wichtig ist:users,products,articles.
Für den meisten Integrationscode sollten Sie internal_id verwenden — so funktioniert derselbe Code weiter, auch wenn dieselben Daten erneut in Personyze importiert werden und dabei neue ids.
Indexierte Spalten bei großen Tabellen erforderlich
Endpunkte, die große Tabellen umfassen (users, events, sessions_archive, summary_actionsusw.), lehnen vollständige Tabellenscans ab. Sie müssen entweder eine where -Klausel oder ein order_by auf einer indexierten Spalte angeben. Fehlermeldungen listen die verfügbaren indexierten Spalten bzw. Kombinationen auf — die vollständigen Regeln finden Sie unter Pfadparameter → Anforderung an indexierte Spalten.
Zusammengesetzte Indizes
Zusammengesetzte Indizes erscheinen in Fehlermeldungen als [col1, col2, col3]. Nur die führende Spalte eines zusammengesetzten Index ist als einzelner Filter nutzbar. Die anderen Spalten werden nur in Kombination mit der führenden Spalte nützlich.
API-Schlüssel gelten pro Konto
Jedes Personyze-Konto, auf das Sie Zugriff haben, hat einen eigenen API-Schlüssel — sie sind nicht austauschbar. Ein anderes Konto heißt ein anderer Schlüssel.
Limits & Paginierung
- Maximal 1.000 Zeilen pro Anfrage. Nutzen Sie
limit/<count>oderlimit/<offset>,<count>, um die Seitengröße zu steuern. - Cursor-Paginierung statt tiefer Offsets. Die indexierte
order_by-Spalte mit cursorartigenwhere-Bedingungen zu durchlaufen, ist viel schneller als tiefeoffset-Werte, die alle übersprungenen Zeilen erneut lesen.
where statt per Offset zu blättern. Nachdem Sie zum Beispiel 1.000 Nutzer absteigend nach last_session_time sortiert abgerufen haben, sollte die nächste Seite where/last_session_time<<last_seen_value> verwenden statt limit/1000,1000.Weiter vertiefen
curl-, Python- und JS-Beispielen sowie Zugriff auf mehrere Konten. Lesen →where / columns / order_by / limit mit allen Operatoren und UND/ODER-Verknüpfung. Lesen →Verwandte Leitfäden
- Einrichtung nach Website-Typ — Tracking, Feeds & Integrationen — wählen Sie Ihren Ausgangspunkt je nach Art Ihrer Website.
- Leitfaden für JavaScript-Aktionen — zum Schreiben eigener Personyze-Aktionen, die im Browser laufen.
- Kampagnendaten clientseitig abrufen — Kampagnen-IDs und Variablen per JavaScript auf der Seite lesen.