Accounts in applications
Personio to Zenya integration: department, team and position from Personio on the Zenya user
With an integration between Personio and Zenya, every new employee in Personio becomes an active Zenya user on their first working day, with department and team as organisation units, position and manager. After the termination date in Personio the integration sets the user to inactive in Zenya, except on a move to another company within the group.
What the integration does
Organisations that use Personio as HR system and Zenya for protocols and reports maintain two organisation structures. Departments and teams from Personio are rebuilt by hand in Zenya, and new colleagues only get their reading tasks once someone adds them to Zenya.
- Application management records which Personio departments and teams belong to which Zenya units.
- Personio reports a new person or a changed employment; KoppelHet fetches the data.
- KoppelHet prepares the Zenya user as inactive and activates it on the start date.
- KoppelHet applies a new department, team, position or manager straight away.
- After the termination date KoppelHet sets the user to inactive.
What to watch for with Personio and Zenya
- Personio sends a dedicated notification on the start date, at midnight UTC, and one on the termination date at 23:59 UTC. KoppelHet uses those moments to make the Zenya user active and inactive; in the Netherlands that is one or two hours after midnight.
- A move to another company within the group ends one employment in Personio and starts a new one, with the termination type SUB_COMPANY_SWITCH. KoppelHet does not set the Zenya user to inactive then, because the person stays and must keep their read confirmations.
- In a Personio employment, department and team sit together in one list of organisation units, each with a type. A Zenya user can belong to several units, so KoppelHet sets both in Zenya when they are in the lookup table, so both department and team protocols reach the employee.
- Personio only supplies the position as a free title, while a position in Zenya is an object with its own ID. KoppelHet looks up the Zenya position by name; a title that does not exist there goes on a list for application management instead of a new position.
- Personio passes on name changes and language through a different notification than department and manager. KoppelHet listens to both, so a new surname or preferred language also reaches Zenya and Zenya addresses the employee in the right language.
- Personio only counts a notification as received with a response within three seconds, and then retries for up to three days. KoppelHet confirms the notification straight away, checks the HMAC signature and then processes the change in Zenya, so a slow Zenya call does not cause duplicate notifications.
- Personio distinguishes internal and external employees. Externals, such as contractors, only get a Zenya user if you want that, and become inactive on their contract end date.
This integration is also part of joiner, mover, leaver.
How we build and run it
- The integration runs on the KoppelHet platform, hosted in a data centre in the EU.
- Every sync and every error is visible in the functional log; on an error your administrator is notified.
- A change that cannot go through is not half-applied but queued for another attempt.
- KoppelHet is ISO 27001 certified. Data travels encrypted and stays on the platform no longer than needed.
- After go-live we manage the integration and adjust it when your process changes.
- The integration fits next to your existing integration layer. Only the fields in the design are transferred; the platform keeps no register of its own.
Implementation and price
This is not an app you switch on. We build the integration for your organisation on our platform, with building blocks we reuse on every project. So it is custom work that does not start from scratch.
A consultant prepares the intake and analyses both systems. We then record the mapping and exceptions field by field, test in the test or acceptance environment and go live at a moment you choose. Costs are a one-off amount for the setup and a monthly amount for platform, monitoring and support.
Frequently asked questions
Does the integration create teams in Zenya?
No. A new team or department from Personio without a place in Zenya goes on a list for application management.
What happens during leave?
The Zenya user stays active. Only the termination date makes it inactive.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Personio through webhooks (person.created, person.updated, employment.created, employment.updated, employment.started and employment.terminated; X-Personio-Webhook-Signature with HMAC-SHA256 over timestamp and raw body, 2xx within 3 seconds, retries for up to 3 days) and the Personio API v2 (employments with status, type INTERNAL or EXTERNAL, position.title, supervisor.id, org_units with type, employment_start_date, contract_end_date and termination.type). Read scopes on persons and employments only.
- Zenya is written through the Zenya REST API v5 (token through POST /tokens with api_key and username). POST /users with login_code and name required, plus email_address, external_id, language, position_id, manager_id, organization_unit_ids and active; PATCH /users/{user_id} for changes. GET /users with external_ids, GET /positions and GET /organization_units for the IDs.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Personio | Field in Zenya | Notes |
|---|---|---|
Person id | external_id | |
Werk-e-mailadres | login_code en email_address | |
Preferred name of voornaam en achternaam | name | |
Taal | language | |
org_units (type department en team) | organization_unit_ids | Through the lookup table |
position.title | position_id | Looked up by name; position must exist in Zenya |
supervisor.id | manager_id | Looked up by external_id |
employment_start_date en termination | active |
Related
Ashby → Personio
Ashby to Personio integration: hires with hours and entity as new employees in Personio
Bullhorn → Personio
Bullhorn to Personio integration: placements as a person with employment in Personio
Carerix → Personio
Carerix to Personio integration: successful placement as a new employee in Personio
Greenhouse → Personio
Greenhouse to Personio integration: hired candidates as employees in Personio