Synchroniser les personnes depuis votre propre API

La source Custom API relie Polzy à un système qui vous appartient — un outil RH interne, un CRM, une base de données derrière une API. Elle fonctionne de deux façons, et vous pouvez utiliser les deux :

• Récupération (pull). Polzy lit, selon le calendrier que vous choisissez, un point de terminaison HTTPS qui renvoie vos personnes en JSON.
• Envoi (push). Votre système envoie une personne à Polzy dès qu’elle change, signée avec un secret que vous partagez, et Polzy l’applique aussitôt.

Dans les deux cas, la même correspondance des champs transforme vos fiches en personnes dans Polzy.

Avant de commencer

Il vous faut :

• Être administrateur de l’espace de travail Polzy, sur Team ou plus, avec Synchronisation des personnes activé sous Paramètres → Général → Ce que fait cet espace de travail.
• Un point de terminaison accessible sur internet, servi en HTTPS, qui renvoie une liste JSON de personnes — et un développeur qui peut le modifier. Polzy n’appelle pas d’adresses privées ou internes.
• Un id unique pour chaque personne. Polzy s’en sert pour reconnaître les personnes d’une synchronisation à l’autre.
• Les champs selon lesquels vous voulez regrouper les résultats déjà ajoutés dans Polzy.

Un espace de travail se synchronise depuis une seule source à la fois. Si une autre source est connectée, déconnectez-la d’abord. Si votre organisation provisionne ses membres via SCIM, aucune source de personnes ne peut être connectée — voir SCIM.

Ce que renvoie votre point de terminaison

Une requête GET sur votre point de terminaison renvoie les personnes, sous forme de liste en tête de la réponse ou à un chemin à l’intérieur :

{
  "data": {
    "users": [
      {
        "id": "4821",
        "email": "anouk@acme.com",
        "first_name": "Anouk",
        "last_name": "Jansen",
        "phone": "+31612345678",
        "is_active": true,
        "department": "Sales",
        "manager_email": "rahul@acme.com"
      }
    ]
  },
  "meta": { "next_cursor": "eyJwYWdlIjoyfQ" }
}

Ici, Chemin des données (JSON) vaut data.users ; avec une simple liste en tête, laissez-le vide. Les chemins peuvent aussi entrer dans des listes, comme results[0].people.

Chaque requête a 30 secondes pour répondre. Si votre point de terminaison pagine, dites à Polzy comment :

• Par un lien ou un curseur. Indiquez le champ qui le contient dans Champ de page suivante, comme meta.next_cursor. Une adresse complète est appelée telle quelle ; un curseur est ajouté à l’adresse de votre point de terminaison sous la forme ?cursor=…, ou sous le nom indiqué dans Paramètre de page. Polzy s’arrête quand le champ est vide.
• Par numéro de page. Laissez Champ de page suivante vide et indiquez le nom du paramètre dans Paramètre de page, comme page. Polzy demande les pages 2, 3 et ainsi de suite, et s’arrête à la première page vide.

Polzy lit au plus 500 pages par synchronisation.

Connecter votre API dans Polzy

1. Ouvrez Contacts → Synchro et champs.
2. Sous Sources disponibles, trouvez Custom API et choisissez Connecter. Un panneau s’ouvre avec trois étapes : Connexion, Paramètres de synchro et Correspondance des champs.
3. Saisissez l’URL du point de terminaison API, puis le Chemin des données (JSON) et les champs de pagination si vous en avez besoin.
4. Choisissez le Type d'authentification et remplissez ce qu’il demande : un Bearer Token ; un Nom de l'en-tête API Key et une Valeur de l'API Key ; un Nom d'utilisateur et un Mot de passe pour l’Authentification de base ; ou rien pour Aucun. Ajoutez tout autre en-tête dont votre point de terminaison a besoin sous En-têtes personnalisés.
5. Pour l’envoi, saisissez une longue chaîne aléatoire comme Secret de signature des webhooks, et donnez la même chaîne à votre développeur. Sinon, laissez-le vide.
6. Choisissez Tester la connexion. Successfully connected to API. Found N users. signifie que Polzy a pu lire votre point de terminaison.
7. Choisissez Suivant, vérifiez les paramètres de synchronisation, choisissez de nouveau Suivant, associez les champs (plus bas), puis choisissez Connecter.

Synchro des personnes

Connecter Custom API

Les clés sont chiffrées et utilisées uniquement en votre nom.

2 sur 2 obligatoires

ConnexionParamètres de synchroCorrespondance des champs

Champ de page suivanteOptionnel

Paramètre de pageOptionnel

Secret de signature des webhooksOptionnel

URL du point de terminaison APIRequis

Type d'authentificationRequis

Bearer TokenOptionnel

Chiffré au reposAnnulerTester la connexionSuivant

Les jetons, mots de passe, le secret de signature et la valeur de chaque en-tête personnalisé sont stockés chiffrés et ne servent qu’à appeler votre point de terminaison.

Paramètres de synchronisation

Que vos personnes arrivent comme membres ou comme contacts dépend du public de votre espace de travail : des membres dans un espace pour des salariés, qui peuvent se connecter et occupent une place ; des contacts dans un espace pour des clients, des utilisateurs d’un produit ou des participants à un événement, qui se contentent de répondre.

Associer les champs

La correspondance par défaut lit email, first_name, last_name, phone et is_active. Tout le reste, vous l’associez vous-même : activez Correspondance personnalisée des champs et tapez, pour chaque champ, le chemin dans vos fiches qui le remplit — department, manager_email, plan, profile.country. La liste suggère des noms courants, et les chemins s’écrivent comme pour Chemin des données. Chaque ligne a aussi une valeur Si vide, utiliser, écrite quand une fiche n’a rien pour ce champ ; une valeur que votre API envoie n’est jamais écrasée.

Synchro des personnes

Connecter Custom API

Les clés sont chiffrées et utilisées uniquement en votre nom.

ConnexionParamètres de synchroCorrespondance des champs

Correspondance personnalisée des champs

Correspondance personnalisée active Choisissez quel champ de votre système RH alimente chaque champ de participant.

Champs de base

Champ du participantDepuis la sourceSi vide, utiliser

EmailRequis

Exemple: anouk@acme.com, rahul@acme.com

PrénomRequis

Exemple: Anouk, Rahul

Nom de familleRequis

Exemple: Jansen, Mehta

Champs de l'espace de travail

Champ du participantDepuis la sourceSi vide, utiliser

Service

Exemple: Ventes, Opérations

Chiffré au reposRetourConnecter

Quelques points à connaître :

• De vrais exemples. Une fois connecté, choisissez Paramètres sur Synchro et champs et rouvrez Correspondance des champs : les suggestions comprennent alors chaque chemin de cinq vraies fiches, chacun avec un Exemple.
• Statut actif. Une valeur false, 0, no, inactive, terminated, leave, disabled, suspended ou archived désactive la personne ; toute autre valeur, ou aucune, la laisse active.
• Managers. Associez Manager à un champ qui contient l’adresse e-mail, le matricule ou l’id dans votre API du manager. Le lien se fait quand le manager est lui aussi dans Polzy. Les managers demandent que Lignes hiérarchiques soit activé dans l’espace de travail.
• Seuls les champs de votre espace de travail sont remplis. Ajoutez un champ avec Ajouter un champ sur Synchro et champs avant de l’associer. Pour comparer les résultats selon ce champ, faites-en un champ Liste et activez Groupes.

Prévisualiser et lancer la première synchronisation

1. Sur Synchro et champs, choisissez Prévisualiser une synchro sous Historique de synchro. Polzy calcule ce qu’une synchronisation ajouterait, mettrait à jour et désactiverait, sans rien changer, et ouvre le journal où le résultat apparaît comme Aperçu.
2. Vérifiez l’aperçu, corrigez la correspondance sous Paramètres si nécessaire, puis choisissez Synchroniser maintenant.

Synchro et champs

Custom APIConnectéDernière synchro il y a 5 minutes · s’exécute toutes les heures · 152 personnes · 9 groupesParamètresSynchroniser maintenant

Historique de synchroPrévisualiser une synchro

Aujourd’hui, 09:12Réussi2 ajoutés · 5 mis à jour

Aujourd’hui, 08:10Partiel1 mis à jour · 3 ignorés

Hier, 16:40Aperçu152 ajoutés

Les personnes sont rapprochées par leur id, puis par adresse e-mail : une personne que vous aviez déjà ajoutée à la main est mise à jour au lieu d’être ajoutée une seconde fois.

Envoyer les changements au moment où ils se produisent

L’envoi transmet une personne à la fois à Polzy, signée, chaque fois qu’elle change. Les synchronisations planifiées continuent à côté et rattrapent ce qu’un envoi aurait manqué — Polzy a donc toujours besoin du point de terminaison ci-dessus, même s’il renvoie une liste vide.

1. Dans Polzy, ouvrez Intégrations, puis Custom API, et copiez l’adresse sous Réception. Elle est propre à votre connexion et se termine par /api.
2. Vérifiez que le même secret est enregistré dans Secret de signature des webhooks sous Paramètres et dans votre système.
3. Depuis votre système, envoyez un POST à cette adresse avec la personne en JSON et trois en-têtes :

Le corps est la personne, avec les mêmes noms de champs que ceux renvoyés par votre point de terminaison, pour que la même correspondance s’applique. Il peut aussi être enveloppé sous la forme { "user": { … } } ou { "employee": { … } }. Il doit contenir l’id et les champs qui ont changé — un corps avec un id seul est accepté mais ne change rien. Pour désactiver une personne, envoyez-la avec "is_active": false, ou avec ce que votre correspondance lit pour Statut actif.

En Node.js :

import crypto from 'node:crypto';

const body = JSON.stringify({
  id: '4821',
  email: 'anouk@acme.com',
  first_name: 'Anouk',
  last_name: 'Jansen',
  department: 'Operations',
  is_active: true,
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
  .createHmac('sha256', process.env.POLZY_SIGNING_SECRET)
  .update(`${timestamp}.${body}`)
  .digest('hex');

await fetch(process.env.POLZY_RECEIVING_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Polzy-Timestamp': timestamp,
    'X-Polzy-Signature': signature,
    'X-Polzy-Event-Id': 'person-4821-2026-10-31T09:12:00Z',
  },
  body,
});

En Python :

import hashlib, hmac, json, os, time, requests

body = json.dumps({"id": "4821", "email": "anouk@acme.com", "department": "Operations", "is_active": True})
timestamp = str(int(time.time()))
signature = hmac.new(
    os.environ["POLZY_SIGNING_SECRET"].encode(),
    f"{timestamp}.{body}".encode(),
    hashlib.sha256,
).hexdigest()

requests.post(
    os.environ["POLZY_RECEIVING_URL"],
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Polzy-Timestamp": timestamp,
        "X-Polzy-Signature": signature,
        "X-Polzy-Event-Id": "person-4821-2026-10-31T09:12:00Z",
    },
)

Signez exactement les octets que vous envoyez : sérialisez le corps une seule fois et envoyez cette même chaîne. Ce que Polzy répond :

Si votre espace de travail est en pause parce qu’il dépasse son offre, les appels sont acquittés et rien n’est appliqué.

Appels signés sans horodatage

La première version de l’envoi signait le corps seul, sans X-Polzy-Timestamp. Ces appels sont encore acceptés pour l’instant, et tant que votre système en envoie, Paramètres → API → Webhooks affiche un avertissement avec la date à partir de laquelle ils seront refusés. À partir de cette date, Polzy y répond par 401 et Calls without X-Polzy-Timestamp are refused since suivi de cette date. Passez à la signature ci-dessus avant — voir Webhooks.

Dépannage

Bon à savoir

• Limites. Une synchronisation qui dépasserait vos places ou vos contacts importe les personnes qui tiennent, s’arrête là et prévient les administrateurs — voir Utilisation et limites.
• Une personne par envoi. Envoyez un appel distinct pour chaque personne qui a changé.
• Déconnecter ou supprimer. Sous Paramètres, Déconnecter arrête la synchronisation et garde les paramètres et l’historique, pour reconnecter plus tard ; Supprimer efface la connexion. Dans les deux cas, les personnes déjà synchronisées restent dans Polzy et ne sont plus mises à jour, et les envois sont refusés.
• Le reste de l’API. Pour lire des résultats ou créer des actions depuis votre système, utilisez une clé d’API et la référence de l’API.