Payroll koppeling
HiBob Paychex Flex koppeling: nieuwe Amerikaanse medewerkers uit Bob klaargezet in Paychex Flex
Een koppeling tussen HiBob en Paychex Flex maakt een nieuwe medewerker van de Amerikaanse entiteit in Bob aan als worker in Paychex Flex, met naam, workertype, personeelsnummer en startdatum. Paychex zet zo'n worker op IN_PROGRESS, waarna de medewerker of de Flex-beheerder belastingformulieren en bankgegevens in Flex invult.
Wat de koppeling doet
Organisaties die HR in HiBob doen en de Amerikaanse lonen in Paychex Flex laten draaien, leggen nieuwe Amerikaanse collega's eerst in Bob vast. Daarna maakt iemand ze met dezelfde naam en startdatum nog eens aan in Flex, vaak pas als de eerste loonrun eraan komt.
- De Flex-beheerder keurt de partnerapp goed onder Company Settings, Integrated Applications.
- Bob meldt een nieuwe medewerker; KoppelHet controleert of die bij de Amerikaanse entiteit hoort en een werknemer is.
- KoppelHet maakt de worker aan in het juiste Paychex-bedrijf en bewaart alleen een workerId uit een geslaagd antwoord.
- In Flex vullen medewerker en beheerder de overige payrollgegevens aan.
- Elke dag vergelijkt KoppelHet de Amerikaanse nieuwe medewerkers in Bob met de workers in Flex en meldt verschillen.
Waar je op let bij HiBob en Paychex Flex
- KoppelHet bouwt deze koppeling op de API van Paychex. De Payroll Hub-API die HiBob payrollleveranciers aanbiedt, is nog in early access.
- Paychex vraagt voor een nieuwe worker alleen voornaam, achternaam en workertype. Alles wat Paychex Flex daarnaast verplicht stelt, bepaalt de inrichting van de klant, en zolang dat ontbreekt blijft de worker IN_PROGRESS. KoppelHet stuurt dus het minimum uit Bob en laat de rest in Flex afmaken.
- Via de API kent Paychex alleen EMPLOYEE, een W-2-werknemer, en INDEPENDENT_CONTRACTOR, een 1099-kracht; het type CONTRACTOR kan niet. Wie in Bob als contractor bij de Amerikaanse entiteit staat, gaat daarom niet automatisch mee; KoppelHet meldt die aan payroll.
- In het voorbeeld van Paychex komt bij meerdere workers per verzoek een andere workerCorrelationId terug dan er is meegestuurd. KoppelHet vertrouwt daar niet op alleen, maar koppelt elke workerId ook op het personeelsnummer uit Bob terug aan de juiste medewerker.
- Bij een vergrendeld Paychex-account geeft de API een 423, terwijl er soms toch een workerId is aangemaakt. Paychex zegt dat ID niet te gebruiken. KoppelHet bewaart alleen ID's uit een antwoord met status 200 en probeert de medewerker uit Bob opnieuw zodra het account weer open is.
- HiBob laat velden waarop de service user geen leesrecht heeft zonder melding weg. Zonder rechten op de Amerikaanse entiteit ziet KoppelHet dus geen nieuwe medewerkers; de service user krijgt rechten op alleen die populatie, zodat salarissen uit andere landen buiten de koppeling blijven.
- Paychex geeft toegang per klantbedrijf via een partnerapp. KoppelHet vraagt toegang aan met het achtcijferige displayId van het Paychex-bedrijf, en pas na goedkeuring door de Flex-beheerder kan de eerste medewerker uit Bob erin.
Hoe we het bouwen en beheren
- De koppeling draait op het KoppelHet platform, gehost in een datacenter in de EU.
- Elke synchronisatie en elke fout is zichtbaar in de functionele logging; bij een fout krijgt jullie beheerder een melding.
- Een mutatie die niet door kan, wordt niet half doorgezet maar klaargezet om opnieuw te proberen.
- KoppelHet is ISO 27001-gecertificeerd. Gegevens gaan versleuteld over en blijven niet langer op het platform dan nodig.
- Na livegang beheren wij de koppeling en passen we hem aan als jullie proces verandert.
- De koppeling past naast je bestaande integratielaag. Alleen de velden uit het ontwerp gaan over; het platform houdt geen eigen registratie bij.
Implementatie en prijs
Dit is geen app die je aanzet. We bouwen de koppeling voor jullie organisatie op ons platform, met bouwstenen die we steeds opnieuw gebruiken. Zo is het maatwerk, zonder dat we bij nul beginnen.
Een consultant bereidt de intake voor en analyseert beide systemen. Daarna leggen we de mapping en uitzonderingen per veld vast, testen we in de test- of acceptatieomgeving en gaan we live op een moment dat jij kiest. De kosten bestaan uit een eenmalig bedrag voor de inrichting en een maandbedrag voor platform, monitoring en beheer.
Veelgestelde vragen
Gaan salariswijzigingen ook mee?
Niet in de eerste versie. De koppeling begint bij nieuwe medewerkers; salariswijzigingen kunnen later als uitbreiding.
Wie vult de W-4 en de bankrekening in?
De medewerker of de Flex-beheerder, in Paychex Flex. Die gegevens staan meestal niet in Bob.
Technische details voor IT
Voor wie wil weten hoe het onder de motorkap werkt: gebruikte API's, velden en bronnen.
- HiBob via ondertekende webhooks voor employee events en de People API (POST /v1/people/search met gekozen velden), met een service user die alleen de Amerikaanse entiteit ziet.
- Paychex via https://api.paychex.com met een partnerapp (één key en secret); toegang per klant via /management/requestclientaccess met het displayId. Aanmaken met POST /companies/{companyId}/workers, latere wijzigingen met PATCH /workers/{workerId}.
Welke velden overgaan
De belangrijkste velden. De volledige mapping stellen we per klant vast.
| Veld in HiBob | Veld in Paychex Flex | Toelichting |
|---|---|---|
root.firstName | name.givenName | |
root.surname | name.familyName | |
Werknemer van de Amerikaanse entiteit | workerType EMPLOYEE | Alleen EMPLOYEE of INDEPENDENT_CONTRACTOR kan via de API |
Personeelsnummer in Bob | employeeId | |
work.startDate | currentStatus (IN_PROGRESS, PENDING_HIRE) met ingangsdatum | |
HiBob employee id | workerCorrelationId bij meerdere workers per verzoek |
Gerelateerd
Ashby → HiBob
Ashby HiBob koppeling: een aanname uit Ashby direct als medewerker in Bob
Bullhorn → HiBob
Bullhorn HiBob koppeling: een goedgekeurde plaatsing als nieuwe medewerker in Bob
Carerix → HiBob
Carerix HiBob koppeling: geslaagde match wordt nieuwe medewerker in Bob
Greenhouse → HiBob
Greenhouse HiBob koppeling: van aanname in Greenhouse naar nieuwe medewerker in Bob