{"openapi":"3.0.3","info":{"title":"PeopleBook read API","version":"1.0.0","description":"Company-authorised server-to-server reads. See /developers for access, pagination and integration limitations."},"servers":[{"url":"https://peoplebook.wcreatesdigital.com/api/v1"}],"security":[{"bearerKey":[]}],"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"Company-scoped pbkey_ key created by the owner in Settings → AI connections."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"paths":{"/companies":{"get":{"summary":"Authorised companies","description":"Returned fields: companyId, name, mode, payrollAllowed","operationId":"get_companies","parameters":[],"responses":{"200":{"description":"Authorised data. Lists are paginated at 50 rows.","content":{"application/json":{"schema":{"type":"object","properties":{"companies":{"type":"array","items":{"type":"object","description":"companyId, name, mode, payrollAllowed"}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or malformed key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access or consent denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/summary":{"get":{"summary":"Company summary","description":"Returned fields: Company identity, activeEmployees, pendingRequests, mode","operationId":"get_summary","parameters":[{"name":"company_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Authorised data. Lists are paginated at 50 rows.","content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object"}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or malformed key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access or consent denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/employees":{"get":{"summary":"Employee directory","description":"Returned fields: id, number, name, email, department, designation, branch, start_date, end_date, active, employment_type, pay_basis, weekly_hours","operationId":"get_employees","parameters":[{"name":"company_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Authorised data. Lists are paginated at 50 rows.","content":{"application/json":{"schema":{"type":"object","properties":{"employees":{"type":"array","items":{"type":"object","description":"id, number, name, email, department, designation, branch, start_date, end_date, active, employment_type, pay_basis, weekly_hours"}},"nextOffset":{"type":"integer","nullable":true}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or malformed key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access or consent denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leave-balances":{"get":{"summary":"Leave balances","description":"Returned fields: employee_id, leave_type, year, entitlement, pending, used, available","operationId":"get_leave_balances","parameters":[{"name":"company_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Authorised data. Lists are paginated at 50 rows.","content":{"application/json":{"schema":{"type":"object","properties":{"balances":{"type":"array","items":{"type":"object","description":"employee_id, leave_type, year, entitlement, pending, used, available"}},"nextOffset":{"type":"integer","nullable":true}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or malformed key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access or consent denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests":{"get":{"summary":"Request summaries","description":"Returned fields: id, employee_id, kind, title, start_date, end_date, leave_type, units, amount_cents, status, version","operationId":"get_requests","parameters":[{"name":"company_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Authorised data. Lists are paginated at 50 rows.","content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","items":{"type":"object","description":"id, employee_id, kind, title, start_date, end_date, leave_type, units, amount_cents, status, version"}},"nextOffset":{"type":"integer","nullable":true}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or malformed key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access or consent denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/attendance":{"get":{"summary":"Attendance records","description":"Returned fields: id, employee_id, in_at, out_at, break_minutes","operationId":"get_attendance","parameters":[{"name":"company_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Authorised data. Lists are paginated at 50 rows.","content":{"application/json":{"schema":{"type":"object","properties":{"attendance":{"type":"array","items":{"type":"object","description":"id, employee_id, in_at, out_at, break_minutes"}},"nextOffset":{"type":"integer","nullable":true}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or malformed key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access or consent denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shifts":{"get":{"summary":"Roster shifts","description":"Returned fields: id, employee_id, title, starts_at, ends_at, break_minutes, published","operationId":"get_shifts","parameters":[{"name":"company_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Authorised data. Lists are paginated at 50 rows.","content":{"application/json":{"schema":{"type":"object","properties":{"shifts":{"type":"array","items":{"type":"object","description":"id, employee_id, title, starts_at, ends_at, break_minutes, published"}},"nextOffset":{"type":"integer","nullable":true}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or malformed key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access or consent denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payroll":{"get":{"summary":"Payroll summaries","description":"Returned fields: id, period, status, payment_status, totals; amountUnit: SGD integer cents. Requires separate payroll consent.","operationId":"get_payroll","parameters":[{"name":"company_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Authorised data. Lists are paginated at 50 rows.","content":{"application/json":{"schema":{"type":"object","properties":{"payroll":{"type":"array","items":{"type":"object","description":"id, period, status, payment_status, totals; amountUnit: SGD integer cents"}},"nextOffset":{"type":"integer","nullable":true}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or malformed key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access or consent denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}