Office

Model definition

Office:
  type: object
  allOf:
    - $ref: '#/definitions/Attribute'
  properties:
    value:
      type: object
      properties:
        type:
          type: string
        attributes:
          type: array
          items:
            type: object
            properties:
              name:
                type: string

Example Response

The attributes in the example are not of type array.

office:
  label: Office
  value:
    type: Office
    attributes:
      name: Munich

Department

Model definition

Department:
  type: object
  allOf:
    - $ref: '#/definitions/Attribute'
  properties:
    value:
      type: object
      properties:
        type:
          type: string
        attributes:
          type: array
          items:
            type: object
            properties:
              name:
                type: string

Example Response

The attributes in the example are not of type array.

department:
  label: Department
  value:
    type: Department
    attributes:
      name: Marketing

Currently, this endpoint provides a list of absence types for absences tracked in both days and hours.

Finding out whether an employee is absent/sick etc via the api involves having to do time/date comparison from what I can tell (the documentation is missing a lot of information for a critical feature of your business).

Is the list of absences returned for an employee via employees[] filter query param does not specify if it's the most recent abscenses first or the latest, I'm sure this could be tested within a few minutes but the kind of information that would be useful to state.

I still believe the endpoint or status (another issue references missing schema for employee status #150)

the requests for
/company/attendances:
/company/time-offs:
define the employees parameter as query (comma list)

the server denied such format with the message "the employees must be an array"

after some try and error, the personio server accepted a body json object with an integer array (or an empty array as well)
the response data matched also the expected result, so I assume the documentation is not up to date.

Here the changes:

- name: employees
  in: query
  required: false
  description: A list of Personio employee ID's to filter the results. The result filters including only absences of provided employees
  explode: true
  schema:
    type: array
    items:
      type: integer

to

- name: employees
  in: body
  required: false
  description: A list of Personio employee ID's to filter the results. The result filters including only absences of provided employees
  explode: true
  schema:
    type: object
    properties:
      employees:
        type: array
        items:
          type: integer

Do I need to configure some permissions for my client_id and client_secret somewhere?

After obtaining a bearer token I did:

curl -v 'https://api.personio.de/v1/company/employees/XZY' -H "authorization: Bearer $TOKEN" --header 'Accept: application/json'
{"success":true,"data":{"type":"Employee","attributes":{"id":{"label":"ID","value":XYZ}}}}

The type Department's value.attributes property only has the property "name", but the API always returns an "id" as well. This "id" is also part of the example values in the spec itself.

Additionally, both properties should be marked as required if they are, or the types generated with e.g. openapi-codegen will be wrong (fields marked as optional, leading to lots of workarounds necessary in typed languages)

curl --request GET \
     --url 'https://api.personio.de/v1/company/time-offs?start_date=2022-03-07&end_date=2022-03-09&limit=200&offset=0'

returns results like:

{
"type":"TimeOffPeriod",
"attributes":{
"id":89788232,
"start_date":"2022-03-01T00:00:00+01:00",
"end_date":"2022-03-07T00:00:00+01:00",
"days_count":5,
...
}

and

{
"type":"TimeOffPeriod",
"attributes":{
"id":20513927,
"start_date":"2020-11-13T00:00:00+01:00",
"end_date":"2022-09-07T00:00:00+02:00",
"days_count":664,
...
}

The documentation states

end_date date
Last day of the period to be queried. It is inclusive, so the result ends on end_date including absences from the end_date

So the first result can be attributed to a confusing wording (does "absences from the end_date" mean "absences starting up to end_date? One would expect end_date to delimit the last date to pull absences from)

However, the second result is more strange: Both the start_date and end_date are way beyond the range in the query.

Does the query return any absences which intersect the time interval defined by start_date and end_date? And if so, is this interval closed, half-open or open?

The Employee schema contains a status property which hast a valueproperty which can have the following values:
'active', 'inactive', 'onboarding', 'leave'
But this is missing in the spec.

Hi Team, hopefully this is right place to ask, if not, I'd appreciate if you can direct me.

I'm the founder of cloudquery.io, a high performance open source ELT framework.

Our users are interested in a Personio plugin, but as we cannot maintain all the plugins ourselves, I was curious if this would be an interesting collaboration, where we would help implement an initial source plugin, and you will help maintain it.

This will give your users the ability to sync Personio data to any of their datalakes/data-warehouses/databases easily using any of the growing list of CQ destination plugins.

Best,
Yevgeny