{"openapi":"3.1.0","info":{"title":"API Reference","version":"1.0.0"},"paths":{"/staff/":{"get":{"operationId":"retrieve","summary":"List staff (employee master)","description":"Returns employee master data for the authenticated company.","tags":["staff"],"parameters":[{"name":"salarybox_id","in":"query","description":"Filter by SalaryBox ID.","required":false,"schema":{"type":"string"}},{"name":"employee_id","in":"query","description":"Filter by employee ID.","required":false,"schema":{"type":"string"}},{"name":"name","in":"query","description":"Search by employee name.","required":false,"schema":{"type":"string"}},{"name":"branches","in":"query","description":"Comma-separated branch IDs to filter by.","required":false,"schema":{"type":"string"}},{"name":"departments","in":"query","description":"Comma-separated department IDs to filter by.","required":false,"schema":{"type":"string"}},{"name":"job_title","in":"query","description":"Filter by job title.","required":false,"schema":{"type":"string"}},{"name":"phone_number","in":"query","description":"Filter by phone number.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffResponse"}}}}}}},"/attendance/break":{"get":{"operationId":"breakRetrieve","summary":"List breaks","description":"Returns the breaks configured for the authenticated company.","tags":["attendance"],"parameters":[{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreaksResponse"}}}}}}},"/attendance/daily":{"get":{"operationId":"dailyRetrieve","summary":"Daily attendance","description":"Returns per-day attendance status for every employee in the requested date range (up to 60 days), with a company-wide summary per day.","tags":["attendance"],"parameters":[{"name":"start_date","in":"query","description":"Start date (YYYY-MM-DD).","required":true,"schema":{"type":"string"}},{"name":"end_date","in":"query","description":"End date (YYYY-MM-DD). Range cannot exceed 60 days.","required":true,"schema":{"type":"string"}},{"name":"salarybox_ids","in":"query","description":"Comma-separated SalaryBox IDs to filter by.","required":false,"schema":{"type":"string"}},{"name":"branch_names","in":"query","description":"Comma-separated branch names to filter by.","required":false,"schema":{"type":"string"}},{"name":"department_names","in":"query","description":"Comma-separated department names to filter by.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyAttendanceResponse"}}}}}}},"/attendance/muster":{"get":{"operationId":"musterRetrieve","summary":"Attendance muster","description":"Returns one aggregated row per employee (status counts, overtime, late arrivals) across the requested date range, up to 60 days.","tags":["attendance"],"parameters":[{"name":"start_date","in":"query","description":"Start date (YYYY-MM-DD).","required":true,"schema":{"type":"string"}},{"name":"end_date","in":"query","description":"End date (YYYY-MM-DD). Range cannot exceed 60 days.","required":true,"schema":{"type":"string"}},{"name":"salarybox_ids","in":"query","description":"Comma-separated SalaryBox IDs to filter by.","required":false,"schema":{"type":"string"}},{"name":"branch_names","in":"query","description":"Comma-separated branch names to filter by.","required":false,"schema":{"type":"string"}},{"name":"department_names","in":"query","description":"Comma-separated department names to filter by.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttendanceMusterResponse"}}}}}}},"/attendance/shift":{"get":{"operationId":"shiftRetrieve","summary":"List shifts","description":"Returns the shifts configured for the authenticated company.","tags":["attendance"],"parameters":[{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShiftsResponse"}}}}}}},"/attendance/time-entry":{"get":{"operationId":"timeEntryRetrieve","summary":"List time entries (punches)","description":"Returns raw punch-in/punch-out entries grouped by date and employee, for a date range up to 60 days.","tags":["attendance"],"parameters":[{"name":"start_date","in":"query","description":"Start date (YYYY-MM-DD).","required":true,"schema":{"type":"string"}},{"name":"end_date","in":"query","description":"End date (YYYY-MM-DD). Range cannot exceed 60 days.","required":true,"schema":{"type":"string"}},{"name":"salarybox_ids","in":"query","description":"Comma-separated SalaryBox IDs to filter by.","required":false,"schema":{"type":"string"}},{"name":"branch_names","in":"query","description":"Comma-separated branch names to filter by.","required":false,"schema":{"type":"string"}},{"name":"department_names","in":"query","description":"Comma-separated department names to filter by.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeEntriesResponse"}}}}}}},"/payroll/summary":{"post":{"operationId":"summaryCreate","summary":"Payroll summary","description":"Computes and returns the payroll summary for the given month.","tags":["payroll"],"parameters":[{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayrollSummaryResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Input"}}}}}},"/leave/balance":{"get":{"operationId":"balanceRetrieve","summary":"List leave balances","description":"Returns leave balances per employee for the authenticated company.","tags":["leave"],"parameters":[{"name":"salarybox_ids","in":"query","description":"Comma-separated SalaryBox IDs to filter by.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaveBalanceResponse"}}}}}}},"/pending-requests/device-mapping":{"get":{"operationId":"deviceMappingRetrieve","summary":"List pending device mapping requests","description":"Returns employee device (phone) mapping requests awaiting approval for the authenticated company, most recent first.","tags":["pendingRequests"],"parameters":[{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingDeviceMappingRequestsResponse"}}}}}}},"/pending-requests/leave":{"get":{"operationId":"leaveRetrieve","summary":"List pending leave requests","description":"Returns employee leave requests awaiting approval for the authenticated company, most recent first.","tags":["pendingRequests"],"parameters":[{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingLeaveRequestsResponse"}}}}}}},"/pending-requests/reimbursements":{"get":{"operationId":"reimbursementsRetrieve","summary":"List pending reimbursement requests","description":"Returns employee reimbursement claims awaiting approval for the authenticated company, most recent first.","tags":["pendingRequests"],"parameters":[{"name":"page","in":"query","description":"Page number to fetch. Defaults to 1.","required":false,"schema":{"type":"integer"}},{"name":"page_size","in":"query","description":"Number of results per page (max 500). Defaults to 500.","required":false,"schema":{"type":"integer"}},{"name":"Authorization","in":"header","description":"Format: \"Api-Key {api-key}\"","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingReimbursementRequestsResponse"}}}}}}}},"servers":[{"url":"https://api.salaryboxapp.com/v2/customer/v1","description":"https://api.salaryboxapp.com/v2/customer/v1"}],"components":{"schemas":{"Employee":{"type":"object","properties":{"salarybox_id":{"type":"string"},"employee_id":{"type":"string"},"name":{"type":"string"},"branches":{"type":"array","items":{"description":"Any type"}},"departments":{"type":"array","items":{"description":"Any type"}},"job_title":{"type":"string"},"phone_number":{"type":"string"},"dial_code":{"type":"string"},"joining_date":{"type":"string"},"date_of_birth":{"type":"string"},"pan":{"type":"string"},"uan":{"type":"string"},"aadhaar":{"type":"string"},"driving_license":{"type":"string"},"voter_id":{"type":"string"},"email":{"type":"string"},"current_address":{"type":"string"},"permanent_address":{"type":["string","null"]},"employee_type":{"type":"string"},"gender":{"type":"string"},"marital_status":{"type":"string"},"blood_group":{"type":"string"}},"required":["salarybox_id","employee_id","name","branches","departments","job_title","phone_number","dial_code","joining_date","date_of_birth","pan","uan","aadhaar","driving_license","voter_id","email","current_address","permanent_address","employee_type","gender","marital_status","blood_group"],"title":"Employee"},"StaffResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"StaffResponse"},"Break":{"type":"object","properties":{"name":{"type":"string"},"max_duration":{"type":"integer"},"is_paid":{"type":"boolean"}},"required":["name","max_duration","is_paid"],"title":"Break"},"BreaksResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Break"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"BreaksResponse"},"AttendanceDaySummary":{"type":"object","properties":{"present":{"type":"integer"},"double_present":{"type":"integer"},"absent":{"type":"integer"},"on_leave":{"type":"integer"},"half_day":{"type":"integer"},"holiday":{"type":"integer"},"weekoff":{"type":"integer"}},"required":["present","double_present","absent","on_leave","half_day","holiday","weekoff"],"title":"AttendanceDaySummary"},"EmployeeAttendanceRecord":{"type":"object","properties":{"salarybox_id":{"type":"string"},"attendance_status":{"type":["string","null"]},"overtime":{"type":["string","null"]},"leave_type_name":{"type":["string","null"]},"is_half_day_leave":{"type":["boolean","null"]}},"required":["salarybox_id","attendance_status","overtime","leave_type_name","is_half_day_leave"],"title":"EmployeeAttendanceRecord"},"DailyAttendance":{"type":"object","properties":{"date":{"type":"string","format":"date"},"day":{"type":"string"},"summary":{"$ref":"#/components/schemas/AttendanceDaySummary"},"employees":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeAttendanceRecord"}}},"required":["date","day","summary","employees"],"description":"One entry per date in the requested range, with a company-wide summary.","title":"DailyAttendance"},"DailyAttendanceResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DailyAttendance"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"DailyAttendanceResponse"},"AttendanceMuster":{"type":"object","properties":{"employee_id":{"type":["string","null"]},"is_active":{"type":"boolean"},"phone_number":{"type":["string","null"]},"designation":{"type":["string","null"]},"employee_name":{"type":"string"},"overtime_weekday":{"type":"string","format":"decimal","pattern":"^\\d{0,8}(?:\\.\\d{0,2})?$"},"overtime_holiday":{"type":"string","format":"decimal","pattern":"^\\d{0,8}(?:\\.\\d{0,2})?$"},"overtime_weekoff":{"type":"string","format":"decimal","pattern":"^\\d{0,8}(?:\\.\\d{0,2})?$"},"early_leaving":{"type":"integer"},"late_arrival":{"type":"integer"},"absent":{"type":"integer"},"present":{"type":"integer"},"double_present":{"type":"integer"},"half_day":{"type":"string","title":"float"},"week_off":{"type":"integer"},"holiday":{"type":"integer"},"paid_leave":{"type":"string","title":"float"},"unpaid_leave":{"type":"integer"},"half_day_leave":{"type":"integer"},"total":{"type":"integer"}},"required":["employee_id","is_active","phone_number","designation","employee_name","overtime_weekday","overtime_holiday","overtime_weekoff","early_leaving","late_arrival","absent","present","double_present","half_day","week_off","holiday","paid_leave","unpaid_leave","half_day_leave","total"],"description":"One entry per employee, aggregated across the requested date range.","title":"AttendanceMuster"},"AttendanceMusterResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AttendanceMuster"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"AttendanceMusterResponse"},"Shift":{"type":"object","properties":{"name":{"type":"string"},"start_time":{"type":"string"},"end_time":{"type":"string"},"min_punch_in_duration":{"type":["integer","null"]},"max_punch_out_duration":{"type":["integer","null"]}},"required":["name","start_time","end_time","min_punch_in_duration","max_punch_out_duration"],"title":"Shift"},"ShiftsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Shift"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"ShiftsResponse"},"Punch":{"type":"object","properties":{"type":{"type":"string"},"time":{"type":"string"},"timezone":{"type":"string"},"address":{"type":["string","null"]},"branch_name":{"type":["string","null"]},"shift_name":{"type":["string","null"]},"break_name":{"type":["string","null"]}},"required":["type","time","timezone","address","branch_name","shift_name","break_name"],"title":"Punch"},"EmployeePunches":{"type":"object","properties":{"salarybox_id":{"type":"string"},"punches":{"type":"array","items":{"$ref":"#/components/schemas/Punch"}}},"required":["salarybox_id","punches"],"title":"EmployeePunches"},"DailyPunches":{"type":"object","properties":{"date":{"type":"string","format":"date"},"employees":{"type":"array","items":{"$ref":"#/components/schemas/EmployeePunches"}}},"required":["date","employees"],"description":"One entry per date, listing punches grouped by employee.","title":"DailyPunches"},"TimeEntriesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DailyPunches"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"TimeEntriesResponse"},"Input":{"type":"object","properties":{"month_from_date":{"type":"string","format":"date"}},"required":["month_from_date"],"title":"Input"},"PayrollSummaryData":{"type":"object","properties":{"ctc_not_defined_employee_count":{"type":"integer"},"cards":{"type":"object","additionalProperties":{"description":"Any type"}},"loan_details":{"type":"object","additionalProperties":{"description":"Any type"}}},"required":["ctc_not_defined_employee_count","cards","loan_details"],"title":"PayrollSummaryData"},"PayrollSummaryResponse":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PayrollSummaryData"}},"required":["message","status","data"],"title":"PayrollSummaryResponse"},"LeaveBalanceItem":{"type":"object","properties":{"leave_type":{"type":"string"},"total":{"type":"string"},"remaining":{"type":"string"}},"required":["leave_type","total","remaining"],"title":"LeaveBalanceItem"},"EmployeeLeaveBalance":{"type":"object","properties":{"salarybox_id":{"type":"string"},"leaves":{"type":"array","items":{"$ref":"#/components/schemas/LeaveBalanceItem"}}},"required":["salarybox_id","leaves"],"title":"EmployeeLeaveBalance"},"LeaveBalanceResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeLeaveBalance"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"LeaveBalanceResponse"},"PendingDeviceMappingRequest":{"type":"object","properties":{"salarybox_id":{"type":"string"},"employee_name":{"type":"string"},"device_model":{"type":"string"},"created_on":{"type":"string","format":"date-time"}},"required":["salarybox_id","employee_name","device_model","created_on"],"title":"PendingDeviceMappingRequest"},"PendingDeviceMappingRequestsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PendingDeviceMappingRequest"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"PendingDeviceMappingRequestsResponse"},"PendingLeaveRequest":{"type":"object","properties":{"salarybox_id":{"type":"string"},"employee_name":{"type":"string"},"leave_type":{"type":"string"},"from_date":{"type":"string","format":"date"},"to_date":{"type":"string","format":"date"},"is_half_day":{"type":"boolean"},"reason":{"type":"string"},"created_on":{"type":"string","format":"date-time"}},"required":["salarybox_id","employee_name","leave_type","from_date","to_date","is_half_day","reason","created_on"],"title":"PendingLeaveRequest"},"PendingLeaveRequestsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PendingLeaveRequest"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"PendingLeaveRequestsResponse"},"PendingReimbursementRequest":{"type":"object","properties":{"salarybox_id":{"type":"string"},"employee_name":{"type":"string"},"amount":{"type":"string","format":"decimal","pattern":"^\\d{0,8}(?:\\.\\d{0,2})?$"},"notes":{"type":"string"},"reimbursement_date":{"type":"string","format":"date"},"created_on":{"type":"string","format":"date-time"}},"required":["salarybox_id","employee_name","amount","notes","reimbursement_date","created_on"],"title":"PendingReimbursementRequest"},"PendingReimbursementRequestsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PendingReimbursementRequest"}},"message":{"type":"string"},"status":{"type":"boolean"},"count":{"type":"integer"},"prev":{"type":["string","null"]},"next":{"type":["string","null"]}},"required":["data","message","status","count","prev","next"],"title":"PendingReimbursementRequestsResponse"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Format: \"Api-Key {api-key}\""}}}}