List Employees

get

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

List Company Employees

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Find an overview of custom attribute types here

📘
'updated_since' filter application
Please note that the 'updated_since' filter is applied only to attributes that are whitelisted as part of the API Credentials

📘
Pagination notice
In order to maintain system integrity and acceptable performance at V1 GET employees endpoint the maximum page size will be reduced to 100 employees per page on an ongoing basis in 2025.
For new API adopters, it is recommended to use the new pagination values when implementing their API requests to the GET /v1/company/employees endpoint.

Query Params

limit

integer

≥ 1

Defaults to 10

Pagination attribute to limit the number of employees returned per page.

offset

integer

≥ 0

Defaults to 0

Pagination attribute to identify the first item in the collection to return.

string

Find an employee with the given email address. The response is still a list, containing only the filtered employee. NOTE: when using the updated_since filter, the email filter is ignored.

attributes[]

array of strings

A list of attributes that will be returned for the employees, ie. a projection of the employee fields and relationships. In case updated_since query parameter is used, this list will additionally be used to exclude the employees that had none of the provided attributes[] updated since updated_since, ie. a selection filter.

attributes[]

updated_since

string

Filter to select and return only the employees that have been updated after updated_since. When it is used together with the attributes[] query parameter, the filter will select only the employees that have had any of the provided attributes[] updated since updated_since. The format is ISO 8601 (2022-12-24T08:15:30) or YYYY-MM-DD. NOTE: when using the updated_since filter, the email, limit, and offset parameters are ignored.

Examples with updated_since and attributes[]:

In an example company that has 17 employees:

?updated_since=2022-12-24T08:15:30 will yield 10 employees that were recently updated:

 {
  "success": true,
  "metadata": {
    "total_elements": 10,
    "current_page": 0,
    "total_pages": 10
  },
  "offset": 0,
  "limit": 1,
  "data": [
    {
      "type": "Employee",
      "attributes": {
        "id": {
          "label": "ID",
          "value": 1,
          "type": "integer",
          "universal_id": "id"
        },
        "first_name": {
          "label": "First name",
          "value": "Alexander",
          "type": "standard",
          "universal_id": "first_name"
        },
        "last_name": {
          "label": "Last name",
          "value": "Bergmann",
          "type": "standard",
          "universal_id": "last_name"
        },
        "email": {
          "label": "Email",
          "value": "[email protected]",
          "type": "standard",
          "universal_id": "email"
        }
      }
    }, ...
  ],
  ...
  ...
}

?attributes[]=first_name will yield all 17 employees:

 {
  "success": true,
  "metadata": {
    "total_elements": 17,
    "current_page": 0,
    "total_pages": 17
  },
  "offset": 0,
  "limit": 1,
  "data": [
    {
      "type": "Employee",
      "attributes": {
        "id": {
          "label": "ID",
          "value": 1,
          "type": "integer",
          "universal_id": "id"
        },
        "first_name": {
          "label": "First name",
          "value": "Alexander",
          "type": "standard",
          "universal_id": "first_name"
        }
      }
    }
  ]
}

?attributes[]=first_name&updated_since=2022-12-24T08:15:30 will yield 3 employees, ones that had their first_name changed since 2022-12-24T08:15:30:

 {
  "success": true,
  "metadata": {
    "total_elements": 3,
    "current_page": 0,
    "total_pages": 3
  },
  "offset": 0,
  "limit": 1,
  "data": [
    {
      "type": "Employee",
      "attributes": {
        "id": {
          "label": "ID",
          "value": 1,
          "type": "integer",
          "universal_id": "id"
        },
        "first_name": {
          "label": "First name",
          "value": "Alexander",
          "type": "standard",
          "universal_id": "first_name"
        }
      }
    }
  ]
}

Headers

X-Personio-Partner-ID

string

The partner identifier

X-Personio-App-ID

string

The application identifier

Response

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

List Employees

'updated_since' filter application

Pagination notice

What’s Next

What’s Next

'updated_since' filter application

Pagination notice

200

What’s Next

What’s Next