Référence des objets de l’API REST

Référence de tous les objets exposés par l’API REST de Personyze. Chaque section ci-dessous couvre un objet : son rôle, les méthodes HTTP prises en charge, ses colonnes (avec type et remarques sur l’indexation), et des exemples curl prêts à l’emploi.

Prérequis — à lire d’abord si ce n’est pas déjà fait :

• Présentation de l’API REST et démarrage rapide — forme des requêtes, méthodes HTTP, codes de réponse
• Authentification — obtenir votre clé API, l’envoyer, configurations multi-comptes
• Paramètres de chemin — la syntaxe where/columns/order_by/limit utilisée dans tous les exemples ci-dessous

Index des objets

Cliquez sur un objet pour aller à sa section. Chaque section a sa propre ancre : vous pouvez créer un lien direct vers la référence de n’importe quel objet.

Contenu CRUD (lecture/écriture)

Contient vos campagnes, votre audience, votre catalogue et votre configuration. CRUD complet pour External API user et au-dessus.

Interactions / événements (surtout en écriture)

Journaux en ajout seul des interactions des visiteurs. Surtout utilisés par les SDK et les intégrations back-end.

Rapports / archive (lecture seule)

Aides pour le tracker et les SDK

Utilisés par le tracker JS, les SDK natifs et les intégrations pour s’amorcer eux-mêmes. Généralement pas appelés directement par les clients de l’API REST.

users

Profils clients. Chaque ligne est un visiteur ou un client. Les noms de colonnes sont dynamiques — au-delà des colonnes de gestion documentées, vous pouvez stocker toutes les clés/valeurs personnalisées dont votre compte a besoin.

Colonnes d’identification / de gestion

Champs de profil courants (personnalisés)

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 (texte), custom_i_1…custom_i_4 (entier), custom_f_1…custom_f_2 (flottant), custom_d_1, custom_d_2 (date) — et tous les champs supplémentaires configurés sur votre compte.

Exemples

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

Colonnes indexées / limites de parcours

GET /rest/users sans where exige order_by sur une colonne indexée — user_id, last_session_time, data_last_modified, fb_id, email, ou internal_id. Sinon : 400 Cannot do this operation on whole table.

Limitation du débit

POST /rest/users est sérialisé par compte Personyze : au plus une insertion en cours à la fois. Les requêtes qui attendent plus d’une seconde sont rejetées avec 400 Too many simultaneous requests — réessayez avec un délai exponentiel.

user_lists

Listes nommées d’utilisateurs (par exemple « VIP », « Inscrits à la newsletter »). Une ligne par liste. L’appartenance se trouve dans un objet distinct — voir user_list_users.

Colonnes

Exemples

# 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

Appartenance : quels utilisateurs appartiennent à quelles user_lists. Une ligne par paire (user_list_id, user_id) .

POST accepte soit un user_idexistant, soit une clé de recherche (user_internal_id, user_email) — l’API la résout en user_id, en créant si nécessaire une ligne users minimale.

Colonnes

Champs supplémentaires du corps POST (résolus en user_id côté serveur, puis supprimés)

Exemples

# 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

Actions de personnalisation — ce que font vos campagnes : afficher du HTML, montrer une popup, envoyer un e-mail, envoyer une notification, etc. En lecture seule via REST pour l’instant (création et modification via l’interface).

Colonnes

Exemples

# 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

Conditions d’audience — le quand des campagnes. En lecture seule via REST.

Colonnes

Exemples

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

placeholders

Conteneurs de type placeholder — emplacements du DOM où les actions affichent du contenu. Gérez le catalogue des emplacements définis pour votre site.

Colonnes

Exemples

# 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

Les conteneurs « grab variable » — récupèrent des valeurs DOM/JS de la page du visiteur vers son profil. Chaque conteneur indique « surveiller cette variable / cet élément du DOM ; quand il apparaît, le capturer comme champ de profil ».

Colonnes

Exemples

# 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

Catalogue de produits. Chaque ligne est un SKU. Les noms de colonnes sont dynamiques — au-delà des colonnes de gestion documentées, vous pouvez stocker tous les champs personnalisés dont votre catalogue a besoin.

Colonnes d’identification / de gestion

Champs de produit courants (personnalisés)

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, etc. L’ensemble réel des champs dépend de la configuration de votre compte.

Entrées renommées (en POST / PUT)

Exemples

# 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

Catalogue d’articles (billets de blog, actualités, entrées de base de connaissances). Même forme que products mais pour le contenu éditorial.

Colonnes d’identification / de gestion

Champs d’article courants (personnalisés)

title, description_short, description_long, image_big_url, image_medium_url, image_small_url, author, publish_date, category, tags, rank, etc. La liste réelle dépend de la configuration other_columns_info de votre site.

Entrées renommées

Exemples

# 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

Journal des interactions sur les produits : vues, ajouts au panier, achats, « favori », « livré ». Principalement en ajout. Adossé à une table d’archive.

Colonnes

Insertion : identifier l’utilisateur

POST accepte l’un de ces champs pour identifier l’utilisateur :

Exemples

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

Colonnes indexées

user_id, [product_internal_id, user_id, transaction_time], status, time. Les requêtes sans where sur l’une d’elles (ou sans order_by sur ces mêmes colonnes) sont rejetées comme parcours de table complet.

events

Journal d’événements générique — une ligne par événement suivi, capturé par le tracker JS, le SDK ou le point de terminaison do . En lecture seule via REST pour l’instant.

Colonnes

Exemples

# 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

Journal des envois de formulaires. Une ligne par envoi de formulaire capturé par le tracker. En lecture seule via REST pour l’instant.

Colonnes

Le JSON data est automatiquement développé en clés de premier niveau à la lecture — demandez des champs personnalisés précis par leur nom.

Exemples

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

Les colonnes indexées comprennent user_id, action_id, et time. Les requêtes doivent filtrer sur l’une d’elles.

do

Répartiteur de commandes « envoyer et oublier » : envoyez une mise à jour de profil utilisateur ou un événement d’interaction sans parler le protocole du tracker. Le corps est un tableau de commandes ; chacune est traitée indépendamment.

Forme de la requête

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

• <key-type>: "user_id", "internal_id", ou "email". Facultatif — à omettre pour les commandes qui ne visent pas un utilisateur.
• <key-value>: l’identifiant correspondant.
• <command>: une chaîne (insensible à la casse). Voir la liste ci-dessous.
• <arg…>: arguments positionnels propres à la commande.

Un POST réussi ne renvoie rien ; les échecs lèvent une erreur (tout le lot s’arrête à la première erreur).

Commandes

Profil utilisateur

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

Après le nom de la commande, les arguments alternent field, value, field, value, …

Interactions produit

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

Après le SKU, des paires clé-valeur facultatives : "quantity", "amount", "action_id", "transaction_time".

Interactions avec les articles

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

Exemples

# 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

Une ligne par session de visiteur (une fenêtre d’activité continue). Adossé à la table d’archive de longue durée — bien plus large que events, avec les métadonnées de localisation, d’appareil, d’écran et de navigateur.

Identification / gestion

Géo / langue / appareil

Compteurs d’engagement

URL d’arrivée et référent

UTM / campagne publicitaire

ad_campaign, ad_source, ad_medium, ad_term, ad_content — les paramètres UTM standard tels que capturés à l’arrivée.

Exemples

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

Colonnes indexées : first_visit_id, user_id, plus plusieurs autres. Les requêtes doivent filtrer sur une colonne indexée, sinon la requête est rejetée comme parcours de table complet.

user_interests

Centres d’intérêt, catégories, tags et tags famille / croisé / montée en gamme déduits par utilisateur par le pipeline du tracker. Une ligne par (user_id, value, class, time). En lecture seule.

Colonnes

Colonnes indexées : user_id, time. Les requêtes doivent filtrer sur une colonne indexée.

Exemples

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

Compteurs d’interactions agrégés par produit, maintenus par le pipeline de synthèse hors ligne. Six fenêtres glissantes sont exposées sur des chemins distincts — choisissez celle qui correspond à votre horizon de rapport. Toutes partagent la même forme de colonnes et les mêmes index ; seule la fenêtre de temps diffère.

Points de terminaison

Identification

Compteurs par produit (nombre d’interactions sur ce produit dans la fenêtre)

Statistiques de distribution sur tout le catalogue

La même valeur sur chaque ligne — décrit l’ensemble du catalogue dans cette fenêtre. Pour chaque indicateur M ∈ {viewed, delivered, extra, favorite, goal}:

Les 3 derniers utilisateurs ayant atteint l’objectif (acheteurs les plus récents de ce produit)

Colonnes indexées

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. Les requêtes doivent filtrer sur l’une de ces colonnes (ou utiliser order_by) sur l’une d’elles.

Exemples

# 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

KPI quotidiens agrégés par action — une ligne par (day, action_id) pour les actions liées à une campagne précise (condition_id). En lecture seule.

Identification

Exposition de l’action

Attribution produit (quand cette action a recommandé des produits)

Attribution des articles

Même forme que l’attribution produit, mais pour les articles : 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.

Événements d’objectif personnalisés par compte

Un compte peut configurer jusqu’à 12 événements d’objectif. Pour chaque conteneur d’événement configuré sur votre compte avec un goal_event_index (N de 1 à 12), quatre colonnes supplémentaires apparaissent dans la réponse :

• goal_event_N_name — Nom affiché de l’événement d’objectif configuré. Renvoyé comme chaîne littérale, identique sur chaque ligne.
• goal_event_N_n_times — Nombre de fois où cet événement d’objectif s’est déclenché pendant une session où l’action a été exécutée.
• goal_event_N_n_sessions — Nombre de sessions distinctes où cet événement d’objectif s’est déclenché au moins une fois après l’exécution de l’action.
• goal_event_N_value — Somme des valeurs monétaires signalées pour cet événement d’objectif sur les occurrences comptées dans goal_event_N_n_times (zéro sauf si le conteneur de l’événement d’objectif est configuré pour capturer une valeur).

Exemples

# 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

Renvoie l’extrait JS à intégrer dans votre site pour amorcer le tracker Personyze. Son contenu dépend des réglages de votre compte (identifiant de compte, hôte de suivi, options async/no-hide).

Réponse

Un extrait text/html (ou du JS dans<script>) prêt à être placé dans un <head>. Le corps n’est pas du JSON — c’est le seul point de terminaison REST qui renvoie du HTML brut.

Exemple

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>

Étapes suivantes