{"openapi":"3.1.0","info":{"title":"PapaHR API","version":"1.0.0","description":"The open API of PapaHR. A key is created by the company owner or HR in PapaHR → Connections and API. Docs: https://papahr.com/developers"},"servers":[{"url":"https://papahr.com/api/v1"}],"security":[{"bearer":[]}],"paths":{"/":{"get":{"tags":["Company"],"summary":"The key and its company","description":"Check the key: the company, the time zone and what the key may do.","operationId":"get-root","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"company":{"name":"Acme","timezone":"Europe/Kyiv"},"key":{"name":"Accounting — timesheet","scopes":{"employees":"read","timesheet":"read"},"salary":false,"personal":false,"expires_at":"2027-11-05T10:00:00Z"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[]}},"/employees":{"get":{"tags":["Employees"],"summary":"List employees","description":"The people of the company in the order they were added. Use updated_since to take only what changed since your last sync — this is how payroll or accounting keeps up without downloading everything again.\n\nWith a key that may see the salary each person has \"salary\": {\"amount\", \"currency\", \"since\"}; with personal data — \"personal\": {\"phone\", \"birthday\"}.","operationId":"get-employees","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":77,"name":"Oleh Pavlenko","first_name":"Oleh","last_name":"Pavlenko","email":"oleh@example.com","position":"Sales manager","department":{"id":4,"name":"Sales"},"manager":"Iryna Koval","status":"probation","hired_at":"2026-11-04","probation_ends_at":"2027-02-04","left_on":null,"hours_per_day":8,"updated_at":"2026-11-04T08:41:12Z"}],"next_cursor":null}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"employees:read","parameters":[{"name":"status","in":"query","required":false,"description":"active | left | all. Default active (includes people on probation)","schema":{"type":"string"}},{"name":"department_id","in":"query","required":false,"description":"integer. Only one department","schema":{"type":"integer"}},{"name":"updated_since","in":"query","required":false,"description":"ISO 8601 date-time. Only people changed after this moment, leavers too","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"integer. From next_cursor of the previous page. 100 per page","schema":{"type":"integer"}}]},"post":{"tags":["Employees"],"summary":"Create an employee","description":"Adds a person, as HR does in PapaHR. A new department from the text is created by itself. Sends the employee.hired webhook.\n\nAnswers 409 employee_limit when the plan's employee limit is reached.","operationId":"post-employees","responses":{"201":{"description":"OK","content":{"application/json":{"example":{"data":{"id":77,"name":"Oleh Pavlenko","first_name":"Oleh","last_name":"Pavlenko","email":"oleh@example.com","position":"Sales manager","department":{"id":4,"name":"Sales"},"manager":"Iryna Koval","status":"probation","hired_at":"2026-11-04","probation_ends_at":"2027-02-04","left_on":null,"hours_per_day":8,"updated_at":"2026-11-04T08:41:12Z"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"employees:write","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"string, required. Full name"},"email":{"type":"string","description":"string"},"position":{"type":"string","description":"string"},"department":{"type":"string","description":"string. The department name, as in PapaHR"},"manager":{"type":"string","description":"string. The manager's full name"},"hired_at":{"type":"string","description":"date"},"probation_until":{"type":"string","description":"date"},"status":{"type":"string","description":"active | probation | left. Default active"},"phone":{"type":"string","description":"string, date. Only with a key that may see personal data"},"birthday":{"type":"string","description":"string, date. Only with a key that may see personal data"}}}}}}}},"/employees/{id}":{"get":{"tags":["Employees"],"summary":"Get an employee","description":"One person by the id.","operationId":"get-employees-id","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":77,"name":"Oleh Pavlenko","first_name":"Oleh","last_name":"Pavlenko","email":"oleh@example.com","position":"Sales manager","department":{"id":4,"name":"Sales"},"manager":"Iryna Koval","status":"probation","hired_at":"2026-11-04","probation_ends_at":"2027-02-04","left_on":null,"hours_per_day":8,"updated_at":"2026-11-04T08:41:12Z"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"employees:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]},"patch":{"tags":["Employees"],"summary":"Update an employee","description":"Changes only the fields you send. status = left with left_on marks a leaver and sends employee.left.","operationId":"patch-employees-id","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":77,"name":"Oleh Pavlenko","first_name":"Oleh","last_name":"Pavlenko","email":"oleh@example.com","position":"Sales manager","department":{"id":4,"name":"Sales"},"manager":"Iryna Koval","status":"probation","hired_at":"2026-11-04","probation_ends_at":"2027-02-04","left_on":null,"hours_per_day":8,"updated_at":"2026-11-04T08:41:12Z"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"employees:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"left_on":{"type":"string","description":"date. The last day"}}}}}}}},"/departments":{"get":{"tags":["Employees"],"summary":"Departments","description":"The departments with the parent, the head and the number of people.","operationId":"get-departments","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":4,"name":"Sales","parent_id":null,"head_employee_id":12,"employees":9}]}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"employees:read","parameters":[]}},"/time-off/types":{"get":{"tags":["Time off"],"summary":"Types of time off","description":"Vacation, sick leave and the company's own types, with the type_id for requests.","operationId":"get-time-off-types","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":2,"name":"Vacation","code":"V","kind":"vacation","paid":true,"counts_as_work":false,"days_per_year":24,"approval":"manager"}]}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"time_off:read","parameters":[]}},"/time-off":{"get":{"tags":["Time off"],"summary":"List time off","description":"Requests and absences that overlap the dates.","operationId":"get-time-off","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":310,"employee":{"id":77,"name":"Oleh Pavlenko"},"type":{"id":2,"name":"Vacation","kind":"vacation"},"starts_on":"2026-12-21","ends_on":"2026-12-25","days":5,"status":"pending","comment":"Family trip","decided_at":null}],"next_cursor":null}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"time_off:read","parameters":[{"name":"from","in":"query","required":false,"description":"date. Default 30 days ago","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"date. Default in 90 days","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"pending | approved | rejected | cancelled | all. Default all","schema":{"type":"string"}},{"name":"employee_id","in":"query","required":false,"description":"integer","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"integer. From next_cursor of the previous page. 100 per page","schema":{"type":"integer"}}]},"post":{"tags":["Time off"],"summary":"Request time off","description":"Creates a request as if the employee sent it: it goes to approval in PapaHR, or is approved at once if the type needs no approval.\n\nAnswers 409 overlap when the person already has a request for these dates, 422 no_working_days when there are none.","operationId":"post-time-off","responses":{"201":{"description":"OK","content":{"application/json":{"example":{"data":{"id":310,"employee":{"id":77,"name":"Oleh Pavlenko"},"type":{"id":2,"name":"Vacation","kind":"vacation"},"starts_on":"2026-12-21","ends_on":"2026-12-25","days":5,"status":"pending","comment":"Family trip","decided_at":null}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"time_off:write","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"employee_id":{"type":"integer","description":"integer, required"},"type_id":{"type":"integer","description":"integer, required. From Types of time off"},"starts_on":{"type":"string","description":"date, required"},"ends_on":{"type":"string","description":"date, required"},"comment":{"type":"string","description":"string"}}}}}}}},"/timesheet/{month}":{"get":{"tags":["Timesheet"],"summary":"Timesheet of a month","description":"The timesheet as HR sees it in PapaHR: hours or the absence code for every day, and the totals. month is YYYY-MM.\n\nclosed_at is set when HR closed the month for the accounting: then the numbers do not change.","operationId":"get-timesheet-month","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"month":"2026-11","closed_at":null,"data":[{"employee_id":77,"name":"Oleh Pavlenko","days":{"2026-11-03":{"value":"8","kind":"work"},"2026-11-04":{"value":"V","kind":"vacation"}},"totals":{"worked_days":20,"hours":160,"vacation_days":1,"sick_days":0,"other_days":0}}]}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"timesheet:read","parameters":[{"name":"month","in":"path","required":true,"schema":{"type":"string"}}]}},"/clock":{"get":{"tags":["Timesheet"],"summary":"Clock-in marks","description":"The marks of “Start the day”: start, break, back, end. At most 62 days at once.","operationId":"get-clock","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":5012,"employee_id":77,"date":"2026-11-05","kind":"in","at":"2026-11-05T07:02:00Z","source":"web"}],"next_cursor":null}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"timesheet:read","parameters":[{"name":"from","in":"query","required":false,"description":"date. Default 6 days ago","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"date. Default today","schema":{"type":"string"}},{"name":"employee_id","in":"query","required":false,"description":"integer","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"integer. From next_cursor of the previous page. 100 per page","schema":{"type":"integer"}}]}},"/vacancies":{"get":{"tags":["Hiring"],"summary":"Vacancies","description":"Vacancies with the stages and the public page to apply.","operationId":"get-vacancies","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":18,"title":"Sales manager","department":"Sales","location":"Kyiv","status":"open","openings":2,"deadline":"2026-12-15","stages":[{"key":"new","name":"New"},{"key":"interview","name":"Interview"}],"candidates":41,"apply_url":"https://papahr.com/jobs/…"}]}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"hiring:read","parameters":[{"name":"status","in":"query","required":false,"description":"draft | open | closed | all. Default open","schema":{"type":"string"}}]}},"/vacancies/{id}/candidates":{"get":{"tags":["Hiring"],"summary":"Candidates of a vacancy","description":"The candidates with the stage and the source.","operationId":"get-vacancies-id-candidates","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":905,"vacancy_id":18,"name":"Maria Bondar","email":"maria@example.com","phone":"+380501234567","source":"page","stage":"new","rejected":false,"created_at":"2026-11-05T09:15:03Z","url":"https://papahr.com/hiring/18"}],"next_cursor":null}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"hiring:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"integer. From next_cursor of the previous page. 100 per page","schema":{"type":"integer"}}]},"post":{"tags":["Hiring"],"summary":"Add a candidate","description":"For the form on your own site: the person lands at the first stage and HR is notified. Sends candidate.created.","operationId":"post-vacancies-id-candidates","responses":{"201":{"description":"OK","content":{"application/json":{"example":{"data":{"id":905,"vacancy_id":18,"name":"Maria Bondar","email":"maria@example.com","phone":"+380501234567","source":"page","stage":"new","rejected":false,"created_at":"2026-11-05T09:15:03Z","url":"https://papahr.com/hiring/18"}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-papahr-scope":"hiring:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"string, required"},"email":{"type":"string","description":"string"},"phone":{"type":"string","description":"string"},"note":{"type":"string","description":"string. A cover letter or answers of your form"},"profile_url":{"type":"string","description":"url. LinkedIn or a CV link"},"source":{"type":"string","description":"page | linkedin | work_ua | robota_ua | djinni | dou | telegram | referral | other. Default page"}}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"phr_live_…"}},"responses":{"Error":{"description":"An error","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"This key may not read “hiring”."}}}}}}}}