L’API REST de Personyze permet à des applications tierces de lire et de modifier les données de votre compte : profils clients, catalogues de produits et d’articles, emplacements, actions, listes d’audience, résumés de rapports quotidiens — les mêmes données que celles qu’utilise l’interface de Personyze. Elle utilise le HTTPS standard, accepte et renvoie du JSON, et prend en charge les quatre verbes standard (GET, POST, PUT, DELETE).
Cette page est le point de départ. Pour la procédure de configuration complète, voir Authentification. Pour la syntaxe des paramètres de chemin (le schéma where/columns/order_by/limit présent dans chaque endpoint), voir Paramètres de chemin. Pour la liste des colonnes et des méthodes prises en charge par objet, voir Référence des objets.
Démarrage rapide
Récupérer l’utilisateur dont l’ID interne est 42:
curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'C’est la forme complète de chaque requête :
https://api:<API_KEY>@app.personyze.com/rest/<object>[/<modifier>/<value>...]- HTTPS uniquement. Le HTTP simple renvoie
401 Unauthorized— même pour les proxyslocalhost. - Authentification HTTP Basic avec le nom d’utilisateur
apiet votre clé API comme mot de passe (ou transmettez-la directement dans l’URL comme dans l’exemplecurlci-dessus). - Tous les arguments de chemin sont décodés (URL-decoded) avant l’analyse — les valeurs de colonnes contenant
/,=,&, ou%doivent être encodées en pourcentage.
Méthodes HTTP
| Méthode | Rôle | Corps | Renvoie |
|---|---|---|---|
GET |
lecture | aucun | Tableau d’enregistrements (ou un seul enregistrement avec la forme à ID unique) |
POST |
création | Objet JSON | ID numérique du nouvel enregistrement |
PUT |
mise à jour | Objet JSON | Nombre de lignes concernées |
DELETE |
suppression | aucun | Nombre de lignes concernées |
POST et PUT utilisent comme corps Content-Type: application/json. application/x-www-form-urlencoded est accepté en solution de repli pour les anciens clients, mais JSON est préférable.
Codes de réponse
| Code | Signification |
|---|---|
200 OK |
Succès — le corps dépend de la méthode (voir le tableau des méthodes HTTP ci-dessus). Les colonnes de type date sont sérialisées au format YYYY-MM-DD HH:MM:SS; les horodatages sont en secondes Unix, en UTC. |
400 Bad Request |
Votre saisie a été rejetée. Le corps est une description en texte brut lisible (par ex. “Cannot do this operation on whole table: column ‘uset_id’ is not indexed.”). Causes fréquentes : faute de frappe dans un nom de colonne, clause where absente sur une grande table, corps JSON mal formé. |
401 Unauthorized |
Clé API incorrecte ou absente, ou requête qui n’était pas en HTTPS. |
500 Internal Server Error |
Erreur inattendue du côté de l’API — message dans le corps. Mérite une nouvelle tentative après quelques secondes ; si le problème persiste, contactez le support. |
503 Service Unavailable |
Échec transitoire (deadlock, connexion à la base perdue, etc.). Vous pouvez réessayer sans risque, avec un délai progressif. |
Conventions communes aux endpoints
id ou internal_id
La plupart des objets exposent deux identifiants :
id— la clé primaire numérique interne de Personyze, attribuée automatiquement à l’insertion. Stable pour toujours, mais uniquement significative dans Personyze.internal_id— l’identifiant externe que vous fournissez (le SKU de votre boutique, l’ID utilisateur de votre CRM, etc.). Exposé pour les objets où la correspondance avec un système externe compte :users,products,articles.
Pour la plupart du code d’intégration, vous utiliserez internal_id — ainsi, le même code continue de fonctionner même si les mêmes données sont réimportées dans Personyze avec de nouveaux ids.
Colonnes indexées obligatoires sur les grandes tables
Les endpoints qui couvrent de grandes tables (users, events, sessions_archive, summary_actions, etc.) refusent les parcours complets de table. Vous devez inclure soit une clause where soit un order_by sur une colonne indexée. Les messages d’erreur listent les colonnes et composites indexés disponibles — voir Paramètres de chemin → Exigence de colonne indexée pour les règles complètes.
Index composites
Les index composites apparaissent dans les messages d’erreur sous la forme [col1, col2, col3]. Seule la colonne de tête d’un composite peut servir de filtre sur une seule colonne. Les autres colonnes ne deviennent utiles qu’en combinaison avec la colonne de tête.
Les clés API sont propres à chaque compte
Chaque compte Personyze auquel vous avez accès a sa propre clé API — elles ne sont pas interchangeables. Changer de compte, c’est changer de clé.
Limites et pagination
- 1 000 lignes maximum par requête. Utilisez
limit/<count>oulimit/<offset>,<count>pour contrôler la taille des pages. - Préférez la pagination par curseur aux décalages profonds. Parcourir la colonne indexée
order_byavec des conditionswherede type curseur est bien plus rapide que des valeursoffsetprofondes, qui relisent toutes les lignes sautées.
where au lieu de paginer par décalage. Par exemple, après avoir récupéré 1 000 utilisateurs triés par last_session_time décroissant, la page suivante doit utiliser where/last_session_time<<last_seen_value> plutôt que limit/1000,1000.Pour aller plus loin
curl/Python/JS, et l’accès multi-comptes. Lire →where / columns / order_by / limit avec tous les opérateurs et la composition AND/OR. Lire →Guides liés
- Configuration par type de site — suivi, flux et intégrations — choisissez votre point de départ selon votre type de site.
- Guide de l’action JavaScript — pour écrire des actions Personyze personnalisées qui s’exécutent dans le navigateur.
- Accéder aux données de campagne côté client — lire les ID et variables de campagne depuis JavaScript sur la page.