In this tutorial we will describe how to fetch the list of employees from Personio, and how to convert the result into a CSV format, using only a set of command line tools.

Step 1: Get the credentials

To start using the API, you need an Client ID and a Client Secret. Both can be found in the Settings page of your Personio account, as described here: https://developer.personio.de/v1.0/reference#auth

Step 2: Get a token

Every request to the API requires a token. Caution: a token is only valid for ONE request.

To get a token, use your Client ID and your Client Secret obtained in Step 1 and creates a POST request:

curl -X POST 'https://api.personio.de/v1/auth?client_id=[client_id]&client_secret=[client_secret]'

The result will be a JSON object such as:

{
  "success":true,
    "data":{
      "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5wZXJzb25pby5kZS92MS9hdXRoIiwiaWF0IjoxNTU5MDI5NjkyLCJleHAiOjE1NTkxMTYwOTIsIm5iZiI6MTU1OTAyOTY5MiwianRpIjoiNDlqczFjb2dyZzYwT21FaiIsInN1YiI6Ik5HUXpNRFV4WkdFd05UYzNNakUxWkRneVpqSmxaalV6IiwicHJ2IjoiN2ExOTk0OTk5ZDE4MWRlZWE2OGU0MzA0YjMzNDZlNzhmODM4ZWNiNyJ9.ZScc7z-wSO8v8L5a0ltjYT1b11-yg3Apvt_zz7admr8"
    }
}

Step 3: Getting the list of employees

First, make sure you have added the list of fields you wish to expose through your API. By default Personio doesn't expose anything on the API. Go to your Settings page, then API, then Access to add fields. In this example, we have decided to expose first_name and last_name. The employee ID is also automatically exposed.

Once you have properly configured the access, you can request the API adding the token in an Authorization header.

curl -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5wZXJzb25pby5kZS92MS9hdXRoIiwiaWF0IjoxNTU5MDI5NjkyLCJleHAiOjE1NTkxMTYwOTIsIm5iZiI6MTU1OTAyOTY5MiwianRpIjoiNDlqczFjb2dyZzYwT21FaiIsInN1YiI6Ik5HUXpNRFV4WkdFd05UYzNNakUxWkRneVpqSmxaalV6IiwicHJ2IjoiN2ExOTk0OTk5ZDE4MWRlZWE2OGU0MzA0YjMzNDZlNzhmODM4ZWNiNyJ9.ZScc7z-wSO8v8L5a0ltjYT1b11-yg3Apvt_zz7admr8' 'https://api.personio.de/v1/company/employees'

This will return a JSON object with the list of employees.

Step 4: Convert to CSV

To convert JSON to CSV using a script, you can use jq. To install jq on MacOS, use:

brew install jq

You can directly pipe the JSON into jq:

curl -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5wZXJzb25pby5kZS92MS9hdXRoIiwiaWF0IjoxNTU5MDI5NjkyLCJleHAiOjE1NTkxMTYwOTIsIm5iZiI6MTU1OTAyOTY5MiwianRpIjoiNDlqczFjb2dyZzYwT21FaiIsInN1YiI6Ik5HUXpNRFV4WkdFd05UYzNNakUxWkRneVpqSmxaalV6IiwicHJ2IjoiN2ExOTk0OTk5ZDE4MWRlZWE2OGU0MzA0YjMzNDZlNzhmODM4ZWNiNyJ9.ZScc7z-wSO8v8L5a0ltjYT1b11-yg3Apvt_zz7admr8' 'https://api.personio.de/v1/company/employees' | jq -r ".data[] | [.attributes.id.value,.attributes.first_name.value.attributes.last_name.value] | @csv"

Final step: A simple Bash script to wrap everything

#!/bin/bash

client_id='your_client_id'
client_secret='your_client_secret'
endpoint='https://api.personio.de'

attributes=(id first_name last_name)


printf -v x ".attributes.%s.value," "${attributes[@]}"
x=${x%,}

token=$(curl -X POST "$endpoint/v1/auth?client_id=$client_id&client_secret=$client_secret" -H 'cache-control: no-cache' | jq -r .data.token)
curl "$endpoint/v1/company/employees" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $token" | jq -r ".data[] | [$x] | @csv"