REST API: naslag van objecten

Naslag voor elk object dat de REST API van Personyze beschikbaar stelt. Elk onderdeel hieronder behandelt één object: het doel, de ondersteunde HTTP-methoden, de kolommen (met type en opmerkingen over indexering), en curl -voorbeelden die klaar zijn om te kopiëren.

Vereisten — lees deze eerst als je dat nog niet hebt gedaan:

• REST API: overzicht & snel aan de slag — vorm van een verzoek, HTTP-methoden, responscodes
• Authenticatie — je API-sleutel krijgen, meesturen, opzetten met meerdere accounts
• Padparameters — de where/columns/order_by/limit -syntaxis die door elk voorbeeld hieronder loopt

Objectenindex

Klik op een object om naar het onderdeel te springen. Elk onderdeel heeft een eigen anker-URL — je kunt direct naar de naslag van elk object linken.

CRUD-content (lezen/schrijven)

Bevat je campagnes, doelgroep, catalogus en configuratie. Volledige CRUD voor External API user en hoger.

Interacties / events (vooral schrijven)

Logboeken van bezoekersinteracties waaraan alleen wordt toegevoegd. Vooral gebruikt door SDK’s en integraties aan de backend.

Rapporten / archief (alleen-lezen)

Hulpmiddelen voor tracker / SDK

Gebruikt door de JS-tracker, native SDK’s en integraties om zichzelf op te starten. Meestal niet direct aangeroepen door gebruikers van de REST API.

users

Klantprofielen. Elke rij is één bezoeker of klant. Kolomnamen zijn dynamisch — naast de gedocumenteerde huishoudelijke kolommen kun je alle eigen sleutels/waarden opslaan die je account nodig heeft.

Identificerende / huishoudelijke kolommen

Veelgebruikte profielvelden (eigen)

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 (tekst), custom_i_1…custom_i_4 (geheel getal), custom_f_1…custom_f_2 (kommagetal), custom_d_1, custom_d_2 (datum) — en alle extra velden die je op je account hebt ingesteld.

Voorbeelden

# 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)

Geïndexeerde kolommen / scanlimieten

GET /rest/users zonder where vereist order_by op een geïndexeerde kolom — user_id, last_session_time, data_last_modified, fb_id, email, of internal_id. Anders: 400 Cannot do this operation on whole table.

Snelheidsbeperking

POST /rest/users wordt per Personyze-account geserialiseerd: hooguit één lopende insert tegelijk. Verzoeken die langer dan 1 seconde wachten, worden geweigerd met 400 Too many simultaneous requests — probeer opnieuw met exponentiële backoff.

user_lists

Benoemde lijsten met gebruikers (bijv. “VIP’s”, “Aanmeldingen voor de nieuwsbrief”). Eén rij per lijst. Het lidmaatschap staat in een apart object — zie user_list_users.

Kolommen

Voorbeelden

# 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

Lidmaatschap: welke gebruikers bij welke user_listshoren. Eén rij per (user_list_id, user_id) -paar.

POST accepteert een bestaande user_id, of een opzoeksleutel (user_internal_id, user_email) — de API zet die om naar een user_id, en maakt zo nodig een tijdelijke users -rij aan.

Kolommen

Extra’s in de POST-body (omgezet naar user_id aan de serverkant, en daarna weggelaten)

Voorbeelden

# 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

Personalisatieacties — wat je campagnes doen: HTML weergeven, een pop-up tonen, een e-mail versturen, een melding pushen, enz. Via REST op dit moment alleen-lezen (maken/bewerken via de interface).

Kolommen

Voorbeelden

# 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

Doelgroepvoorwaarden — het wanneer van campagnes. Via REST alleen-lezen.

Kolommen

Voorbeelden

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

placeholders

Containers van het type placeholder — DOM-plekken waar acties content weergeven. Beheer de catalogus met placeholders die voor je site zijn gedefinieerd.

Kolommen

Voorbeelden

# 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

containers_grab_variable

Containers van het type “grab variable” — halen DOM-/JS-waarden van de pagina van de bezoeker terug naar het bezoekersprofiel. Elke container zegt “houd deze variabele / dit DOM-element in de gaten; verschijnt die, leg die dan vast als profielveld.”

Kolommen

Voorbeelden

# 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

Productcatalogus. Elke rij is één SKU. Kolomnamen zijn dynamisch — naast de gedocumenteerde huishoudelijke kolommen kun je alle eigen velden opslaan die je catalogus nodig heeft.

Identificerende / huishoudelijke kolommen

Veelgebruikte productvelden (eigen)

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_location, enz. De werkelijke set velden hangt af van de configuratie van je account.

Hernoemde invoer (bij POST / PUT)

Voorbeelden

# 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'

articles

Artikelcatalogus (blogberichten, nieuws, items in een kennisbank). Dezelfde vorm als products maar voor redactionele content.

Identificerende / huishoudelijke kolommen

Veelgebruikte artikelvelden (eigen)

title, description_short, description_long, image_big_url, image_medium_url, image_small_url, author, publish_date, category, tags, rank, enz. De werkelijke lijst hangt af van de other_columns_info -configuratie van je site.

Hernoemde invoer

Voorbeelden

# 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'

products_interactions

Logboek van interacties met producten: weergaven, toevoegingen aan de winkelwagen, aankopen, “favoriet”, “bezorgd”. Vooral toevoegen. Ondersteund door een archieftabel.

Kolommen

Invoegen: de gebruiker identificeren

POST accepteert één van deze om de gebruiker te identificeren:

Voorbeelden

# 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'

Geïndexeerde kolommen

user_id, [product_internal_id, user_id, transaction_time], status, time. Query’s zonder where op een van deze (of order_by op dezelfde) worden geweigerd als scans van de volledige tabel.

events

Algemeen eventlogboek — één rij per gevolgd event dat is vastgelegd door de JS-tracker, de SDK of het endpoint do . Via REST op dit moment alleen-lezen.

Kolommen

Voorbeelden

# 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'

forms

Logboek van formulierinzendingen. Eén rij per formulierinzending die door de tracker is vastgelegd. Via REST op dit moment alleen-lezen.

Kolommen

De data -JSON wordt bij het lezen automatisch uitgevouwen tot sleutels op het hoogste niveau — vraag specifieke eigen velden op naam op.

Voorbeelden

# 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'

Geïndexeerde kolommen zijn onder meer user_id, action_id, en time. Query’s moeten op een van deze filteren.

do

Verdeler voor commando’s die je afvuurt en vergeet: stuur één update van een gebruikersprofiel of één interactie-event zonder het trackerprotocol te spreken. De body is een array met commando’s; elk commando wordt afzonderlijk verwerkt.

Vorm van het verzoek

[
    [<key-type>, <key-value>, <command>, <arg1>, <arg2>, ...],
    [<key-type>, <key-value>, <command>, <arg1>, <arg2>, ...],
    ...
]

• <key-type>: "user_id", "internal_id", of "email". Optioneel — laat weg bij commando’s die niet op een gebruiker zijn gericht.
• <key-value>: de bijbehorende identificator.
• <command>: een tekenreeks (niet hoofdlettergevoelig). Zie de lijst hieronder.
• <arg…>: positionele argumenten die per commando verschillen.

Een geslaagde POST geeft niets terug; bij fouten wordt een exceptie gegooid (de hele batch stopt bij de eerste fout).

Commando’s

Gebruikersprofiel

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

Na de naam van het commando wisselen de argumenten elkaar af: field, value, field, value, …

Productinteracties

["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"]

Na de SKU volgen optionele sleutel-waardeparen: "quantity", "amount", "action_id", "transaction_time".

Artikelinteracties

["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"]

Voorbeelden

# 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"]
     ]' 

sessions_archive

Eén rij per bezoekerssessie (een aaneengesloten periode van activiteit). Ondersteund door de archieftabel met een lange levensduur — veel breder dan events, met metadata over locatie, apparaat, scherm en browser.

Identificerend / huishoudelijk

Geo / taalinstelling / apparaat

Tellers voor betrokkenheid

Landings-URL & verwijzer

UTM / advertentiecampagne

ad_campaign, ad_source, ad_medium, ad_term, ad_content — de standaard UTM-parameters zoals vastgelegd bij binnenkomst.

Voorbeelden

# 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'

Geïndexeerde kolommen: first_visit_id, user_id, plus verschillende andere. Query’s moeten filteren op een geïndexeerde kolom, anders wordt het verzoek geweigerd als scan van de volledige tabel.

user_interests

Interesses, categorieën, tags en tags voor familie/cross-sell/upsell per gebruiker, afgeleid door de pipeline van de tracker. Eén rij per (user_id, value, class, time). Alleen-lezen.

Kolommen

Geïndexeerde kolommen: user_id, time. Query’s moeten filteren op een geïndexeerde kolom.

Voorbeelden

# 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_*

Geaggregeerde interactietellers per product, bijgehouden door de offline pipeline voor samenvattingen. Zes doorlopende vensters zijn beschikbaar op aparte paden — kies het venster dat past bij je rapportagehorizon. Ze delen allemaal dezelfde kolomvorm en indexen; alleen het tijdvenster verschilt.

Endpoints

Identificerend

Tellers per product (aantal interacties met dit product binnen het venster)

Verdelingsstatistieken voor de hele catalogus

Dezelfde waarde op elke rij — beschrijft de hele catalogus binnen dit venster. Voor elke metriek M ∈ {viewed, delivered, extra, favorite, goal}:

Laatste 3 doelgebruikers (meest recente kopers van dit product)

Geïndexeerde kolommen

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. Query’s moeten filteren op (of order_by) een van deze.

Voorbeelden

# 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

Dagelijks geaggregeerde KPI’s per actie — één rij per (day, action_id) voor acties die aan een specifieke campagne zijn gekoppeld (condition_id). Alleen-lezen.

Identificerend

Blootstelling van de actie

Toeschrijving aan producten (als deze actie producten aanbeval)

Toeschrijving aan artikelen

Dezelfde vorm als bij de toeschrijving aan producten, maar voor artikelen: 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.

Eigen doelevents per account

Een account kan tot 12 doelevents instellen. Voor elke eventcontainer die in je account is ingesteld met een goal_event_index (N van 1 tot 12 die niet nul is, verschijnen er vier extra kolommen in het antwoord:

• goal_event_N_name — Weergavenaam van het ingestelde doelevent. Wordt teruggegeven als letterlijke tekenreeks, op elke rij hetzelfde.
• goal_event_N_n_times — Hoe vaak dit doelevent afging tijdens een sessie waarin de actie werd uitgevoerd.
• goal_event_N_n_sessions — In hoeveel afzonderlijke sessies dit doelevent minstens één keer afging nadat de actie was uitgevoerd.
• goal_event_N_value — Som van de geldwaarden die voor dit doelevent zijn gerapporteerd over de keren die zijn geteld in goal_event_N_n_times (nul, tenzij de container van het doelevent is ingesteld om een waarde vast te leggen).

Voorbeelden

# 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

Geeft het JS-snippet terug dat je op je site insluit om de Personyze-tracker op te starten. De inhoud wordt afgeleid uit de instellingen van je account (account-ID, trackinghost, vlaggen voor async/niet verbergen).

Antwoord

Een gewoon text/html -snippet (of JS in een<script>), klaar om in een <head>te plakken. De body is geen JSON — dit is het ene REST-endpoint dat ruwe HTML teruggeeft.

Voorbeeld

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>

Volgende stappen