diff --git a/personio-personnel-data-api-oa3.yaml b/personio-personnel-data-api-oa3.yaml index 05512a0..7d31100 100644 --- a/personio-personnel-data-api-oa3.yaml +++ b/personio-personnel-data-api-oa3.yaml @@ -197,6 +197,7 @@ paths: type: string example: 2022-12-24T08:15:30 description: List Company Employees + summary: List Employees responses: "200": description: "" @@ -204,259 +205,12 @@ paths: application/json: schema: $ref: "#/components/schemas/EmployeesResponse" - examples: - response: - value: - success: true - metadata: - total_elements: 2 - current_page: 0 - total_pages: 3 - offset: 0 - limit: 20 - 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 - preferred_name: - label: Name (preferred) - value: Alexander Bergmann - type: standard - universal_id: preferred_name - email: - label: Email - value: alexander.bergmann@demo.email - type: standard - universal_id: email - gender: - label: Gender - value: male - type: standard - universal_id: gender - status: - label: Status - value: active - type: standard - universal_id: status - position: - label: Position - value: CTO - type: standard - universal_id: position - supervisor: - label: Supervisor - value: - type: Employee - attributes: - id: - label: ID - value: 2 - type: integer - universal_id: id - type: standard - universal_id: supervisor - employment_type: - label: Employment type - value: external - type: standard - universal_id: employment_type - weekly_working_hours: - label: Weekly hours - value: '40' - type: standard - universal_id: weekly_working_hours - hire_date: - label: Hire date - value: 2014-11-09T00:00:00+01:00 - type: date - universal_id: hire_date - contract_end_date: - label: Contract ends - value: null - type: date - universal_id: contract_end_date - termination_date: - label: Termination date - value: null - type: date - universal_id: termination_date - termination_type: - label: Termination type - value: null - type: standard - universal_id: termination_type - termination_reason: - label: Termination reason - value: null - type: standard - universal_id: termination_reason - probation_period_end: - label: Probation period end - value: null - type: date - universal_id: probation_period_end - created_at: - label: created_at - value: '2017-05-23T09:49:03+02:00' - type: date - universal_id: created_at - last_modified_at: - label: Last modified - value: '2020-11-18T17:33:55+01:00' - type: date - universal_id: last_modified_at - subcompany: - label: Subcompany - value: - type: Subcompany - attributes: - id: 7033 - name: CS Demo GmbH - type: standard - universal_id: subcompany - office: - label: Office - value: - type: Office - attributes: - id: 131014 - name: Munich - type: standard - universal_id: office - department: - label: Department - value: - type: Department - attributes: - id: 281521 - name: Customer Support - type: standard - universal_id: department - cost_centers: - label: Cost center - value: - - type: CostCenter - attributes: - id: 82957 - name: Cost center 1 - percentage: 100 - type: standard - universal_id: cost_centers - holiday_calendar: - label: Public holidays - value: - type: HolidayCalendar - attributes: - id: 2 - name: Deutschland (Bayern) Feiertage - country: DE - state: Bayern - type: standard - universal_id: holiday_calendar - absence_entitlement: - label: Absence entitlement - value: - - type: TimeOffType - attributes: - id: 113437 - name: Paid vacation - category: paid_vacation - entitlement: 24 - type: standard - universal_id: absence_entitlement - work_schedule: - label: Work schedule - value: - type: WorkSchedule - attributes: - id: 97188 - name: Full-time, 40 hours without time tracking, (mon,tue,wed,thu,fri) - valid_from: - monday: '08:00' - tuesday: '08:00' - wednesday: '08:00' - thursday: '08:00' - friday: '08:00' - saturday: '00:00' - sunday: '00:00' - type: standard - universal_id: work_schedule - fix_salary: - label: Fix salary - value: 3000 - type: decimal - universal_id: fix_salary - currency: EUR - fix_salary_interval: - label: Salary interval - value: monthly - type: standard - universal_id: fix_salary_interval - hourly_salary: - label: Hourly salary - value: 0 - type: decimal - universal_id: hourly_salary - currency: EUR - vacation_day_balance: - label: Vacation day balance - value: 2 - type: decimal - universal_id: vacation_day_balance - last_working_day: - label: Last day of work - value: - type: date - universal_id: last_working_day - profile_picture: - label: Profile Picture - value: https://api.personio.de/v1/company/employees/1132888/profile-picture - type: standard - universal_id: profile_picture - team: - label: Team - value: - type: Team - attributes: - id: 59026 - name: T_X - type: standard - universal_id: team - dynamic_24407: - label: Titel - value: Dr - universal_id: null - type: standard - dynamic_21827: - label: IBAN - value: DE98 8989 9898 0000 8989 00 - universal_id: iban - type: standard - dynamic_33400: - label: Anniversary Date - value: 2021-01-01 - universal_id: null - type: date post: security: - BearerAuth: [] tags: - Employees - summary: Create an employee + summary: Create an Employee description: > Creates a new employee. If the employee's status is not provided, it will be set based on the `hire_date` value - if it is in the past, status will be `active`, otherwise `onboarding`. This endpoint responds with the `id` of the created employee in case of success. requestBody: @@ -609,7 +363,7 @@ paths: error: code: 422 message: "Supervisor with ID 1 not found" - "/company/employees/{employee_id}": + /company/employees/{employee_id}: parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -618,7 +372,7 @@ paths: - BearerAuth: [] tags: - Employees - summary: Update an employee + summary: Update Employee by ID description: > Updates an existing employee. Note: Only the fields that are listed in the body example are updatable. Attributes that are not part of the sample request body but are present @@ -756,7 +510,8 @@ paths: - BearerAuth: [] tags: - Employees - description: Show employee by ID + description: Get Employee by ID + summary: Get Employee by ID parameters: - name: employee_id in: path @@ -1032,7 +787,7 @@ paths: code: 404 message: 'Es ist ein Problem aufgetreten ' - "/company/employees/{employee_id}/absences/balance": + /company/employees/{employee_id}/absences/balance: parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -1042,6 +797,7 @@ paths: tags: - Employees description: Retrieve the absence balance for a specific employee + summary: Get Absence Balance for Employee parameters: - name: employee_id in: path @@ -1071,13 +827,14 @@ paths: code: 404 message: 'Es ist ein Problem aufgetreten ' - "/company/employees/custom-attributes": + /company/employees/custom-attributes: get: security: - BearerAuth: [] tags: - Employees description: "This endpoint is an alias for `/company/employees/attributes`." + summary: List Allowed Custom Attributes parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -1085,13 +842,14 @@ paths: "200": description: "Please refer to `/company/employees/attributes`" - "/company/employees/attributes": + /company/employees/attributes: get: security: - BearerAuth: [] tags: - Employees description: Lists all the allowed atrributes per API credentials including custom (dynamic) attributes. + summary: List Allowed Attributes parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -1118,7 +876,7 @@ paths: type: standard universal_id: iban - "/company/employees/{employee_id}/profile-picture/{width}": + /company/employees/{employee_id}/profile-picture/{width}: parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -1128,6 +886,7 @@ paths: tags: - Employees description: "Show employee's profile picture. If profile picture is missing, the 404 error will be thrown. The `Profile Picture` attribute has to be whitelisted." + summary: Get Employee Profile Picture parameters: - name: employee_id in: path @@ -1175,6 +934,7 @@ paths: tags: - Attendances description: Fetch attendance data for the company employees. The result can be `paginated` and `filtered` by period, the date and/or time they were updated, and/or specific employee/employees. The result contains a list of attendances. + summary: List Attendances parameters: - name: start_date in: query @@ -1303,6 +1063,7 @@ paths: tags: - Attendances description: This endpoint is responsible for adding attendance data for the company employees. It is possible to add attendances for one or many employees at the same time. The payload sent on the request should be a list of attendance periods, in the form of an array containing attendance period objects. + summary: Create an Attendance requestBody: content: application/json: @@ -1375,7 +1136,7 @@ paths: } ] - "/company/attendances/{id}": + /company/attendances/{id}: parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -1386,6 +1147,7 @@ paths: - Attendances description: This endpoint is responsible for deleting attendance data for the company employees. + summary: Delete Attendance by ID parameters: - name: id in: path @@ -1451,6 +1213,7 @@ paths: tags: - Attendances description: This endpoint is responsible for updating attendance data for the company employees. Attributes are not required and if not specified, the current value will be used. It is not possible to change the employee id. + summary: Update Attendance by ID parameters: - name: id in: path @@ -1520,6 +1283,7 @@ paths: tags: - Projects description: Provides a list of all company projects. + summary: List Projects responses: "200": description: List of projects returned @@ -1540,6 +1304,7 @@ paths: tags: - Projects description: Creates a project into the company account + summary: Create a Project requestBody: content: application/json: @@ -1593,6 +1358,7 @@ paths: tags: - Projects description: Deletes a project from the company account + summary: Delete Project by ID parameters: - name: id in: path @@ -1624,6 +1390,7 @@ paths: tags: - Projects description: Updates a project with the given data + summary: Update Project by ID parameters: - name: id in: path @@ -1700,6 +1467,7 @@ paths: tags: - Absences description: Provides a list of absence types for absences **time unit** set to either **days** or **hours**. For example 'Paid vacation', 'Parental leave' or 'Home office'. + summary: List Time-Off Types parameters: - name: limit in: query @@ -1771,6 +1539,7 @@ paths: tags: - Absences description: Fetches absence periods for absences with **time unit** set to **days**. The result can be `paginated` and `filtered` by period and/or specific employee/employees. The result contains a list of absence periods. + summary: List Time-Offs parameters: - name: start_date in: query @@ -1892,6 +1661,7 @@ paths: tags: - Absences description: Adds absence data for absence types with **time unit** set to **days**. + summary: Create a Time-Off requestBody: content: application/x-www-form-urlencoded: @@ -2006,7 +1776,7 @@ paths: message: 'The given data failed to pass validation.' error_data: '{...}' - "/company/time-offs/{id}": + /company/time-offs/{id}: parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -2016,6 +1786,7 @@ paths: tags: - Absences description: Deletes absence period data for absence types with **time unit** set to **days**. + summary: Delete Time-Off by ID parameters: - name: id in: path @@ -2069,6 +1840,7 @@ paths: tags: - Absences description: Gets an absence period for absences with **time unit** set to **days**. + summary: Get Time-Off by ID parameters: - name: id in: path @@ -2145,7 +1917,7 @@ paths: error: code: 404 message: 'The absence period was not found.' - "/company/absence-periods": + /company/absence-periods: parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -2155,6 +1927,7 @@ paths: tags: - Absences description: Fetches absence periods for absences with **time unit** set to **hours**. The result can be `paginated` and `filtered` by period and/or specific employee/employees. The result contains a list of hourly absence periods. + summary: List Absence Periods parameters: - name: start_date in: query @@ -2318,6 +2091,7 @@ paths: tags: - Absences description: Adds absence data for absence types with **time unit** set to **hours**. Note that creating periods for absence types with certificate requirement enabled is not supported! + summary: Create an Absence Period requestBody: content: application/x-www-form-urlencoded: @@ -2455,7 +2229,7 @@ paths: code: 0 message: 'Something went wrong' - "/company/absence-periods/{id}": + /company/absence-periods/{id}: parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -2465,6 +2239,7 @@ paths: tags: - Absences description: Deletes absence period data for absence types with **time unit** set to **hours**. + summary: Delete Absence Period by ID parameters: - name: id in: path @@ -2514,7 +2289,7 @@ paths: code: 400 message: 'The absence period id is invalid.' - "/company/document-categories": + /company/document-categories: parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -2524,6 +2299,7 @@ paths: tags: - Documents description: This endpoint is responsible for fetching all document categories of the company. The result contains a list of document categories. + summary: List Document Categories responses: "200": description: "" @@ -2544,7 +2320,7 @@ paths: type: "DocumentCategory" attributes: name: "Other documents" - "/company/documents": + /company/documents: parameters: - $ref: "#/components/parameters/XPersonioPartnerID" - $ref: "#/components/parameters/XPersonioAppID" @@ -2554,6 +2330,7 @@ paths: tags: - Documents description: This endpoint is responsible for uploading documents for the company employees. + summary: Upload Document requestBody: content: multipart/form-data: @@ -2671,6 +2448,7 @@ paths: required: false description: The status of the report to filter the results. description: This endpoint provides you with metadata about existing custom reports in your Personio account, such as report name, report type, report date / timeframe. + summary: List Custom Reports operationId: listReports responses: 200: @@ -2722,6 +2500,7 @@ paths: example: 10 required: false description: This endpoint provides you with the data of an existing Custom Report. + summary: Get Custom Report by ID operationId: listReportItems responses: 200: @@ -2780,6 +2559,7 @@ paths: description: The ID of the report to filter the result of the columns. If no ID is passed, all columns for the company are returned. required: false description: This endpoint provides human-readable labels for report table columns. It is particularly important if you get a report with custom attributes or absence data to match the column IDs to the translation. + summary: List Custom Report Column Labels operationId: listColumns responses: 200: