Met de REST API van Personyze lezen en wijzigen applicaties van derden data in je account: klantprofielen, product- en artikelcatalogi, placeholders, acties, doelgroeplijsten, dagelijkse rapportagesamenvattingen — dezelfde data waarmee de interface van Personyze werkt. Hij gebruikt standaard-HTTPS, accepteert en geeft JSON terug, en ondersteunt de vier standaardwerkwoorden (GET, POST, PUT, DELETE).
Deze pagina is het startpunt. Voor de volledige installatie-uitleg, zie Authenticatie. Voor de syntaxis van padparameters (het patroon where/columns/order_by/limit dat door elk endpoint loopt), zie Padparameters. Voor kolomlijsten per object en ondersteunde methoden, zie Naslag van objecten.
Snel aan de slag
Haal de gebruiker op met interne ID 42:
curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'Dat is de hele vorm van elk verzoek:
https://api:<API_KEY>@app.personyze.com/rest/<object>[/<modifier>/<value>...]- Alleen HTTPS. Gewone HTTP krijgt
401 Unauthorized— zelfs voorlocalhost-proxy’s. - HTTP Basic auth met gebruikersnaam
apien je API-sleutel als wachtwoord (of geef die inline mee zoals in hetcurl-voorbeeld hierboven). - Alle padargumenten worden URL-gedecodeerd voordat ze worden verwerkt — kolomwaarden met
/,=,&, of%moeten procent-gecodeerd zijn.
HTTP-methoden
| Methode | Doel | Body | Geeft terug |
|---|---|---|---|
GET |
lezen | geen | Array met records (of één record bij de vorm met één id) |
POST |
aanmaken | JSON-object | Numerieke ID van het nieuwe record |
PUT |
bijwerken | JSON-object | Aantal betrokken rijen |
DELETE |
verwijderen | geen | Aantal betrokken rijen |
POST en PUT -body’s gebruiken Content-Type: application/json. application/x-www-form-urlencoded wordt als terugval geaccepteerd voor oudere clients, maar JSON heeft de voorkeur.
Responscodes
| Code | Betekenis |
|---|---|
200 OK |
Gelukt — de body hangt af van de methode (zie de tabel met HTTP-methoden hierboven). Kolommen van het type datum worden geserialiseerd als YYYY-MM-DD HH:MM:SS; tijdstempels zijn Unix-seconden in UTC. |
400 Bad Request |
Je invoer is geweigerd. De body is een leesbare beschrijving in platte tekst (bijv. “Cannot do this operation on whole table: column ‘uset_id’ is not indexed.”). Veelvoorkomende oorzaken: een typefout in een kolomnaam, een ontbrekende where -clausule bij een grote tabel, een ongeldige JSON-body. |
401 Unauthorized |
Ongeldige of ontbrekende API-sleutel, of het verzoek was geen HTTPS. |
500 Internal Server Error |
Onverwachte fout aan de kant van de API — melding in de body. Het loont om het na een paar seconden opnieuw te proberen; blijft het, neem dan contact op met support. |
503 Service Unavailable |
Tijdelijke fout (deadlock, verbroken databaseverbinding, enz.). Veilig om opnieuw te proberen met backoff. |
Conventies voor alle endpoints
id vs internal_id
De meeste objecten hebben twee identificatoren:
id— de interne numerieke primaire sleutel van Personyze, automatisch toegekend bij het invoegen. Voor altijd stabiel, maar alleen betekenisvol binnen Personyze.internal_id— de externe identificator die jij aanlevert (je e-commerce-SKU, je gebruikers-ID uit het CRM, enz.). Beschikbaar bij objecten waar koppelen aan een extern systeem ertoe doet:users,products,articles.
Voor de meeste integratiecode wil je internal_id gebruiken — zo blijft dezelfde code werken, ook als dezelfde data opnieuw in Personyze worden geïmporteerd met nieuwe ids.
Geïndexeerde kolommen vereist bij grote tabellen
Endpoints rond grote tabellen (users, events, sessions_archive, summary_actions, enz.) weigeren scans van de volledige tabel. Je moet een where -clausule of een order_by op een geïndexeerde kolom opnemen. Foutmeldingen noemen de beschikbare geïndexeerde kolommen/samengestelde indexen — zie Padparameters → Vereiste geïndexeerde kolom voor alle regels.
Samengestelde indexen
Samengestelde indexen verschijnen in foutmeldingen als [col1, col2, col3]. Alleen de eerste kolom van een samengestelde index is bruikbaar als filter op één kolom. De andere kolommen worden pas nuttig in combinatie met de eerste kolom.
API-sleutels gelden per account
Elk Personyze-account waartoe je toegang hebt, heeft een eigen API-sleutel — die zijn niet uitwisselbaar. Van account wisselen betekent van sleutel wisselen.
Limieten & paginering
- Maximaal 1.000 rijen per verzoek. Gebruik
limit/<count>oflimit/<offset>,<count>om de paginagrootte te bepalen. - Cursorpaginering heeft de voorkeur boven diepe offsets. De geïndexeerde
order_by-kolom doorlopen metwhere-voorwaarden in cursorstijl is veel sneller dan diepeoffset-waarden, die alle overgeslagen rijen opnieuw lezen.
where in plaats van te pagineren op offset. Na het ophalen van 1.000 gebruikers gesorteerd op last_session_time aflopend moet de volgende pagina bijvoorbeeld where/last_session_time<<last_seen_value> gebruiken in plaats van limit/1000,1000.Verder verdiepen
curl/Python/JS-voorbeelden, en toegang tot meerdere accounts. Lezen →where / columns / order_by / limit -syntaxis met alle operatoren en combinaties met AND/OR. Lezen →Gerelateerde handleidingen
- Installatie per type site — tracking, feeds & integraties — kies je startpunt op basis van het type site.
- Handleiding voor de JavaScript-actie — om eigen Personyze-acties te schrijven die in de browser draaien.
- Campagnedata aan de clientkant — lees campagne-ID’s en variabelen uit JavaScript op de pagina.