personio-hr

n8n community node for Personio HR platform (v2 API)

Package Information

Downloads: 39 weekly / 937 monthly
Latest Version: 0.1.8
Author: Paul Karrmann

Available Nodes

Personio HR icon
Personio HR
Interact with the Personio HR platform API
Personio HR Trigger icon
Personio HR Trigger
Starts the workflow when Personio events occur

Documentation

n8n-nodes-personio-hr

Community node for n8n to interact with the Personio HR platform via their v2 API.

Installation

In n8n Desktop / Self-Hosted

Go to Settings > Community Nodes and install:

n8n-nodes-personio-hr

Manual Installation

cd ~/.n8n/nodes
npm install n8n-nodes-personio-hr

Then restart n8n.

Credentials

You need a Personio API client ID and client secret. Create them in Personio > Settings > Integrations > API credentials.

When configuring the credential in n8n, enter:

  • Client ID - Your API client ID
  • Client Secret - Your API client secret

The node handles token authentication automatically (OAuth2 Client Credentials flow with expirable tokens).

Supported Resources & Operations

Personio HR (Regular Node)

Resource Operations
Person Create, Get, Get Many, Update, Delete
Employment Get, Get Many, Update
Absence Period Create, Get, Get Many, Get Breakdowns, Update, Delete
Absence Type Get, Get Many
Attendance Period Create, Get, Get Many, Update, Delete
Project Create, Get, Get Many, Update, Delete, Get Members, Add Members, Remove Members
Document Get Many, Download (binary), Update, Delete
Compensation Create, Get Many, Get Types, Create Type
Organization Get Legal Entities, Get Legal Entity

Personio Trigger (Webhook Node)

Automatically registers webhooks with Personio for real-time events:

  • Person: created, updated, deleted
  • Employment: created, updated, deleted
  • Absence Period: created, updated, deleted
  • Attendance Period: created, updated, deleted
  • Compensation: created, updated, deleted
  • Project: created, updated, deleted
  • Custom reports: created

Webhooks are auto-registered on workflow activation and cleaned up on deactivation.

Features

  • Cursor-based pagination on all list endpoints with "Return All" toggle
  • Custom Attributes support on Person Create/Update (dynamic key-value pairs for instance-specific fields like date of birth, phone, address, etc.)
  • Nested body formats handled correctly for the Personio v2 API (employments, positions, supervisors, org units, cost centers)
  • Binary file download for documents
  • Proper Accept headers for DELETE/PATCH operations (application/problem+json)

Custom Attributes

Personio stores many personal details (date of birth, phone, nationality, etc.) as custom attributes with instance-specific IDs. The Person Create and Update operations include a "Custom Attributes" section where you can add multiple attribute rows.

Single value:

  • Attribute ID: laptop_serial_number
  • Value: ABC-123

Array value (tags/multi-select):

  • Attribute ID: peripheries
  • Value: ["mouse","keyboard","monitor"]

Known Limitations

  • Compensation Create returns 403 Forbidden - this is a Personio-side issue (also fails in their own API playground)
  • Organization - Cost Centers and Workplaces endpoints return 404 (not live in Personio API despite being documented). Only Legal Entities are available.
  • Org Units - No list endpoint exists, so you need to know the org unit ID beforehand
  • Recruiting API - Not included (known to be unstable)

API Scopes Required

Ensure your Personio API credentials have the following scopes enabled:

  • persons:read, persons:write
  • employments:read, employments:write
  • absences:read, absences:write
  • attendances:read, attendances:write
  • projects:read, projects:write
  • documents:read, documents:write
  • compensations:read, compensations:write
  • webhooks:read, webhooks:write (for the Trigger node)

License

MIT

Discussion