Personen aus Ihrer eigenen API synchronisieren

Die Quelle Custom API verbindet Polzy mit einem eigenen System — einem internen HR-Tool, einem CRM, einer Datenbank hinter einer API. Sie funktioniert auf zwei Wegen, und Sie können beide nutzen:

• Abrufen (Pull). Polzy liest nach einem Zeitplan Ihrer Wahl einen HTTPS-Endpunkt, der Ihre Personen als JSON zurückgibt.
• Senden (Push). Ihr System sendet eine Person in dem Moment an Polzy, in dem sie sich ändert, signiert mit einem gemeinsamen Secret, und Polzy übernimmt sie sofort.

In beiden Fällen macht dieselbe Feldzuordnung aus Ihren Datensätzen die Personen in Polzy.

Bevor Sie beginnen

Sie brauchen:

• Admin-Rechte im Polzy-Workspace, auf Team oder höher, mit eingeschalteter Personensynchronisierung unter Einstellungen → Allgemein → Was dieser Arbeitsbereich leistet.
• Einen Endpunkt im öffentlichen Internet, per HTTPS erreichbar, der eine JSON-Liste von Personen zurückgibt — und eine Entwicklerin oder einen Entwickler, der ihn ändern kann. Polzy ruft keine privaten oder internen Adressen auf.
• Eine eindeutige id für jede Person. Daran erkennt Polzy Personen von einer Synchronisierung zur nächsten.
• Die Felder, nach denen Sie Ergebnisse gruppieren möchten, bereits in Polzy angelegt.

Ein Workspace synchronisiert jeweils aus genau einer Quelle. Ist schon eine andere Quelle verbunden, trennen Sie diese zuerst. Stellt Ihre Organisation Personen über SCIM bereit, lässt sich überhaupt keine Quelle verbinden — siehe SCIM.

Was Ihr Endpunkt zurückgibt

Eine GET-Anfrage an Ihren Endpunkt gibt die Personen zurück, als Liste ganz oben in der Antwort oder an einem Pfad darin:

{
  "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" }
}

Hier ist Datenpfad (JSON) data.users; steht eine einfache Liste ganz oben, lassen Sie ihn leer. Pfade können auch in Listen greifen, etwa results[0].people.

Jede Anfrage hat 30 Sekunden Zeit für die Antwort. Blättert Ihr Endpunkt in Seiten, sagen Sie Polzy, wie:

• Per Link oder Cursor. Tragen Sie das Feld, das ihn enthält, in Feld für die nächste Seite ein, etwa meta.next_cursor. Eine vollständige Adresse wird so aufgerufen; ein Cursor wird als ?cursor=… an die Adresse Ihres Endpunkts angehängt, oder unter dem Namen in Seitenparameter. Polzy hört auf, wenn das Feld leer ist.
• Per Seitenzahl. Lassen Sie Feld für die nächste Seite leer und tragen Sie den Namen des Parameters in Seitenparameter ein, etwa page. Polzy fragt Seite 2, 3 und so weiter ab und hört bei der ersten leeren Seite auf.

Polzy liest höchstens 500 Seiten pro Synchronisierung.

Ihre API in Polzy verbinden

1. Öffnen Sie Kontakte → Sync und Felder.
2. Suchen Sie Custom API unter Verfügbare Quellen und wählen Sie Verbinden. Ein Bereich mit drei Schritten öffnet sich: Verbindung, Sync-Einstellungen und Feldzuordnung.
3. Tragen Sie Ihre API-Endpunkt-URL ein und, falls nötig, den Datenpfad (JSON) und die Felder für die Paginierung.
4. Wählen Sie den Authentifizierungstyp und füllen Sie aus, was er verlangt: ein Bearer Token; einen Name des API-Key-Headers und einen Wert des API Key; einen Benutzername und ein Passwort für die Basisauthentifizierung; oder nichts bei Keine. Fügen Sie jeden weiteren Header, den Ihr Endpunkt braucht, unter Benutzerdefinierte Header hinzu.
5. Für das Senden tragen Sie eine lange Zufallszeichenfolge als Webhook-Signatur-Secret ein und geben dieselbe Zeichenfolge an Ihre Entwicklung weiter. Andernfalls lassen Sie es leer.
6. Wählen Sie Verbindung testen. Successfully connected to API. Found N users. bedeutet, dass Polzy Ihren Endpunkt lesen konnte.
7. Wählen Sie Weiter, prüfen Sie die Sync-Einstellungen, wählen Sie erneut Weiter, ordnen Sie die Felder zu (unten) und wählen Sie dann Verbinden.

Personen-Sync

Custom API verbinden

Schlüssel werden verschlüsselt und nur in Ihrem Auftrag verwendet.

2 von 2 erforderlich

VerbindungSync-EinstellungenFeldzuordnung

Feld für die nächste SeiteOptional

SeitenparameterOptional

Webhook-Signatur-SecretOptional

API-Endpunkt-URLErforderlich

AuthentifizierungstypErforderlich

Bearer TokenOptional

Im Ruhezustand verschlüsseltAbbrechenVerbindung testenWeiter

Tokens, Passwörter, das Signatur-Secret und der Wert jedes benutzerdefinierten Headers werden verschlüsselt gespeichert und nur verwendet, um Ihren Endpunkt aufzurufen.

Sync-Einstellungen

Ob Ihre Personen als Mitglieder oder als Kontakte ankommen, richtet sich nach der Zielgruppe Ihres Workspace: Mitglieder in einem Workspace für Mitarbeitende, die sich anmelden können und einen Platz belegen; Kontakte in einem für Kunden, Produktnutzer oder Veranstaltungsgäste, die nur antworten.

Die Felder zuordnen

Die Standardzuordnung liest email, first_name, last_name, phone und is_active. Alles andere ordnen Sie selbst zu: Schalten Sie Benutzerdefinierte Feldzuordnung ein und tippen Sie für jedes Feld den Pfad in Ihren Datensätzen ein, der es füllt — department, manager_email, plan, profile.country. Die Liste schlägt gängige Namen vor, und die Pfade folgen derselben Schreibweise wie Datenpfad. Jede Zeile hat auch einen Wert bei Wenn leer, verwende, der eingetragen wird, wenn ein Datensatz für dieses Feld nichts enthält; ein Wert, den Ihre API sendet, wird nie überschrieben.

Personen-Sync

Custom API verbinden

Schlüssel werden verschlüsselt und nur in Ihrem Auftrag verwendet.

VerbindungSync-EinstellungenFeldzuordnung

Benutzerdefinierte Feldzuordnung

Benutzerdefinierte Zuordnung aktiv Wählen Sie aus, welches Feld aus Ihrem HR-System jedes Teilnehmerfeld befüllt.

Kernfelder

TeilnehmerfeldAus der QuelleWenn leer, verwende

E-MailErforderlich

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

VornameErforderlich

Beispiel: Anouk, Rahul

NachnameErforderlich

Beispiel: Jansen, Mehta

Workspace-Felder

TeilnehmerfeldAus der QuelleWenn leer, verwende

Abteilung

Beispiel: Vertrieb, Betrieb

Im Ruhezustand verschlüsseltZurückVerbinden

Gut zu wissen:

• Echte Beispiele. Wählen Sie nach dem Verbinden Einstellungen auf Sync und Felder und öffnen Sie Feldzuordnung erneut: Die Vorschläge enthalten dann jeden Pfad aus fünf echten Datensätzen, jeweils mit einem Beispiel.
• Aktiv-Status. Ein Wert false, 0, no, inactive, terminated, leave, disabled, suspended oder archived deaktiviert die Person; jeder andere Wert, oder keiner, lässt sie aktiv.
• Führungskräfte. Ordnen Sie Führungskraft einem Feld zu, das E-Mail-Adresse, Personalnummer oder id der Führungskraft in Ihrer API enthält. Die Verknüpfung entsteht, wenn die Führungskraft ebenfalls in Polzy ist. Dafür muss Berichtslinien im Workspace eingeschaltet sein.
• Nur Felder Ihres Workspace werden gefüllt. Legen Sie ein Feld mit Feld hinzufügen auf Sync und Felder an, bevor Sie es zuordnen. Um Ergebnisse danach zu vergleichen, machen Sie es zu einem Liste-Feld und schalten Gruppen ein.

Vorschau und erste Synchronisierung

1. Wählen Sie auf Sync und Felder unter Sync-Verlauf die Option Sync-Vorschau. Polzy ermittelt, was eine Synchronisierung hinzufügen, aktualisieren und deaktivieren würde, ohne etwas zu ändern, und öffnet das Protokoll, in dem das Ergebnis als Vorschau erscheint.
2. Prüfen Sie die Vorschau, passen Sie bei Bedarf die Zuordnung unter Einstellungen an und wählen Sie dann Jetzt synchronisieren.

Sync und Felder

Custom APIVerbundenLetzter Sync vor 5 Minuten · läuft stündlich · 152 Personen · 9 GruppenEinstellungenJetzt synchronisieren

Sync-VerlaufSync-Vorschau

Heute, 09:12Erfolgreich2 hinzugefügt · 5 aktualisiert

Heute, 08:10Teilweise1 aktualisiert · 3 übersprungen

Gestern, 16:40Vorschau152 hinzugefügt

Personen werden an ihrer id erkannt und danach an ihrer E-Mail-Adresse. Wen Sie schon von Hand angelegt hatten, wird also aktualisiert statt doppelt angelegt.

Änderungen senden, sobald sie passieren

Beim Senden übermitteln Sie jeweils eine Person signiert an Polzy, sobald sie sich ändert. Geplante Synchronisierungen laufen daneben weiter und holen nach, was ein gesendeter Datensatz verpasst hat — Polzy braucht den Endpunkt oben also weiterhin, auch wenn er eine leere Liste zurückgibt.

1. Öffnen Sie in Polzy Integrationen, dann Custom API, und kopieren Sie die Adresse unter Empfang. Sie ist für Ihre Verbindung erzeugt und endet auf /api.
2. Stellen Sie sicher, dass dasselbe Secret unter Einstellungen in Webhook-Signatur-Secret und in Ihrem System gespeichert ist.
3. Senden Sie aus Ihrem System einen POST an diese Adresse, mit der Person als JSON und drei Headern:

Der Body ist die Person, mit denselben Feldnamen, die Ihr Endpunkt zurückgibt, sodass dieselbe Zuordnung gilt. Er darf auch als { "user": { … } } oder { "employee": { … } } verpackt sein. Er muss die id und die geänderten Felder enthalten — ein Body mit nur einer id wird angenommen, ändert aber nichts. Um jemanden zu deaktivieren, senden Sie die Person mit "is_active": false, oder mit dem, was Ihre Zuordnung für Aktiv-Status liest.

In 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,
});

In 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",
    },
)

Signieren Sie genau die Bytes, die Sie senden: Serialisieren Sie den Body einmal und senden Sie genau diese Zeichenfolge. Was Polzy antwortet:

Ist Ihr Workspace pausiert, weil er seinen Plan überschreitet, werden Aufrufe bestätigt, aber nichts wird übernommen.

Aufrufe ohne Zeitstempel signiert

Die erste Version des Sendens signierte nur den Body, ohne X-Polzy-Timestamp. Solche Aufrufe werden vorerst noch angenommen, und solange Ihr System sie sendet, warnt Einstellungen → API → Webhooks mit dem Datum, ab dem sie abgelehnt werden. Ab diesem Datum beantwortet Polzy sie mit 401 und Calls without X-Polzy-Timestamp are refused since gefolgt von diesem Datum. Stellen Sie vorher auf die Signatur oben um — siehe Webhooks.

Fehlerbehebung

Gut zu wissen

• Limits. Eine Synchronisierung, die Ihre Plätze oder Kontakte überschreiten würde, übernimmt, wer hineinpasst, hält dort an und informiert die Admins — siehe Nutzung und Limits.
• Eine Person pro Aufruf. Senden Sie für jede geänderte Person einen eigenen Aufruf.
• Trennen oder entfernen. Unter Einstellungen beendet Trennen die Synchronisierung und behält Einstellungen und Verlauf, sodass Sie später wieder verbinden können; Entfernen löscht die Verbindung. In beiden Fällen bleiben die bereits synchronisierten Personen in Polzy und werden nicht mehr aktualisiert, und gesendete Änderungen werden abgelehnt.
• Der Rest der API. Um aus Ihrem System Ergebnisse zu lesen oder Maßnahmen anzulegen, verwenden Sie einen API-Schlüssel und die API-Referenz.