Mensen synchroniseren vanuit je eigen API

De bron Custom API verbindt Polzy met een eigen systeem — een interne HR-tool, een CRM, een database achter een API. Het werkt op twee manieren, en je kunt ze allebei gebruiken:

• Ophalen (pull). Polzy leest volgens een schema dat jij kiest een HTTPS-endpoint dat je mensen als JSON teruggeeft.
• Doorsturen (push). Je systeem stuurt één persoon naar Polzy op het moment dat die verandert, ondertekend met een geheim dat jullie delen, en Polzy verwerkt het meteen.

In beide gevallen maakt dezelfde veldkoppeling van jouw records de mensen in Polzy.

Voordat je begint

Je hebt nodig:

• Beheerder zijn van de Polzy-werkruimte, op Team of hoger, met Deelnemers synchroniseren ingeschakeld onder Instellingen → Algemeen → Wat deze werkruimte doet.
• Een endpoint op het openbare internet, via HTTPS, dat een JSON-lijst van mensen teruggeeft — en een ontwikkelaar die het kan aanpassen. Polzy roept geen privé- of interne adressen aan.
• Een unieke id bij elke persoon. Daarmee herkent Polzy mensen van de ene synchronisatie op de andere.
• De velden waarop je resultaten wilt groeperen, al toegevoegd in Polzy.

Een werkruimte synchroniseert uit één bron tegelijk. Is er al een andere bron gekoppeld, koppel die dan eerst los. Levert je organisatie mensen aan via SCIM, dan kan er helemaal geen bron worden gekoppeld — zie SCIM.

Wat je endpoint teruggeeft

Een GET-verzoek aan je endpoint geeft de mensen terug, als lijst bovenaan het antwoord of op een pad daarbinnen:

{
  "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 is Gegevenspad (JSON) data.users; staat er een gewone lijst bovenaan, laat het dan leeg. Paden kunnen ook in lijsten verwijzen, zoals results[0].people.

Elk verzoek heeft 30 seconden om te antwoorden. Verdeelt je endpoint de resultaten over pagina's, vertel Polzy dan hoe:

• Met een link of cursor. Zet het veld waarin die staat in Veld voor volgende pagina, zoals meta.next_cursor. Een volledig adres wordt zo aangeroepen; een cursor wordt aan het adres van je endpoint toegevoegd als ?cursor=…, of onder de naam in Paginaparameter. Polzy stopt als het veld leeg is.
• Met een paginanummer. Laat Veld voor volgende pagina leeg en zet de naam van de parameter in Paginaparameter, zoals page. Polzy vraagt pagina 2, 3 enzovoort op, en stopt bij de eerste lege pagina.

Polzy leest hoogstens 500 pagina's per synchronisatie.

Je API koppelen in Polzy

1. Open Contacten → Synchronisatie en velden.
2. Zoek Custom API onder Beschikbare bronnen en kies Verbinden. Er opent een paneel met drie stappen: Verbinding, Synchronisatie-instellingen en Veldkoppeling.
3. Vul je API-eindpunt-URL in, en het Gegevenspad (JSON) en de pagineringsvelden als je die nodig hebt.
4. Kies het Type authenticatie en vul in wat erbij hoort: een Bearer Token; een Naam van de API Key-header en een Waarde van de API Key; een Gebruikersnaam en Wachtwoord voor Basisauthenticatie; of niets bij Geen. Voeg elke andere header die je endpoint nodig heeft toe onder Aangepaste headers.
5. Voor doorsturen vul je een lange willekeurige tekenreeks in als Ondertekengeheim voor webhooks, en geef je dezelfde reeks aan je ontwikkelaar. Laat het anders leeg.
6. Kies Verbinding testen. Successfully connected to API. Found N users. betekent dat Polzy je endpoint kon lezen.
7. Kies Volgende, controleer de synchronisatie-instellingen, kies nog eens Volgende, koppel de velden (hieronder) en kies dan Verbinden.

Personensynchronisatie

Custom API koppelen

Sleutels worden versleuteld en alleen namens jou gebruikt.

2 van 2 verplicht

VerbindingSynchronisatie-instellingenVeldkoppeling

Veld voor volgende paginaOptioneel

PaginaparameterOptioneel

Ondertekengeheim voor webhooksOptioneel

API-eindpunt-URLVerplicht

Type authenticatieVerplicht

Bearer TokenOptioneel

Versleuteld opgeslagenAnnulerenVerbinding testenVolgende

Tokens, wachtwoorden, het ondertekengeheim en de waarde van elke aangepaste header worden versleuteld opgeslagen en alleen gebruikt om je endpoint aan te roepen.

Synchronisatie-instellingen

Of je mensen als leden of als contacten binnenkomen, volgt het publiek van je werkruimte: leden in een werkruimte voor medewerkers, die zich kunnen aanmelden en een plek gebruiken; contacten in een werkruimte voor klanten, productgebruikers of eventgasten, die alleen antwoorden.

De velden koppelen

De standaardkoppeling leest email, first_name, last_name, phone en is_active. De rest koppel je zelf: zet Aangepaste veldkoppeling aan en typ voor elk veld het pad in je records dat het vult — department, manager_email, plan, profile.country. De lijst stelt gangbare namen voor, en de paden gebruiken dezelfde notatie als Gegevenspad. Elke rij heeft ook een waarde bij Indien leeg, gebruik, die wordt ingevuld als een record niets voor dat veld heeft; een waarde die je API wél stuurt, wordt nooit overschreven.

Personensynchronisatie

Custom API koppelen

Sleutels worden versleuteld en alleen namens jou gebruikt.

VerbindingSynchronisatie-instellingenVeldkoppeling

Aangepaste veldkoppeling

Aangepaste koppeling actief Kies welk veld uit je HR-systeem elk deelnemersveld vult.

Kernvelden

DeelnemersveldUit de bronIndien leeg, gebruik

E-mailVerplicht

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

VoornaamVerplicht

Voorbeeld: Anouk, Rahul

AchternaamVerplicht

Voorbeeld: Jansen, Mehta

Werkruimtevelden

DeelnemersveldUit de bronIndien leeg, gebruik

Afdeling

Voorbeeld: Verkoop, Operations

Versleuteld opgeslagenTerugVerbinden

Goed om te weten:

• Echte voorbeelden. Kies na het koppelen Instellingen op Synchronisatie en velden en open Veldkoppeling opnieuw: de suggesties bevatten dan elk pad uit vijf echte records, elk met een Voorbeeld.
• Actieve status. Een waarde false, 0, no, inactive, terminated, leave, disabled, suspended of archived deactiveert de persoon; elke andere waarde, of geen, houdt hem actief.
• Leidinggevenden. Koppel Leidinggevende aan een veld met het e-mailadres, het personeelsnummer of de id in je API van de leidinggevende. De koppeling wordt gelegd als die leidinggevende ook in Polzy staat. Daarvoor moet Rapportagelijnen in de werkruimte aan staan.
• Alleen velden van je werkruimte worden gevuld. Voeg een veld toe met Veld toevoegen op Synchronisatie en velden voordat je het koppelt. Wil je resultaten erop vergelijken, maak er dan een Lijst-veld van en zet Groepen aan.

Vooraf bekijken en de eerste synchronisatie uitvoeren

1. Kies op Synchronisatie en velden onder Synchronisatiegeschiedenis de optie Synchronisatie vooraf bekijken. Polzy rekent uit wat een synchronisatie zou toevoegen, bijwerken en deactiveren, zonder iets te wijzigen, en opent het logboek waar het resultaat als Voorbeeld verschijnt.
2. Bekijk het voorbeeld, pas zo nodig de koppeling aan onder Instellingen, en kies dan Nu synchroniseren.

Synchronisatie en velden

Custom APIVerbondenLaatste synchronisatie 5 minuten geleden · draait elk uur · 152 mensen · 9 groepenInstellingenNu synchroniseren

SynchronisatiegeschiedenisSynchronisatie vooraf bekijken

Vandaag, 09:12Gelukt2 toegevoegd · 5 bijgewerkt

Vandaag, 08:10Gedeeltelijk1 bijgewerkt · 3 overgeslagen

Gisteren, 16:40Voorbeeld152 toegevoegd

Mensen worden herkend aan hun id en daarna aan hun e-mailadres. Iemand die je al met de hand had toegevoegd, wordt dus bijgewerkt in plaats van dubbel toegevoegd.

Wijzigingen doorsturen op het moment dat ze gebeuren

Bij doorsturen stuur je steeds één persoon ondertekend naar Polzy, telkens als die verandert. Geplande synchronisaties blijven ernaast draaien en halen op wat een doorgestuurde wijziging heeft gemist — Polzy heeft het endpoint hierboven dus nog steeds nodig, ook als dat een lege lijst teruggeeft.

1. Open in Polzy Integraties, dan Custom API, en kopieer het adres onder Ontvangen. Het is voor jouw koppeling gemaakt en eindigt op /api.
2. Zorg dat hetzelfde geheim is opgeslagen in Ondertekengeheim voor webhooks onder Instellingen en in je systeem.
3. Stuur vanuit je systeem een POST naar dat adres met de persoon als JSON en drie headers:

De body is de persoon, met dezelfde veldnamen die je endpoint teruggeeft, zodat dezelfde koppeling geldt. Hij mag ook verpakt zijn als { "user": { … } } of { "employee": { … } }. Hij moet de id bevatten en de velden die zijn gewijzigd — een body met alleen een id wordt geaccepteerd maar verandert niets. Wil je iemand deactiveren, stuur die persoon dan met "is_active": false, of met wat je koppeling leest voor Actieve status.

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

Onderteken precies de bytes die je verstuurt: zet de body één keer om naar tekst en verstuur diezelfde tekenreeks. Wat Polzy antwoordt:

Is je werkruimte gepauzeerd omdat die over het abonnement heen gaat, dan worden aanroepen bevestigd maar wordt er niets verwerkt.

Aanroepen ondertekend zonder tijdstempel

De eerste versie van doorsturen ondertekende alleen de body, zonder X-Polzy-Timestamp. Die aanroepen worden voorlopig nog geaccepteerd, en zolang je systeem ze stuurt, waarschuwt Instellingen → API → Webhooks met de datum vanaf wanneer ze worden geweigerd. Vanaf die datum beantwoordt Polzy ze met 401 en Calls without X-Polzy-Timestamp are refused since die datum. Stap vóór die tijd over op de handtekening hierboven — zie Webhooks.

Problemen oplossen

Goed om te weten

• Limieten. Een synchronisatie die boven je plekken of contacten uitkomt, importeert wie past, stopt daar en laat het beheerders weten — zie Gebruik en limieten.
• Eén persoon per aanroep. Stuur voor elke gewijzigde persoon een aparte aanroep.
• Loskoppelen of verwijderen. Onder Instellingen stopt Loskoppelen de synchronisatie en blijven de instellingen en de geschiedenis bewaard, zodat je later opnieuw kunt verbinden; Verwijderen wist de koppeling. In beide gevallen blijven de al gesynchroniseerde mensen in Polzy staan en worden ze niet meer bijgewerkt, en worden doorgestuurde wijzigingen geweigerd.
• De rest van de API. Wil je vanuit je systeem resultaten lezen of acties aanmaken, gebruik dan een API-sleutel en de API-referentie.