The Personio Developer Hub

Welcome to the Personio developer hub. You'll find comprehensive guides and documentation to help you start working with Personio as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Introduction

 

This page builds up on our API docs in swagger format hosted on github.

/auth

 

Credentials can be downloaded in the Personio app at Configure account > Company as text file. The credentials allow you to perform a request against the /auth endpoint to retrieve an initial authentication token.

With each new download of credentials, new keys are generated, whereby the existing keys become invalid.

In every request, the Authorization header has to be set:
Authorization: Bearer YOUR_TOKEN_HERE

After each request a new token is generated and sent back to the user in the Authorization header. You can use this token to make the next request. With every new call the previous token is invalidated.

Retrieved tokens have a lifetime of one day and can be exchanged for new ones in the course of two weeks.

post

Request Authentication Token

 
posthttps://api.personio.de/v1/auth

Query Params

client_id
string
required

Client id of the downloaded credentials file

client_secret
string
required

Client secret of the downloaded credentials file

curl --request POST \
  --url 'https://api.personio.de/v1/auth?client_id=client_id&client_secret=client_secret'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.personio.de/v1/auth',
  qs: 
   { client_id: 'client_id',
     client_secret: 'client_secret' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.personio.de/v1/auth?client_id=client_id&client_secret=client_secret")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.personio.de/v1/auth?client_id=client_id&client_secret=client_secret");

xhr.send(data);
import requests

url = "https://api.personio.de/v1/auth"

querystring = {"client_id":"client_id","client_secret":"client_secret"}

response = requests.request("POST", url, params=querystring)

print(response.text)
A binary file was returned
{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vYXBpLmRldi5wZXJzb25pby5kZTozMDAwMS92MS9hdXRoIiwiaWF0IjoxNDg5MDkxMzA2LCJleHAiOjE0ODkxNzc3MDYsIm5iZiI6MTQ4OTA5MTMwNiwianRpIjoiZmU1ZjkxOGY2MDZjOWI4OGMwMzM0ZmJkZjkyYzkwMzgiLCJzdWIiOiJPR014TVdRd1kySmxZbVF6Tm1RNVpqQmxOell6WmpsaSJ9.QZZCdlDjmL-LYdoDx2XLUfhwTdcjDgm9h4t-6JoACiM"
  }
}

/company/employees

 

get

List Employees

 
gethttps://api.personio.de/v1/company/employees

Query Params

query
string

[In development] Query string to perform search on. Returns all employees if not present. Can also be used with custom attributes, e.g. dynamic_9382=abcd

attributes
array of s

[In development] Attributes to be returend for employees found. Returns all available attributes if not present. Pass attributes multiple times of needed.

curl --request GET \
  --url https://api.personio.de/v1/company/employees
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.personio.de/v1/company/employees' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.personio.de/v1/company/employees")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.personio.de/v1/company/employees");

xhr.send(data);
import requests

url = "https://api.personio.de/v1/company/employees"

response = requests.request("GET", url)

print(response.text)
A binary file was returned
{
  "success": true,
  "data": [
    {
      "type": "Employee",
      "attributes": {
        "id": {
          "label": "id",
          "value": 83752
        },
        "first_name": {
          "label": "First name",
          "value": "Andreas"
        },
        "last_name": {
          "label": "Last name",
          "value": "Anderson"
        },
        "email": {
          "label": "Email",
          "value": "andreas.anderson@demo.com"
        },
        "gender": {
          "label": "Gender",
          "value": "male"
        },
        "status": {
          "label": "Status",
          "value": "active"
        },
        "position": {
          "label": "Position",
          "value": "Online Marketing Specialist"
        },
        "employment_type": {
          "label": "Employment type",
          "value": "internal"
        },
        "weekly_working_hours": {
          "label": "Weekly hours",
          "value": "40"
        },
        "hire_date": {
          "label": "Hire date",
          "value": "2012-02-01T00:00:00+0100"
        },
        "contract_end_date": {
          "label": "Contract ends",
          "value": null
        },
        "termination_date": {
          "label": "Termination date",
          "value": null
        },
        "termination_type": {
          "label": "Termination type",
          "value": ""
        },
        "termination_reason": {
          "label": "Termination reason",
          "value": ""
        },
        "probation_period_end": {
          "label": "Probation period end",
          "value": "2012-07-31T00:00:00+0200"
        },
        "created_at": {
          "label": "created_at",
          "value": "2016-10-20T16:15:55+0200"
        },
        "office": {
          "label": "Office",
          "value": {
            "type": "Office",
            "attributes": {
              "name": "Munich"
            }
          }
        },
        "department": {
          "label": "Department",
          "value": {
            "type": "Department",
            "attributes": {
              "name": "Marketing"
            }
          }
        },
        "cost_centers": {
          "label": "Cost center",
          "value": [
            {
              "type": "CostCenter",
              "attributes": {
                "name": "Cost Center One",
                "id": 320,
                "percentage": 50
              }
            },
            {
              "type": "CostCenter",
              "attributes": {
                "name": "Cost Center Two",
                "id": 321,
                "percentage": 50
              }
            }
          ]
        },
        "fix_salary": {
          "label": "Fix salary",
          "value": 4000
        },
        "hourly_salary": {
          "label": "Hourly salary",
          "value": 0
        },
        "vacation_day_balance": {
          "label": "Vacation day balance",
          "value": 28.5
        },
        "dynamic_24407": {
          "label": "Titel",
          "value": "Dr"
        },
        "dynamic_21827": {
          "label": "IBAN",
          "value": "DE98 8989 9898 0000 8989 00"
        }
      }
    }
  ]
}

/company/employees/{employee_id}

 

get

Employee

 
gethttps://api.personio.de/v1/company/employees/employee_id

Path Params

employee_id
integer
required

Numeric id of the employee

curl --request GET \
  --url https://api.personio.de/v1/company/employees/employee_id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.personio.de/v1/company/employees/employee_id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.personio.de/v1/company/employees/employee_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.personio.de/v1/company/employees/employee_id");

xhr.send(data);
import requests

url = "https://api.personio.de/v1/company/employees/employee_id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned
{
  "success": true,
  "data": {
    "type": "Employee",
    "attributes": {
      "id": {
        "label": "id",
        "value": 83752
      },
      "first_name": {
        "label": "First name",
        "value": "Andreas"
      },
      "last_name": {
        "label": "Last name",
        "value": "Anderson"
      },
      "email": {
        "label": "Email",
        "value": "andreas.anderson@demo.com"
      },
      "gender": {
        "label": "Gender",
        "value": "male"
      },
      "status": {
        "label": "Status",
        "value": "active"
      },
      "position": {
        "label": "Position",
        "value": "Online Marketing Specialist"
      },
      "employment_type": {
        "label": "Employment type",
        "value": "internal"
      },
      "weekly_working_hours": {
        "label": "Weekly hours",
        "value": "40"
      },
      "hire_date": {
        "label": "Hire date",
        "value": "2012-02-01T00:00:00+0100"
      },
      "contract_end_date": {
        "label": "Contract ends",
        "value": null
      },
      "termination_date": {
        "label": "Termination date",
        "value": null
      },
      "termination_type": {
        "label": "Termination type",
        "value": ""
      },
      "termination_reason": {
        "label": "Termination reason",
        "value": ""
      },
      "probation_period_end": {
        "label": "Probation period end",
        "value": "2012-07-31T00:00:00+0200"
      },
      "created_at": {
        "label": "created_at",
        "value": "2016-10-20T16:15:55+0200"
      },
      "office": {
        "label": "Office",
        "value": {
          "type": "Office",
          "attributes": {
            "name": "Munich"
          }
        }
      },
      "department": {
        "label": "Department",
        "value": {
          "type": "Department",
          "attributes": {
            "name": "Marketing"
          }
        }
      },
      "cost_centers": {
        "label": "Cost center",
        "value": [
          {
            "type": "CostCenter",
            "attributes": {
              "name": "Cost Center One",
              "id": 320,
              "percentage": 50
            }
          },
          {
            "type": "CostCenter",
            "attributes": {
              "name": "Cost Center Two",
              "id": 321,
              "percentage": 50
            }
          }
        ]
      },
      "fix_salary": {
        "label": "Fix salary",
        "value": 4000
      },
      "hourly_salary": {
        "label": "Hourly salary",
        "value": 0
      },
      "vacation_day_balance": {
        "label": "Vacation day balance",
        "value": 28.5
      },
      "dynamic_24407": {
        "label": "Titel",
        "value": "Dr"
      },
      "dynamic_21827": {
        "label": "IBAN",
        "value": "DE98 8989 9898 0000 8989 00"
      }
    }
  }
}

/company/attendance-periods

 

Coming soon

This endpoint is in development still

get

List Attendance Periods

 
gethttps://api.personio.de/v1/company/attendance-periods
curl --request GET \
  --url https://api.personio.de/v1/company/attendance-periods
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.personio.de/v1/company/attendance-periods' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.personio.de/v1/company/attendance-periods")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.personio.de/v1/company/attendance-periods");

xhr.send(data);
import requests

url = "https://api.personio.de/v1/company/attendance-periods"

response = requests.request("GET", url)

print(response.text)
A binary file was returned
{
  "success": true,
  "data": [
    {
      "type": "AttendancePeriod",
      "attributes": {
        "id": 325659,
        "start_time": "2017-01-17T10:00:00+0100",
        "end_time": "2017-01-17T18:00:00+0100",
        "break": 35,
        "comment": "I was productive as hell",
        "status": "confirmed",
        "employee": {
          "type": "Employee",
          "attributes": {
            "id": 325659,
            "first_name": {
              "label": "First name",
              "value": "Michael"
            },
            "last_name": {
              "label": "Last name",
              "value": "Miller"
            },
            "email": {
              "label": "Email",
              "value": "michael.miller@demo.com"
            }
          }
        },
        "updated_at": "2017-01-17T10:32:18+0100",
        "created_at": "2017-01-17T10:32:18+0100"
      }
    }
  ]
}

/company/employees/{employee_id}/attendance-periods

 

Coming soon

This endpoint is in development still

post

Create new attendance period

 
posthttps://api.personio.de/v1/company/employees/employee_id/attendance-periods

Path Params

employee_id
double
required

Numeric id of the User to perform action with.

Body Params

start_time
string
required
end_time
string
required
break
int32
required
comment
string
required
curl --request POST \
  --url https://api.personio.de/v1/company/employees/employee_id/attendance-periods
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.personio.de/v1/company/employees/employee_id/attendance-periods' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.personio.de/v1/company/employees/employee_id/attendance-periods")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.personio.de/v1/company/employees/employee_id/attendance-periods");

xhr.send(data);
import requests

url = "https://api.personio.de/v1/company/employees/employee_id/attendance-periods"

response = requests.request("POST", url)

print(response.text)
A binary file was returned
{
  "success": true,
  "data": {
    "type": "AttendancePeriod",
    "attributes": {
      "id": 325659,
      "start_time": "2017-01-17T10:00:00+0100",
      "end_time": "2017-01-17T18:00:00+0100",
      "break": 35,
      "comment": "I was productive as hell",
      "status": "confirmed",
      "employee": {
        "type": "Employee",
        "attributes": {
          "id": 325659,
          "first_name": {
            "label": "First name",
            "value": "Michael"
          },
          "last_name": {
            "label": "Last name",
            "value": "Miller"
          },
          "email": {
            "label": "Email",
            "value": "michael.miller@demo.com"
          }
        }
      },
      "updated_at": "2017-01-17T10:32:18+0100",
      "created_at": "2017-01-17T10:32:18+0100"
    }
  }
}

/company/time-offs

 

get

List All Absence Periods

 
gethttps://api.personio.de/v1/company/time-offs
curl --request GET \
  --url https://api.personio.de/v1/company/time-offs
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.personio.de/v1/company/time-offs' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.personio.de/v1/company/time-offs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.personio.de/v1/company/time-offs");

xhr.send(data);
import requests

url = "https://api.personio.de/v1/company/time-offs"

response = requests.request("GET", url)

print(response.text)
A binary file was returned
{
  "success": true,
  "data": [
    {
      "type": "TimeOffPeriod",
      "attributes": {
        "status": "approved",
        "start_date": "2017-12-27T00:00:00+0100",
        "end_date": "2017-12-29T00:00:00+0100",
        "days_count": 3,
        "half_day_start": 0,
        "half_day_end": 0,
        "time_off_type": {
          "type": "TimeOffType",
          "attributes": {
            "name": "Vacation"
          }
        },
        "employee": {
          "type": "Employee",
          "attributes": {
            "first_name": {
              "label": "First name",
              "value": "Michael"
            },
            "last_name": {
              "label": "Last name",
              "value": "Miller"
            },
            "email": {
              "label": "Email",
              "value": "michael.miller@demo.com"
            }
          }
        },
        "certificate": {
          "status": "not-required"
        },
        "created_at": "2017-01-17T10:32:18+0100"
      }
    }
  ]
}

/company/time-off/{time_off_id}

 

get

Absence Period

 
gethttps://api.personio.de/v1/company/time-off/time_off_id

Path Params

time_off_id
integer
required

Numeric id of the absence period

curl --request GET \
  --url https://api.personio.de/v1/company/time-off/time_off_id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.personio.de/v1/company/time-off/time_off_id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.personio.de/v1/company/time-off/time_off_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.personio.de/v1/company/time-off/time_off_id");

xhr.send(data);
import requests

url = "https://api.personio.de/v1/company/time-off/time_off_id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned
{
  "success": true,
  "data": {
    "type": "TimeOffPeriod",
    "attributes": {
      "status": "approved",
      "start_date": "2017-12-27T00:00:00+0100",
      "end_date": "2017-12-29T00:00:00+0100",
      "days_count": 3,
      "half_day_start": 0,
      "half_day_end": 0,
      "time_off_type": {
        "type": "TimeOffType",
        "attributes": {
          "name": "Vacation"
        }
      },
      "employee": {
        "type": "Employee",
        "attributes": {
          "first_name": {
            "label": "First name",
            "value": "Michael"
          },
          "last_name": {
            "label": "Last name",
            "value": "Miller"
          },
          "email": {
            "label": "Email",
            "value": "michael.miller@demo.com"
          }
        }
      },
      "certificate": {
        "status": "not-required"
      },
      "created_at": "2017-01-17T10:32:18+0100"
    }
  }
}