{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","description":"# Multiplier Public REST API\n\nWelcome to the Multiplier Public REST API documentation. This API enables partner integrations\nwith the Multiplier platform, providing access to core business operations including:\n\n- **Authentication & Authorization**: Secure access to platform resources\n- **Partner Management**: Company and partner profile operations\n- **Data Synchronization**: Real-time data exchange and updates\n- **Webhook Management**: Event-driven integration capabilities\n- **Resource Provisioning**: Access to platform resources and services\n\n## Getting Started\n\n1. **Authentication**: Obtain API credentials from your Multiplier account manager\n2. **Authorization**: Use Bearer token authentication for all protected endpoints\n3. **Testing**: Use the \"Authorize\" button below to authenticate and test endpoints\n4. **Integration**: Download the OpenAPI specification for SDK generation\n\n## API Conventions\n\n- All endpoints follow RESTful conventions\n- Request/response bodies use JSON format\n- Timestamps are in ISO 8601 format (UTC)\n- Pagination uses limit/offset parameters\n- Error responses follow RFC 7807 Problem Details format\n\n## Support\n\nFor technical support, integration assistance, or API questions:\n- Email: api-support@usemultiplier.com\n- Documentation: https://docs.usemultiplier.com\n- Status Page: https://status.usemultiplier.com","contact":{"name":"Multiplier API Support","url":"https://docs.usemultiplier.com","email":"api-support@usemultiplier.com"},"license":{"name":"Proprietary","url":"https://www.usemultiplier.com/terms"},"version":"1.0.0"},"servers":[{"url":"https://api.usemultiplier.com","description":"Production API / Partner Sandbox"},{"url":"https://release-api-gateway.api.usemultiplier.com","description":"MPL internal release environment"},{"url":"https://api-gateway.api.acc.staging.usemultiplier.com","description":"MPL internal staging"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Authentication","description":"Authentication and authorization endpoints for secure access to the Multiplier platform","x-page-title":"Authentication","x-page-description":"Authentication and authorization endpoints for secure access to the Multiplier platform","x-page-icon":"lock"},{"name":"OAuth","description":"OAuth 2.0 authorization code flow for partner authentication","x-page-title":"OAuth","x-page-description":"OAuth 2.0 authorization code flow for partner authentication","x-page-icon":"key","x-parent":"Authentication"},{"name":"Partner Token","description":"Generate access tokens for partner integrations using client credentials","x-page-title":"Partner Token","x-page-description":"Generate access tokens for partner integrations using client credentials","x-page-icon":"shield-check","x-parent":"Authentication"},{"name":"Magic Links","description":"Authorization code generation and exchange for seamless user authentication","x-page-title":"Magic Links","x-page-description":"Authorization code generation and exchange for seamless user authentication","x-page-icon":"link","x-parent":"Authentication"},{"name":"JWKS Controller","description":"JSON Web Key Set endpoints for token verification","x-page-title":"JWKS","x-page-description":"JSON Web Key Set endpoints for token verification","x-page-icon":"fingerprint","x-parent":"Authentication"},{"name":"Partner Management","description":"Manage partner customers and customer users","x-page-title":"Partner Management","x-page-description":"Manage partner customers and customer users","x-page-icon":"briefcase"},{"name":"Customers","description":"Manage customer profiles and information","x-page-title":"Customers","x-page-description":"Manage customer profiles and information","x-page-icon":"building","x-parent":"Partner Management"},{"name":"Customer Users","description":"Manage customer user accounts and access","x-page-title":"Customer Users","x-page-description":"Manage customer user accounts and access","x-page-icon":"users","x-parent":"Partner Management"},{"name":"Customer Departments","description":"Manage customer departments","x-page-title":"Customer Departments","x-page-description":"Manage customer departments","x-page-icon":"building","x-parent":"Partner Management"},{"name":"Customer Management","description":"Manage customer profiles and information","x-page-title":"Customer Management","x-page-description":"Manage customer profiles and information","x-page-icon":"building"},{"name":"Customer Entities","description":"Manage customer entities","x-page-title":"Customer Entities","x-page-description":"Manage customer entities","x-page-icon":"building","x-parent":"Customer Management"},{"name":"Employee Management","description":"Access and manage employee information across all domains","x-page-title":"Employee Management","x-page-description":"Access and manage employee information across all domains","x-page-icon":"user-circle"},{"name":"List Employees","description":"Search and list employees","x-page-title":"List Employees","x-page-description":"Search and list employees","x-page-icon":"list","x-parent":"Employee Management"},{"name":"Employee Personal Details","description":"Access employee personal information","x-page-title":"Employee Personal Details","x-page-description":"Access employee personal information","x-page-icon":"user","x-parent":"Employee Management"},{"name":"Employee Address Details","description":"Access employee address information","x-page-title":"Employee Address Details","x-page-description":"Access employee address information","x-page-icon":"map-pin","x-parent":"Employee Management"},{"name":"Employee Contact Details","description":"Access employee contact information","x-page-title":"Employee Contact Details","x-page-description":"Access employee contact information","x-page-icon":"phone","x-parent":"Employee Management"},{"name":"Employee Bank Details","description":"Access employee banking information","x-page-title":"Employee Bank Details","x-page-description":"Access employee banking information","x-page-icon":"credit-card","x-parent":"Employee Management"},{"name":"Employee Compensation Details","description":"Access employee compensation and salary information","x-page-title":"Employee Compensation Details","x-page-description":"Access employee compensation and salary information","x-page-icon":"dollar-sign","x-parent":"Employee Management"},{"name":"Employee Education Details","description":"Access employee education history","x-page-title":"Employee Education Details","x-page-description":"Access employee education history","x-page-icon":"book-open","x-parent":"Employee Management"},{"name":"Employee Employment Details","description":"Access employee employment history and status","x-page-title":"Employee Employment Details","x-page-description":"Access employee employment history and status","x-page-icon":"briefcase","x-parent":"Employee Management"},{"name":"Time Offs","description":"Manage employee time off requests and tracking","x-page-title":"Time Offs","x-page-description":"Manage employee time off requests and tracking","x-page-icon":"calendar","x-parent":"Employee Management"},{"name":"Timesheet","description":"Manage employee timesheet entries and hours tracking","x-page-title":"Time & Attendance","x-page-description":"Manage employee timesheet entries and hours tracking","x-page-icon":"clock","x-parent":"Employee Management"},{"name":"Create GP Employment","description":"Create and onboard Global Payroll employees","x-page-title":"Create GP Employment","x-page-description":"Create and onboard Global Payroll employees","x-page-icon":"user-plus","x-parent":"Employee Management"},{"name":"Approver Management","description":"Manage approver assignments for employees across approval categories","x-page-title":"Approver Management","x-page-description":"Manage approver assignments for employees across approval categories","x-page-icon":"user-check","x-parent":"Employee Management"},{"name":"Dev Support","description":"Development-only endpoints for test employee lifecycle management","x-page-title":"Dev Support","x-page-description":"Development-only endpoints for test employee lifecycle management","x-page-icon":"wrench","x-parent":"Employee Management"}],"paths":{"/v1/employees":{"get":{"tags":["List Employees"],"summary":"Search and list employees","description":"Retrieve a paginated list of employees based on various filter criteria.\n\nEmployees are automatically filtered by the company associated with your authentication token.\n\nThis endpoint allows you to:\n- Filter employees by status\n- Sort results by various fields\n- Paginate through large result sets\n\n**Filter Precedence:**\nWhen both `employeeId` and `employeeCode` are provided, `employeeId` takes precedence.\nIt is recommended to use only one filter at a time for clarity.\n","operationId":"searchEmployees","parameters":[{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"style":"form","explode":true,"schema":{"minimum":1,"type":"integer","example":1,"default":1}},{"name":"pageSize","in":"query","description":"Number of items per page","required":false,"style":"form","explode":true,"schema":{"maximum":100,"minimum":1,"type":"integer","example":20,"default":20}},{"name":"status","in":"query","description":"Filter by employment status","required":false,"style":"form","explode":true,"schema":{"$ref":"#/components/schemas/EmployeeStatus"},"example":"ACTIVE"},{"name":"employeeId","in":"query","description":"Filter by employee ID (UUID, exact match)","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},{"name":"employeeCode","in":"query","description":"Filter by human-readable employee code (exact match)","required":false,"style":"form","explode":true,"schema":{"type":"string"},"example":"EMP-12345"},{"name":"sortBy","in":"query","description":"Field to sort by. Currently only supports \"startOn\".","required":false,"style":"form","explode":true,"schema":{"$ref":"#/components/schemas/SortByField"},"example":"startOn"},{"name":"sortOrder","in":"query","description":"Sort direction","required":false,"style":"form","explode":true,"schema":{"$ref":"#/components/schemas/SortOrder"},"example":"DESC"}],"responses":{"200":{"description":"Successfully retrieved employee list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesGetResponse"},"example":{"data":[{"id":"123e4567-e89b-12d3-a456-426614174000","employeeCode":"EMP-12345","employeeId":"EMP-12345","firstName":"John","middleName":"Michael","lastName":"Doe","fullName":"John Michael Doe","displayName":"John Doe","workEmail":"john.doe@company.com","designation":"Senior Software Engineer","department":"Engineering","status":"ACTIVE","type":"FULL_TIME","startDate":"2023-01-15","endDate":null,"country":"USA","customerId":"550e8400-e29b-41d4-a716-446655440000","customerName":"Tech Corp Inc","entity":"Tech Corp Singapore Pte Ltd"}],"pagination":{"currentPage":1,"pageSize":20,"totalPages":5,"totalItems":100,"hasNextPage":true,"hasPreviousPage":false}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/onboarding-tracker":{"get":{"tags":["List Employees"],"summary":"Get onboarding tracker","description":"Returns the current onboarding stage for each employee currently in the onboarding lifecycle.\n\nOptional filters narrow the result to a specific employee. When both filters are provided\nthey are applied as an AND (intersection).\n","operationId":"getOnboardingTracker","parameters":[{"name":"employeeId","in":"query","description":"Filter by employee ID (UUID, exact match)","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},{"name":"employeeCode","in":"query","description":"Filter by human-readable employee code (exact match)","required":false,"style":"form","explode":true,"schema":{"type":"string"},"example":"EMP-12345"}],"responses":{"200":{"description":"Successfully retrieved onboarding tracker list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OnboardingTrackerItem"}},"example":[{"id":"123e4567-e89b-12d3-a456-426614174000","employeeCode":"EMP-12345","stage":"VERIFICATION"}]}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/offboarding-tracker":{"get":{"tags":["List Employees"],"summary":"Get offboarding tracker","description":"Returns the current offboarding stage for each employee currently in the offboarding lifecycle.\n\nOptional filters narrow the result to a specific employee. When both filters are provided\nthey are applied as an AND (intersection).\n","operationId":"getOffboardingTracker","parameters":[{"name":"employeeId","in":"query","description":"Filter by employee ID (UUID, exact match)","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},{"name":"employeeCode","in":"query","description":"Filter by human-readable employee code (exact match)","required":false,"style":"form","explode":true,"schema":{"type":"string"},"example":"EMP-12345"}],"responses":{"200":{"description":"Successfully retrieved offboarding tracker list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OffboardingTrackerItem"}},"example":[{"id":"123e4567-e89b-12d3-a456-426614174000","employeeCode":"EMP-12345","stage":"DOCUMENTS_PENDING","pendingDocuments":["WET_INK_LETTER"]}]}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/dynamic-details/schema":{"get":{"tags":["Create GP Employment"],"summary":"Get employee creation form schema","description":"Returns the form schema (field definitions and validation rules) needed to create an employee\nunder a specific employment context.\n\nThe schema describes required and optional fields, their types, validation constraints,\nand allowed values for the given context.\n\n**Context Types:**\n- **GP Employment**: Provide `entity` to get the schema for a Global Payroll employee creation.\n","operationId":"getEmployeeDynamicDetailsSchema","parameters":[{"name":"employmentType","in":"query","description":"Type of employment. Required for all contexts.\n","required":true,"style":"form","explode":true,"schema":{"$ref":"#/components/schemas/EmploymentType"},"example":"GLOBAL_PAYROLL"},{"name":"entity","in":"query","description":"Legal entity name. Required for GP employment context.\nWhen provided, the schema returned is for creating a GP employee under this entity.\n","required":false,"style":"form","explode":true,"schema":{"type":"string"},"example":"Tech Corp Singapore Pte Ltd"}],"responses":{"200":{"description":"Form schema retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1GetEmployeeDynamicDetailsSchemaResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}}}}},"/v1/employees/gp-employments":{"post":{"tags":["Create GP Employment"],"summary":"Create a GP (Global Payroll) employee","description":"Creates, onboards a Global Payroll employee in a single call.\n\nHandles the full onboarding flow including personal details, contact information,\nemployment terms, compensation, and compliance setup.\n","operationId":"createGpEmployment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1GpEmploymentsPostRequest"}}},"required":true},"responses":{"201":{"description":"GP employee created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1GpEmploymentsPostResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"409":{"description":"Conflict - resource already exists or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"CONFLICT","message":"Resource already exists","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Resource already exists"}],"error":{"code":"CONFLICT","message":"Resource already exists","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/dynamic-details":{"patch":{"tags":["Create GP Employment"],"summary":"Submit dynamic data for employee creation","description":"Submits dynamic field values (as required by the schema returned from `GET /v1/employees/schema`)\nfor a GP employment record.\n\nUse this endpoint **after** getting the schema to know which fields are required, and after\ncreating the basic employment record. The submitted values populate the dynamic sections:\nlegal details and custom fields.\n","operationId":"submitEmployeeDynamicDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1SubmitEmployeesDynamicDetailsRequest"}}},"required":true},"responses":{"204":{"description":"Dynamic data submitted successfully"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/personal":{"get":{"tags":["Employee Personal Details"],"summary":"Retrieve employee personal details","description":"Get comprehensive personal information about an employee including name, date of birth,\ngender, and marital status.\n\nThis endpoint provides access to the employee's personal profile data that is typically\nused for HR records, compliance, and employee management purposes.\n","operationId":"getEmployeePersonalDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Employee personal details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdPersonalGetResponse"},"example":{"firstName":"Foo","middleName":null,"lastName":"Bar","fullLegalName":"Foo Bar","dateOfBirth":"2000-10-11","gender":"MALE","maritalStatus":"SINGLE","age":25,"religion":"Sikh","nationalities":[{"country":"CHE","type":"CITIZEN"}]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/contact":{"get":{"tags":["Employee Contact Details"],"summary":"Retrieve employee contact details","description":"Get employee contact information including personal email, phone number,\nand emergency contact details.\n\nThis endpoint provides access to all communication channels for reaching the employee\nand their designated emergency contact person.\n","operationId":"getEmployeeContactDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Employee contact details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdContactGetResponse"},"example":{"personalEmail":"foo.bar@personal.com","personalPhoneNumber":"+41791234567","emergencyContact":{"name":"Jane Doe","phoneNumber":"+41791234568","relationship":"SPOUSE"}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/address":{"get":{"tags":["Employee Address Details"],"summary":"Retrieve employee address details","description":"Get employee address information including current residential address and permanent address.\n\nThis endpoint provides access to the employee's current and permanent addresses,\nwhich are used for official correspondence, tax purposes, and compliance requirements.\n","operationId":"getEmployeeAddressDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Employee address details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdAddressGetResponse"},"example":{"currentAddress":{"addressLine1":"123 Main Street","addressLine2":"Apartment 4B","streetName":"Main Street","landmark":"Near Central Park","city":"Zurich","subdivision":"Zurich","country":"CHE","postalCode":"8001"},"permanentAddress":{"addressLine1":"456 Oak Avenue","addressLine2":null,"streetName":"Oak Avenue","landmark":null,"city":"Geneva","subdivision":"Geneva","country":"CHE","postalCode":"1200"}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/bank":{"get":{"tags":["Employee Bank Details"],"summary":"Retrieve employee bank account details","description":"Get employee bank account information for salary payments and financial transactions.\n\nThis endpoint provides access to the employee's bank account details including\naccount number, bank name, SWIFT code, and other banking information required\nfor processing salary payments.\n","operationId":"getEmployeeBankDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Employee bank details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdBankGetResponse"},"example":{"accountNumber":"1234567890","accountHolderName":"Foo Bar","bankName":"Swiss National Bank","branchName":"Zurich Branch","swiftCode":"SNBZCHZZ","localBankCode":"12345","accountType":"PERSONAL","currency":"CHF","country":"CHE"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/education":{"get":{"tags":["Employee Education Details"],"summary":"Retrieve employee education details","description":"Get employee education history including schools attended, degrees earned,\ngraduation years, and academic performance.\n\nThis endpoint provides access to the employee's educational background,\nwhich is used for qualification verification and HR records.\n","operationId":"getEmployeeEducationDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Employee education details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdEducationGetResponse"},"example":{"education":[{"lastSchoolAttended":"University of Zurich","degree":"Bachelor of Science in Computer Science","yearOfPassing":2022,"grade":"A","gpa":3.8},{"lastSchoolAttended":"Zurich High School","degree":"High School Diploma","yearOfPassing":2018,"grade":"A-","gpa":null}]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/employment":{"get":{"tags":["Employee Employment Details"],"summary":"Retrieve employee employment details","description":"Get comprehensive employment information including job details,\nemployment status, and work history.\n\nThis endpoint provides access to the employee's current employment details\nand reporting structure.\n","operationId":"getEmployeeEmploymentDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Employee employment details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdEmploymentGetResponse"},"example":{"employeeCode":"EMP-12345","workEmail":"john.doe@company.com","entity":"Tech Corp Singapore Pte Ltd","country":"SGP","startDate":"2023-01-15","status":"ACTIVE","endDate":null,"designation":"Software Engineer","department":"Engineering","type":"EMPLOYEE","term":"PERMANENT","noticePeriod":{"value":"3","unit":"MONTHS"},"reportsTo":{"id":"550e8400-e29b-41d4-a716-446655440000","firstName":"Jane","lastName":"Smith","designation":"Engineering Manager"}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}},"patch":{"tags":["Employee Employment Details"],"summary":"Update employee employment details","description":"Update employment details for a specific employee.\n\nThis endpoint allows partial updates to employment information. Only the fields\nprovided in the request body will be updated; other fields remain unchanged.\n\n**Important:** At least one field must be provided in the request body.\nEmpty requests (no-op operations) are not allowed and will return a 400 Bad Request.\n\n**Currently Supported Fields (Phase 1):**\n- `employeeCode` - The employee's unique identifier code within the organization\n\n**Future Fields (Planned):**\n- `designation` - Job title or position\n- `department` - Department name\n- `workEmail` - Work email address\n- `noticePeriod` - Notice period details\n\n**Read-Only Fields (Not Updatable):**\nFields such as `entity`, `startDate`, `endDate`, `status`, `type`, and `term`\nare managed through other processes and cannot be updated via this endpoint.\n","operationId":"updateEmployeeEmploymentDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdEmploymentPatchRequest"},"example":{"employeeCode":"EMP-2024-001"}}},"required":true},"responses":{"200":{"description":"Employee employment details updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdEmploymentPatchResponse"},"example":{"employeeId":"123e4567-e89b-12d3-a456-426614174000","employeeCode":"EMP-2024-001"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"409":{"description":"Conflict - resource already exists or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"CONFLICT","message":"Resource already exists","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Resource already exists"}],"error":{"code":"CONFLICT","message":"Resource already exists","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/compensation":{"get":{"tags":["Employee Compensation Details"],"summary":"Retrieve employee compensation details","description":"Get comprehensive compensation information including salary, pay frequency, \nand structured allowance breakdowns.\n\nThis endpoint provides access to the employee's compensation details including\ngross salary, designation, salary frequency, effective date, and detailed \nsalary breakup components.\n","operationId":"getEmployeeCompensationDetails","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Employee compensation details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdCompensationGetResponse"},"example":{"compensationDetails":{"baseSalary":{"amount":50000.0,"currency":"INR","frequency":"MONTHLY"},"designation":"CSM","salaryFrequency":"MONTHLY","effectiveFrom":"2025-10-31","additionalPays":[{"name":"HRA","label":"House Rent Allowance","amount":3497.0,"currency":"INR","frequency":"MONTHLY"},{"name":"LTA","label":"Leave Travel Allowance","amount":9474.0,"currency":"INR","frequency":"MONTHLY"}]}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/dev-activate":{"post":{"tags":["Dev Support"],"summary":"[DEV ONLY] Activate a test employee's employment","description":"**For dev testing purposes only. Not intended for production use.**\n\nActivates a test employee's employment by transitioning it from ONBOARDING to ACTIVE status.\nThis endpoint only works for test employments (isTest = true). Attempting to activate a\nnon-test employment will return a 400 Bad Request.\n\nThe employee must have completed all onboarding steps before this call succeeds.\nThis operation is idempotent with respect to side-effects and status — calling\nit on an already-ACTIVE employment is a no-op.\n","operationId":"devActivateEmployee","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Employment successfully activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdDevActivatePostResponse"},"example":{"employeeId":"123e4567-e89b-12d3-a456-426614174000","status":"ACTIVE","activatedOn":"2026-03-23T10:00:00Z"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"409":{"description":"Conflict - resource already exists or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"CONFLICT","message":"Resource already exists","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Resource already exists"}],"error":{"code":"CONFLICT","message":"Resource already exists","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}":{"delete":{"tags":["List Employees"],"summary":"Delete an employee that is still in onboarding","description":"Deletes an employee by ID that is still in onboarding.\n","operationId":"deleteEmployee","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"204":{"description":"Employee successfully deleted"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"409":{"description":"Conflict - resource already exists or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"CONFLICT","message":"Resource already exists","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Resource already exists"}],"error":{"code":"CONFLICT","message":"Resource already exists","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/dev-deactivate":{"post":{"tags":["Dev Support"],"summary":"[DEV ONLY] Deactivate a test employee's employment","description":"**For dev testing purposes only. Not intended for production use.**\n\nDeactivates a test employee's employment by fast-tracking it to its\nterminal offboarding state. This endpoint only works for test employments (isTest = true).\nAttempting to deactivate a non-test employment will return a 400 Bad Request.\n\nThe employment must be initialized offboarding before this call succeeds.\n","operationId":"devDeactivateEmployee","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Employment successfully deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdDevDeactivatePostResponse"},"example":{"employeeId":"123e4567-e89b-12d3-a456-426614174000","status":"COMPLETED"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"409":{"description":"Conflict - resource already exists or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"CONFLICT","message":"Resource already exists","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Resource already exists"}],"error":{"code":"CONFLICT","message":"Resource already exists","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}},"security":[{"BearerAuth":[]}]}},"/v1/employees/{employeeId}/approvers":{"get":{"tags":["Approver Management"],"summary":"Get approver assignments for an employee","description":"Retrieve the current approver assignments for a specific employee across all approval categories.\n\nReturns a list of approver assignments, where each entry contains the approval scope (category)\nand the UUID of the assigned approver (company user).\n","operationId":"getEmployeeApprovers","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Approver assignments retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApproverInfo"}}}},"example":{"data":[{"scope":"TIME_OFF","approverId":"123e4567-e89b-12d3-a456-426614174000"},{"scope":"TIME_SHEET","approverId":"456e7890-e89b-12d3-a456-426614174001"}]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}},"delete":{"tags":["Approver Management"],"summary":"Remove approver assignments for an employee","description":"Remove approver assignments for specified approval categories from an employee's employment.\n\nThe response returns the resulting state after all specified approver assignments have been removed.\n","operationId":"deleteEmployeeApprovers","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteEmployeeApproversRequest"},"example":{"scopes":["TIME_OFF","TIME_SHEET"]}}},"required":true},"responses":{"204":{"description":"Approver assignments removed successfully"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}},"patch":{"tags":["Approver Management"],"summary":"Update approver assignments for an employee","description":"Assign or update approvers for specific approval categories for an employee.\n\nEach entry in the request body specifies an approval scope and the UUID of the\ncompany user to assign as approver for that scope. The response returns the\nresulting state after all assignments have been applied.\n","operationId":"updateEmployeeApprovers","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApproverInfo"}},"example":[{"scope":"TIME_OFF","approverId":"123e4567-e89b-12d3-a456-426614174000"},{"scope":"TIME_SHEET","approverId":"456e7890-e89b-12d3-a456-426614174001"}]}},"required":true},"responses":{"200":{"description":"Approver assignments updated successfully — returns resulting state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApproverInfo"}}}},"example":{"data":[{"scope":"TIME_OFF","approverId":"123e4567-e89b-12d3-a456-426614174000"},{"scope":"TIME_SHEET","approverId":"456e7890-e89b-12d3-a456-426614174001"}]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/payslips":{"get":{"tags":["Employee Compensation Details"],"summary":"List payslips for an employee","description":"Retrieves a paginated list of payslips for a specific employee.\n","operationId":"listPayslips","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"style":"form","explode":true,"schema":{"minimum":1,"type":"integer","example":1,"default":1}},{"name":"pageSize","in":"query","description":"Number of items per page","required":false,"style":"form","explode":true,"schema":{"maximum":100,"minimum":1,"type":"integer","example":20,"default":20}}],"responses":{"200":{"description":"Payslips retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdPayslipsGetResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/employees/{employeeId}/payslips/{payslipId}":{"get":{"tags":["Employee Compensation Details"],"summary":"Get payslip download URL","description":"Retrieves a pre-signed download URL for a specific published payslip.\n","operationId":"getPayslipDownloadUrl","parameters":[{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},{"name":"payslipId","in":"path","description":"Unique identifier of the payslip","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"019f4b79-b3fe-7138-b4b6-1037923bb712"}],"responses":{"200":{"description":"Payslip download URL retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdPayslipsPayslipIdGetResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/expenses":{"get":{"tags":["expenses"],"summary":"List and search expense claims","description":"Retrieve a paginated list of expense claims with filtering and sorting capabilities.\n\nThis endpoint allows partners to:\n- Search expenses by employee name\n- Filter by expense status (draft, approved, paid, etc.)\n- Use predefined views for common queries\n- Sort by submission date, amount, or creation date\n- Paginate through large result sets\n\nResults include expense summary information and can be filtered to show only relevant expenses based on status, employee, or predefined views.\n","operationId":"listExpenses","parameters":[{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"style":"form","explode":true,"schema":{"minimum":1,"type":"integer","example":1,"default":1}},{"name":"pageSize","in":"query","description":"Number of items per page","required":false,"style":"form","explode":true,"schema":{"maximum":100,"minimum":1,"type":"integer","example":20,"default":20}},{"name":"memberName","in":"query","description":"Filter expenses by employee name (supports partial matching)","required":false,"style":"form","explode":true,"schema":{"type":"string"},"example":"John Doe"},{"name":"status","in":"query","description":"Filter by expense status (can specify multiple values)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["DRAFT","REVOKED","APPROVAL_IN_PROGRESS","APPROVED","REJECTED","PROCESSING","PAID","TO_BE_PAID","ON_HOLD"]}},"example":["APPROVED","PAID"]},{"name":"view","in":"query","description":"Predefined view filter for common queries","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["ALL_PENDING","PENDING_ON_ME","HISTORY"]},"example":"ALL_PENDING"},{"name":"sortBy","in":"query","description":"Field to sort results by","required":false,"style":"form","explode":true,"schema":{"type":"string","default":"submittedAt","enum":["submittedAt","totalAmount","createdOn","updatedOn"]},"example":"submittedAt"},{"name":"sortOrder","in":"query","description":"Sort direction","required":false,"style":"form","explode":true,"schema":{"type":"string","default":"DESC","enum":["ASC","DESC"]},"example":"DESC"}],"responses":{"200":{"description":"List of expenses retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ExpensesGetResponse"},"example":{"data":[{"expenseId":"550e8400-e29b-41d4-a716-446655440000","title":"Business Travel - Singapore","status":"APPROVED","totalAmount":1250.5,"currency":"USD","submittedAt":"2025-10-15T10:30:00Z","createdOn":"2025-10-14T08:00:00Z","employeeId":"123e4567-e89b-12d3-a456-426614174000","items":[{"itemId":"item-001","title":"Flight Ticket","amount":850.0,"date":"2025-10-10T00:00:00Z","category":{"id":"cat-001","name":"Travel"},"description":"Round trip flight to Singapore"}]}],"pagination":{"page":1,"pageSize":20,"totalCount":45,"totalPages":3}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/expenses/{expenseId}":{"get":{"tags":["expenses"],"summary":"Retrieve detailed expense information","description":"Get comprehensive details about a specific expense claim by its unique identifier.\n\nThis endpoint provides complete expense information including:\n- All expense line items with receipts\n- Approval status and workflow information\n- Available actions based on current state\n- Complete audit trail with timestamps\n\nUse this endpoint when you need full details about an expense, including receipt links and approval information that are not included in the list endpoint.\n","operationId":"getExpenseById","parameters":[{"name":"expenseId","in":"path","description":"Unique identifier of the expense","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Expense details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ExpensesExpenseIdGetResponse"},"example":{"expenseId":"550e8400-e29b-41d4-a716-446655440000","title":"Business Travel - Singapore","status":"APPROVED","totalAmount":1250.5,"currency":"USD","submittedAt":"2025-10-15T10:30:00Z","createdOn":"2025-10-14T08:00:00Z","updatedOn":"2025-10-16T14:20:00Z","employeeId":"123e4567-e89b-12d3-a456-426614174000","items":[{"itemId":"item-001","title":"Flight Ticket","amount":850.0,"date":"2025-10-10T00:00:00Z","category":{"id":"cat-001","name":"Travel"},"description":"Round trip flight to Singapore","receipts":[{"id":"receipt-001","name":"flight-ticket.pdf","link":"https://storage.example.com/receipts/flight-ticket.pdf"}]}],"approval":{"id":"approval-001"},"actionRules":[{"action":"APPROVE","allowed":true,"reason":null},{"action":"REJECT","allowed":true,"reason":null}]}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/timeoffs":{"get":{"tags":["Time Offs"],"summary":"List time off requests","description":"Search and list time off requests with pagination and filtering capabilities.\n\nThis endpoint allows you to:\n- Retrieve time off requests for specific employees\n- Filter by status (draft, pending approval, approved, etc.)\n- Filter by date ranges\n- Filter by time off types\n- Sort results by various fields\n- Paginate through large result sets\n","operationId":"listTimeOffs","parameters":[{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"style":"form","explode":true,"schema":{"minimum":1,"type":"integer","example":1,"default":1}},{"name":"pageSize","in":"query","description":"Number of items per page","required":false,"style":"form","explode":true,"schema":{"maximum":100,"minimum":1,"type":"integer","example":20,"default":20}},{"name":"employeeId","in":"query","description":"Filter time offs by employee ID (will be resolved to employment ID internally)","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},{"name":"status","in":"query","description":"Filter by time off status (can specify multiple)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["DRAFT","APPROVAL_IN_PROGRESS","APPROVED","REJECTED","TAKEN","DELETED","REVOKED"]}},"example":["APPROVED","TAKEN"]},{"name":"startDateFrom","in":"query","description":"Filter time offs starting from this date (inclusive)","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"date"},"example":"2025-10-01"},{"name":"startDateTo","in":"query","description":"Filter time offs starting before this date (inclusive)","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"date"},"example":"2025-12-31"},{"name":"typeId","in":"query","description":"Filter by time off type IDs (can specify multiple)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"example":["550e8400-e29b-41d4-a716-446655440001","550e8400-e29b-41d4-a716-446655440002"]},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"style":"form","explode":true,"schema":{"type":"string","default":"startDate","enum":["startDate","createdOn","updatedOn","noOfDays"]},"example":"startDate"},{"name":"sortOrder","in":"query","description":"Sort direction","required":false,"style":"form","explode":true,"schema":{"type":"string","default":"DESC","enum":["ASC","DESC"]},"example":"DESC"}],"responses":{"200":{"description":"Time off requests retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1TimeoffsGetResponse"},"example":{"timeOffs":[{"timeOffId":"660e8400-e29b-41d4-a716-446655440003","status":"APPROVED","startDate":{"date":"2025-11-15","session":"FULL_DAY"},"endDate":{"date":"2025-11-20","session":"FULL_DAY"},"noOfDays":6.0,"description":"Family vacation","type":{"typeId":"550e8400-e29b-41d4-a716-446655440001","key":"annual"},"createdOn":"2025-10-23T10:30:00Z","updatedOn":"2025-10-23T10:30:00Z"},{"timeOffId":"770e8400-e29b-41d4-a716-446655440004","status":"APPROVAL_IN_PROGRESS","startDate":{"date":"2025-12-01","session":"MORNING"},"endDate":{"date":"2025-12-01","session":"AFTERNOON"},"noOfDays":1.0,"description":"Medical appointment","type":{"typeId":"550e8400-e29b-41d4-a716-446655440002","key":"sick"},"createdOn":"2025-10-25T09:15:00Z","updatedOn":"2025-10-25T09:15:00Z"}],"page":{"pageNumber":1,"pageSize":20,"totalCount":2,"totalPages":1},"allCount":150,"pendingCount":10,"approvedCount":120}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/timeoffs/{timeOffId}":{"get":{"tags":["Time Offs"],"summary":"Retrieve time off details by ID","description":"Get detailed information about a specific time off request by its unique identifier.\n\nThis endpoint allows you to:\n- Retrieve complete details of a time off request\n- View the current status and approval state\n- Access time off dates, duration, and description\n- See time off type information\n","operationId":"getTimeOffById","parameters":[{"name":"timeOffId","in":"path","description":"Unique identifier of the time off request","required":true,"style":"simple","explode":false,"schema":{"type":"string"},"example":"TO-001"}],"responses":{"200":{"description":"Time off details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1TimeoffsTimeOffIdGetResponse"},"example":{"timeOffId":"660e8400-e29b-41d4-a716-446655440003","status":"APPROVED","startDate":{"date":"2025-11-15","session":"FULL_DAY"},"endDate":{"date":"2025-11-20","session":"FULL_DAY"},"noOfDays":6.0,"description":"Family vacation","type":{"typeId":"550e8400-e29b-41d4-a716-446655440001","key":"annual"},"createdOn":"2025-10-23T10:30:00Z","updatedOn":"2025-10-23T11:45:00Z"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/timesheets":{"get":{"tags":["Timesheet"],"summary":"List timesheets with filtering and pagination","description":"Search and retrieve a list of timesheets with comprehensive filtering options.\n\nThis endpoint allows you to:\n- List all timesheets for specific employees or companies\n- Filter by timesheet status (OPEN, SUBMITTED, APPROVED, REJECTED)\n- Filter by date ranges\n- Search by employee name\n- Sort results by various fields\n- Paginate through large result sets\n\nUse this endpoint to view timesheet history, find pending approvals, or generate reports.\n","operationId":"listTimesheets","parameters":[{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"style":"form","explode":true,"schema":{"minimum":1,"type":"integer","example":1,"default":1}},{"name":"pageSize","in":"query","description":"Number of items per page","required":false,"style":"form","explode":true,"schema":{"maximum":100,"minimum":1,"type":"integer","example":20,"default":20}},{"name":"employeeIds","in":"query","description":"Filter timesheets by employee IDs (employment IDs). Can specify multiple values.","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"example":["123e4567-e89b-12d3-a456-426614174000","123e4753-e89b-12d3-a456-426614174000"]},{"name":"status","in":"query","description":"Filter by timesheet status","required":false,"style":"form","explode":true,"schema":{"type":"string","enum":["OPEN","PARTIALLY_SUBMITTED","SUBMITTED","APPROVED","REJECTED"]},"example":"APPROVED"},{"name":"startDateFrom","in":"query","description":"Filter timesheets with start date from this date (inclusive)","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"date"},"example":"2025-10-01"},{"name":"startDateTo","in":"query","description":"Filter timesheets with start date up to this date (inclusive)","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"date"},"example":"2025-10-31"},{"name":"memberName","in":"query","description":"Filter timesheets by employee name (partial match, case-insensitive)","required":false,"style":"form","explode":true,"schema":{"maxLength":255,"minLength":1,"type":"string"},"example":"John"},{"name":"companyIds","in":"query","description":"Filter timesheets by company IDs. Can specify multiple values.","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"example":["company-001"]},{"name":"country","in":"query","description":"Filter timesheets by country code (ISO 3166-1 alpha-3)","required":false,"style":"form","explode":true,"schema":{"maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$","type":"string"},"example":"SGP"},{"name":"sortBy","in":"query","description":"Field to sort by","required":false,"style":"form","explode":true,"schema":{"type":"string","default":"startDate","enum":["startDate","endDate","updatedOn","submittedOn","approvedOn"]},"example":"startDate"},{"name":"sortOrder","in":"query","description":"Sort direction","required":false,"style":"form","explode":true,"schema":{"type":"string","default":"DESC","enum":["ASC","DESC"]},"example":"DESC"}],"responses":{"200":{"description":"Timesheets retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1TimesheetsGetResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/timesheets/{timesheetId}":{"get":{"tags":["Timesheet"],"summary":"Retrieve timesheet details by ID","description":"Get detailed information about a specific timesheet including all time entries.\n\nThis endpoint allows you to:\n- Retrieve complete timesheet information\n- View all daily time entries with work times and break times\n- Access time summary broken down by day type and hours type\n- See approval status and timestamps\n\nReturns comprehensive timesheet data including individual entries for each day,\nwork time periods, break time periods, overtime calculations, and approval information.\n","operationId":"getTimesheetById","parameters":[{"name":"timesheetId","in":"path","description":"Unique identifier of the timesheet","required":true,"style":"simple","explode":false,"schema":{"type":"string"},"example":"TS-001"},{"name":"employeeId","in":"query","description":"Employee ID (employment ID) - required for authorization and to identify which employment's timesheet to retrieve","required":true,"style":"form","explode":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Timesheet details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1TimesheetsTimesheetIdGetResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/partner/customers/{customerId}/departments":{"get":{"tags":["Customer Departments"],"summary":"List all departments","description":"Retrieve all departments for the authenticated company.\n","operationId":"listDepartments","parameters":[{"name":"customerId","in":"path","description":"Customer ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c"}],"responses":{"200":{"description":"Departments retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1DepartmentsGetResponse"},"example":{"data":[{"id":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c","code":"DEPT_99","name":"Global Sales","description":"Internal code: GS-001","createdAt":"2026-03-24T10:00:00Z"}]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}},"post":{"tags":["Customer Departments"],"summary":"Create a new department","description":"Create a new department for the authenticated company.\n\nReturns 201 with the full DepartmentItem on success.\n","operationId":"createDepartment","parameters":[{"name":"customerId","in":"path","description":"Customer ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1DepartmentsPostRequest"},"example":{"code":"DEPT_99","name":"Global Sales","description":"Internal code: GS-001"}}},"required":true},"responses":{"201":{"description":"Department created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentItem"},"example":{"id":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c","code":"DEPT_99","name":"Global Sales","description":"Internal code: GS-001","createdAt":"2026-03-24T10:00:00Z"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/partner/customers/{customerId}/departments/{departmentId}":{"patch":{"tags":["Customer Departments"],"summary":"Update a department","description":"Partially update a department by its ID.\n\nOnly supplied fields are updated. If field is not provided, the existing value is preserved.\n\nReturns `200` with the full `DepartmentItem` on success.\n","operationId":"updateDepartment","parameters":[{"name":"customerId","in":"path","description":"Customer ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c"},{"name":"departmentId","in":"path","description":"Department ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1DepartmentsPatchRequest"},"example":{"name":"New Department Name","code":"DEPT_99","description":"Updated description"}}},"required":true},"responses":{"200":{"description":"Department updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentItem"},"example":{"id":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c","code":"DEPT_99","name":"New Department Name","description":"Updated description","createdAt":"2026-03-24T10:00:00Z"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/customer-entities":{"get":{"tags":["Customer Entities"],"summary":"List all entities for a customer","description":"Retrieve all entities for the authenticated company.\n","operationId":"listCustomerEntities","responses":{"200":{"description":"Entities retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1EntitiesGetResponse"},"example":{"data":[{"id":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c","name":"Acme Corp Singapore"}]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}}}}},"/v1/partner/customers":{"get":{"tags":["Customers"],"summary":"List all customers","description":"Retrieves a paginated list of all customers associated with the partner.\n\nResults are returned in descending order by creation date (newest first).\n","operationId":"customersList","parameters":[{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"style":"form","explode":true,"schema":{"minimum":1,"type":"object","example":1,"default":1}},{"name":"pageSize","in":"query","description":"Number of items per page","required":false,"style":"form","explode":true,"schema":{"maximum":100,"minimum":1,"type":"object","example":20,"default":20}},{"name":"customerCode","in":"query","description":"Filter customers by exact customer code match","required":false,"style":"form","explode":true,"schema":{"type":"object","example":"CUST-12345"}}],"responses":{"200":{"description":"Customers retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_CustomerListResponse"},"examples":{"first_page":{"$ref":"#/components/examples/CustomerListResponseFirstPage"},"empty_list":{"$ref":"#/components/examples/CustomerListResponseEmpty"},"last_page":{"$ref":"#/components/examples/CustomerListResponseLastPage"}}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"examples":{"ValidationError":{"summary":"Validation error with field details","value":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Request validation failed","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"legalName","message":"Legal name must be at least 2 characters"},{"property":"admin.email","message":"Email address is not valid"}],"error":{"type":"ValidationError","code":"VALIDATION_FAILED","message":"Request validation failed","details":[{"field":"legalName","message":"Legal name must be at least 2 characters"},{"field":"admin.email","message":"Email address is not valid"}]}}}}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"Invalid or missing API key","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Invalid or missing API key"}],"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"Invalid or missing API key"}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An internal server error occurred","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An internal server error occurred"}],"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[{"BearerAuth":[]}]}},"/v1/partner/customers/{customerId}":{"get":{"tags":["Customers"],"summary":"Get customer details","description":"Retrieves detailed information about a specific customer.","operationId":"customerGet","parameters":[{"name":"customerId","in":"path","description":"Customer ID","required":true,"style":"simple","explode":false,"schema":{"type":"object","example":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6"}}],"responses":{"200":{"description":"Customer details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_CustomerResponse"},"examples":{"active":{"$ref":"#/components/examples/CustomerResponseActive"},"pending":{"$ref":"#/components/examples/CustomerResponsePending"},"minimal":{"$ref":"#/components/examples/CustomerResponseMinimal"}}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"Invalid or missing API key","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Invalid or missing API key"}],"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"Invalid or missing API key"}}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"Customer not found","path":"/v1/partner/customers/019a0ad5-75d5-78d7-ad93-0ebb55da0eb6","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Customer not found"}],"error":{"type":"NotFoundError","code":"RESOURCE_NOT_FOUND","message":"Customer not found"}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An internal server error occurred","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An internal server error occurred"}],"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}}}},"/v1/partner/customers/{customerId}/users":{"get":{"tags":["Customer Users"],"summary":"List all customer users","description":"Retrieves a paginated list of all users associated with the customer.\nResults are returned in descending order by creation date (newest first).\n","operationId":"customerUsersList","parameters":[{"name":"customerId","in":"path","description":"Customer ID","required":true,"style":"simple","explode":false,"schema":{"type":"object","example":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6"}},{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"style":"form","explode":true,"schema":{"minimum":1,"type":"object","example":1,"default":1}},{"name":"pageSize","in":"query","description":"Number of items per page","required":false,"style":"form","explode":true,"schema":{"maximum":100,"minimum":1,"type":"object","example":20,"default":20}}],"responses":{"200":{"description":"Customer users retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_CustomerUserListResponse"},"examples":{"first_page":{"$ref":"#/components/examples/CustomerUserListResponseFirstPage"},"empty_list":{"$ref":"#/components/examples/CustomerUserListResponseEmpty"},"last_page":{"$ref":"#/components/examples/CustomerUserListResponseLastPage"}}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"examples":{"ValidationError":{"summary":"Validation error with field details","value":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Request validation failed","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"legalName","message":"Legal name must be at least 2 characters"},{"property":"admin.email","message":"Email address is not valid"}],"error":{"type":"ValidationError","code":"VALIDATION_FAILED","message":"Request validation failed","details":[{"field":"legalName","message":"Legal name must be at least 2 characters"},{"field":"admin.email","message":"Email address is not valid"}]}}}}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"Invalid or missing API key","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Invalid or missing API key"}],"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"Invalid or missing API key"}}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"Customer not found","path":"/v1/partner/customers/019a0ad5-75d5-78d7-ad93-0ebb55da0eb6","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Customer not found"}],"error":{"type":"NotFoundError","code":"RESOURCE_NOT_FOUND","message":"Customer not found"}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An internal server error occurred","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An internal server error occurred"}],"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[{"BearerAuth":[]}]},"post":{"tags":["Customer Users"],"summary":"Create a customer user","description":"Creates a new user account for a customer.\n\nThis endpoint provisions a user account with the specified role and associates it with the customer.\n\n**Security:**\n- Requires valid partner access token (Bearer token)\n\n**Validation:**\n- Email must be a valid email address\n- First name and last name are required\n- Role must be a valid CustomerUserRole enum value\n","operationId":"customerUserCreate","parameters":[{"name":"customerId","in":"path","description":"Customer ID","required":true,"style":"simple","explode":false,"schema":{"type":"object","example":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6"}}],"requestBody":{"description":"Customer user creation details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_CustomerUserCreateRequest"},"examples":{"admin":{"$ref":"#/components/examples/CustomerUserCreateRequestAdmin"}}}},"required":true},"responses":{"201":{"description":"Customer user created successfully","headers":{"Location":{"description":"URL to the created customer user resource","style":"simple","explode":false,"schema":{"type":"object","format":"uri","example":"https://api.usemultiplier.com/v1/partner/{partnerId}/customers/{id}/users/018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_CustomerUserResponse"},"examples":{"admin":{"$ref":"#/components/examples/CustomerUserResponseAdmin"}}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"examples":{"ValidationError":{"summary":"Validation error with field details","value":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Request validation failed","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"legalName","message":"Legal name must be at least 2 characters"},{"property":"admin.email","message":"Email address is not valid"}],"error":{"type":"ValidationError","code":"VALIDATION_FAILED","message":"Request validation failed","details":[{"field":"legalName","message":"Legal name must be at least 2 characters"},{"field":"admin.email","message":"Email address is not valid"}]}}}}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"Invalid or missing API key","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Invalid or missing API key"}],"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"Invalid or missing API key"}}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"Customer not found","path":"/v1/partner/customers/019a0ad5-75d5-78d7-ad93-0ebb55da0eb6","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Customer not found"}],"error":{"type":"NotFoundError","code":"RESOURCE_NOT_FOUND","message":"Customer not found"}}}}},"409":{"description":"Conflict - Resource already exists or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"CONFLICT","message":"A customer with this registration number already exists","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A customer with this registration number already exists"}],"error":{"type":"ConflictError","code":"RESOURCE_ALREADY_EXISTS","message":"A customer with this registration number already exists"}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An internal server error occurred","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An internal server error occurred"}],"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[{"BearerAuth":[]}]}},"/v1/partner/customers/{customerId}/users/{userId}":{"get":{"tags":["Customer Users"],"summary":"Get customer user details","description":"Retrieves detailed information about a specific customer user.\n\n**Security:**\n- Requires valid partner access token (Bearer token)\n","operationId":"customerUserGet","parameters":[{"name":"customerId","in":"path","description":"Customer ID","required":true,"style":"simple","explode":false,"schema":{"type":"object","example":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6"}},{"name":"userId","in":"path","description":"Customer User ID","required":true,"style":"simple","explode":false,"schema":{"type":"object","example":"018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f"}}],"responses":{"200":{"description":"Customer user details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_CustomerUserResponse"},"examples":{"admin":{"$ref":"#/components/examples/CustomerUserResponseAdmin"}}}}},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"Invalid or missing API key","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Invalid or missing API key"}],"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"Invalid or missing API key"}}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"Customer not found","path":"/v1/partner/customers/019a0ad5-75d5-78d7-ad93-0ebb55da0eb6","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Customer not found"}],"error":{"type":"NotFoundError","code":"RESOURCE_NOT_FOUND","message":"Customer not found"}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An internal server error occurred","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An internal server error occurred"}],"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[{"BearerAuth":[]}]},"delete":{"tags":["Customer Users"],"summary":"Delete a customer user","description":"Deletes a customer user account.\n\nThis operation removes the user's association with the customer.\n\n**Security:**\n- Requires valid partner access token (Bearer token)\n","operationId":"customerUserDelete","parameters":[{"name":"customerId","in":"path","description":"Customer ID","required":true,"style":"simple","explode":false,"schema":{"type":"object","example":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6"}},{"name":"userId","in":"path","description":"Customer User ID","required":true,"style":"simple","explode":false,"schema":{"type":"object","example":"018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f"}}],"responses":{"204":{"description":"Customer user deleted successfully"},"401":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"Invalid or missing API key","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Invalid or missing API key"}],"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"Invalid or missing API key"}}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"Customer not found","path":"/v1/partner/customers/019a0ad5-75d5-78d7-ad93-0ebb55da0eb6","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Customer not found"}],"error":{"type":"NotFoundError","code":"RESOURCE_NOT_FOUND","message":"Customer not found"}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An internal server error occurred","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An internal server error occurred"}],"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[{"BearerAuth":[]}]}},"/v1/partner/.well-known/jwks.json":{"get":{"tags":["JWKS Controller"],"summary":"Get JWKS public keys","description":"Returns the JSON Web Key Set (JWKS) containing all public keys used to verify JWTs\nissued by the Strategic Partner service (e.g. webhook signatures).\n\nThis endpoint follows the standard JWKS format defined in RFC 7517.\n\n**Security:**\n- This is an UNAUTHENTICATED public endpoint (standard for JWKS discovery)\n- Only public keys are exposed; private keys are never returned\n","operationId":"getJwks","responses":{"200":{"description":"JWKS retrieved successfully","content":{"application/json":{"schema":{"required":["keys"],"type":"object","properties":{"keys":{"type":"object","description":"Array of JSON Web Keys","items":{"required":["alg","crv","kid","kty","x","y"],"type":"object","properties":{"kty":{"type":"object","description":"Key type — always \"EC\" for elliptic curve keys","example":"EC"},"crv":{"type":"object","description":"Elliptic curve name","example":"P-521"},"kid":{"type":"object","description":"Key ID used to identify this key","example":"key-M6_su2ox"},"x":{"type":"object","description":"Base64url-encoded x coordinate of the EC public key","example":"AaW67emtYjW6ECOJpkgYc-L9-eWV9BIPPUsYSqGk0sAkPaZtNH7Tsp0GXlqrjLmFrZyS6HAshuAz9jARpZM6LOED"},"y":{"type":"object","description":"Base64url-encoded y coordinate of the EC public key","example":"AZH2VyMkqQKR6KHksoYarvAr-kVDWSR5GQ3BAPEne4pcIoLby9Eps1vnfR0kFXddDtHtFzGxVhUZc9oysLfUN5P2"},"alg":{"type":"object","description":"Algorithm associated with the key","example":"ES512"}},"description":"An EC JSON Web Key (RFC 7517 / RFC 7518)"}}},"description":"JSON Web Key Set (RFC 7517)"},"examples":{"jwks_response":{"summary":"Example JWKS response","value":{"keys":[{"kty":"EC","crv":"P-521","kid":"key-M6_su2ox","x":"AaW67emtYjW6ECOJpkgYc-L9-eWV9BIPPUsYSqGk0sAkPaZtNH7Tsp0GXlqrjLmFrZyS6HAshuAz9jARpZM6LOED","y":"AZH2VyMkqQKR6KHksoYarvAr-kVDWSR5GQ3BAPEne4pcIoLby9Eps1vnfR0kFXddDtHtFzGxVhUZc9oysLfUN5P2","alg":"ES512"}]}}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategicPartner_ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An internal server error occurred","path":"/v1/partner/customers","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An internal server error occurred"}],"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[]}},"/v1/client/token":{"post":{"tags":["Partner Token"],"summary":"OAuth 2.0 Token Endpoint","description":"Implements RFC 6749 Section 4.4.2 - Access Token Request using Client Credentials flow.\n\nThis endpoint accepts both JSON and form-urlencoded content types.\n\n**Security considerations:**\n- Uses HTTPS in production (enforced by infrastructure)\n- Validates client credentials using Argon2 password hashing\n- Generates cryptographically secure opaque tokens\n\n**Grant Type:**\n- Only `client_credentials` grant type is supported\n\n**Authentication:**\n- This endpoint does NOT require a bearer token\n- Authentication is performed using client_id and client_secret in the request body\n","operationId":"oauthToken","requestBody":{"description":"OAuth 2.0 token request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientAuth_client_token_body"},"examples":{"client_credentials":{"summary":"Client credentials grant","value":{"grant_type":"client_credentials","client_id":"partner_abc123","client_secret":"secret_xyz789"}}}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ClientAuth_client_token_body_1"},"examples":{"client_credentials":{"summary":"Client credentials grant (form-encoded)","value":"grant_type=client_credentials&client_id=partner_abc123&client_secret=secret_xyz789"}}}},"required":true},"responses":{"200":{"description":"Token issued successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientAuth_inline_response_200"},"examples":{"success":{"summary":"Successful token response","value":{"access_token":"tok_abc123def456ghi789jkl012mno345pqrst","token_type":"Bearer","expires_in":3600}}}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientAuth_inline_response_400"},"examples":{"ValidationError":{"summary":"Validation error with field details","value":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Request validation failed","path":"/v1/client/token","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"client_id","message":"Client ID must not be blank"}],"error":{"type":"ValidationError","code":"VALIDATION_FAILED","message":"Request validation failed","details":[{"field":"client_id","message":"Client ID must not be blank"}]}}}}}}},"401":{"description":"Invalid client credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientAuth_inline_response_400"},"examples":{"invalid_client":{"summary":"Invalid client credentials","value":{"error":"invalid_client","error_description":"Client authentication failed"}}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientAuth_inline_response_400"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred. Please contact support.","path":"/v1/client/token","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred. Please contact support."}],"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[]}},"/authenticate/partner/token-exchange":{"post":{"tags":["OAuth"],"summary":"OAuth 2.0 Token Exchange","description":"Implements RFC 8693 (OAuth 2.0 Token Exchange) with extensions.\n\nValidates a partner access token and exchanges it for a JWT token. This implementation uses the requested_subject field (common extension to RFC 8693) to specify the platform user ID for whom the token is being requested.\n\n**Security considerations:**\n- Uses HTTPS in production (enforced by infrastructure)\n- Validates partner access token\n- Generates cryptographically secure JWT tokens\n\n**Grant Type:**\n- Only `urn:ietf:params:oauth:grant-type:token-exchange` grant type is supported\n\n**Authentication:**\n- This endpoint does NOT require a bearer token\n- Authentication is performed using the subject_token in the request body\n","operationId":"tokenExchange","requestBody":{"description":"OAuth 2.0 token exchange request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_partner_tokenexchange_body"},"examples":{"token_exchange":{"summary":"Token exchange request","value":{"grant_type":"urn:ietf:params:oauth:grant-type:token-exchange","subject_token":"partner_access_token_abc123","subject_token_type":"urn:ietf:params:oauth:token-type:access_token","requested_subject":"user_id_xyz789"}}}}},"required":true},"responses":{"200":{"description":"Token exchanged successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_200"},"examples":{"success":{"summary":"Successful token exchange","value":{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","token_type":"Bearer","expires_in":3600,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.refresh..."}}}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"examples":{"ValidationError":{"summary":"Validation error with field details","value":{"error":{"type":"ValidationError","code":"VALIDATION_FAILED","message":"Request validation failed","details":[{"field":"legalName","message":"Legal name must be at least 2 characters"},{"field":"admin.email","message":"Email address is not valid"}]}}}}}}},"401":{"description":"Invalid partner token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"examples":{"invalid_token":{"summary":"Invalid partner token","value":{"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"The provided partner token is invalid or expired"}}}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"example":{"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[]}},"/authenticate/partner/request-authcode":{"post":{"tags":["Magic Links"],"summary":"Generate Authorization Code","description":"Generates an authorization code for a strategic partner customer user.\n\nExtracts partner ID from the JWT token in the Authorization header,\nlooks up the platform user ID, and generates a short-lived auth code.\n\n**Security considerations:**\n- Requires valid Bearer token in Authorization header\n- Auth code is short-lived (typically 60 seconds)\n- Auth code can only be used once\n\n**Authentication:**\n- Requires Bearer token in Authorization header\n","operationId":"requestAuthCode","parameters":[{"name":"Authorization","in":"header","description":"Bearer token for partner authentication","required":true,"style":"simple","explode":false,"schema":{"type":"object","example":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}],"requestBody":{"description":"Auth code generation request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_partner_requestauthcode_body"},"examples":{"request":{"summary":"Auth code request","value":{"customerUserId":"user_id_xyz789"}}}}},"required":true},"responses":{"200":{"description":"Auth code generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_200_1"},"examples":{"success":{"summary":"Successful auth code generation","value":{"auth_code":"abc123def456","expires_in":60}}}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"examples":{"ValidationError":{"summary":"Validation error with field details","value":{"error":{"type":"ValidationError","code":"VALIDATION_FAILED","message":"Request validation failed","details":[{"field":"legalName","message":"Legal name must be at least 2 characters"},{"field":"admin.email","message":"Email address is not valid"}]}}}}}}},"401":{"description":"Invalid or missing authorization token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"Invalid or missing Authorization header"}}}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"example":{"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[{"bearerAuth":[]}]}},"/authenticate/partner/request-customer-authcode":{"post":{"tags":["Magic Links"],"summary":"Generate Authorization Code for Customer User","description":"Generates an authorization code for a customer user using a platform JWT token.\n\nThis endpoint extracts the platform user ID directly from the JWT token's claims\n(details.id field) and generates a short-lived auth code.\n\nUnlike /authenticate/partner/request-authcode, this endpoint:\n- Does NOT require a customerUserId in the request body\n- Accepts only platform JWT tokens (not client auth tokens)\n- Extracts platformUserId from the JWT token's \"details.id\" claim\n\n**Security considerations:**\n- Requires valid Bearer token (platform JWT) in Authorization header\n- Auth code is short-lived (typically 60 seconds)\n- Auth code can only be used once\n\n**Authentication:**\n- Requires Bearer token (platform JWT) in Authorization header\n","operationId":"requestCustomerAuthCode","parameters":[{"name":"Authorization","in":"header","description":"Bearer token (platform JWT) for authentication","required":true,"style":"simple","explode":false,"schema":{"type":"object","example":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}],"responses":{"200":{"description":"Auth code generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_200_1"},"examples":{"success":{"summary":"Successful auth code generation","value":{"auth_code":"abc123def456","expires_in":60}}}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"examples":{"ValidationError":{"summary":"Validation error with field details","value":{"error":{"type":"ValidationError","code":"VALIDATION_FAILED","message":"Request validation failed","details":[{"field":"legalName","message":"Legal name must be at least 2 characters"},{"field":"admin.email","message":"Email address is not valid"}]}}}}}}},"401":{"description":"Invalid or missing authorization token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"Invalid or missing Authorization header"}}}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"example":{"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[{"bearerAuth":[]}]}},"/authenticate/partner/authcode":{"post":{"tags":["Magic Links"],"summary":"OAuth 2.0 Authorization Code Exchange","description":"Implements RFC 6749 Section 4.1.3 - Authorization Code Grant.\n\nExchanges an authorization code for access and refresh tokens.\n\n**Security considerations:**\n- Uses HTTPS in production (enforced by infrastructure)\n- Auth code is single-use and short-lived\n- Validates client_id\n\n**Grant Type:**\n- Only `authorization_code` grant type is supported\n\n**Authentication:**\n- This endpoint does NOT require a bearer token\n- Authentication is performed using the authorization code\n","operationId":"exchangeAuthCode","parameters":[{"name":"platform","in":"header","description":"Optional platform type for refresh token cookie","required":false,"style":"simple","explode":false,"schema":{"type":"object","example":"web","enum":["web","mobile"]}}],"requestBody":{"description":"OAuth 2.0 authorization code exchange request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_partner_authcode_body"},"examples":{"json_request":{"summary":"JSON authorization code request","value":{"grant_type":"authorization_code","code":"abc123def456","client_id":"strategic-partner-app"}}}}},"required":true},"responses":{"200":{"description":"Tokens issued successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_200"},"examples":{"success":{"summary":"Successful token response","value":{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","token_type":"Bearer","expires_in":3600}}}}}},"400":{"description":"Bad Request - Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"examples":{"ValidationError":{"summary":"Validation error with field details","value":{"error":{"type":"ValidationError","code":"VALIDATION_FAILED","message":"Request validation failed","details":[{"field":"legalName","message":"Legal name must be at least 2 characters"},{"field":"admin.email","message":"Email address is not valid"}]}}}}}}},"401":{"description":"Invalid authorization code or client credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"examples":{"invalid_grant":{"summary":"Invalid authorization code","value":{"error":{"type":"AuthenticationError","code":"AUTHENTICATION_FAILED","message":"The authorization code is invalid or expired"}}}}}}},"500":{"description":"Internal Server Error - Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserService_inline_response_400"},"example":{"error":{"type":"ServerError","code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please contact support."}}}}}},"security":[]}}},"components":{"schemas":{"ErrorResponse":{"required":["code","correlationId","message","path","timestamp"],"type":"object","properties":{"timestamp":{"type":"string","description":"ISO-8601 UTC timestamp of when the error occurred","format":"date-time","example":"2026-03-19T10:15:30Z"},"code":{"type":"string","description":"Machine-readable error category","example":"BAD_REQUEST","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","CONFLICT","VALIDATION_ERROR","SERVICE_UNAVAILABLE","INTERNAL_SERVER_ERROR"]},"message":{"type":"string","description":"Human-readable description of the error","example":"The requested resource could not be found"},"path":{"type":"string","description":"Request URI that produced the error","example":"/v1/employees"},"correlationId":{"type":"string","description":"Trace ID for correlating this error in logs","example":"4bf92f3577b34da6a3ce929d0e0e4736"},"errors":{"type":"array","description":"Field-level error details. Present for validation errors; may be present for other errors.","items":{"$ref":"#/components/schemas/ErrorItem"}},"error":{"description":"Deprecated: Use errors instead. Backward-compatible error object.","nullable":true,"deprecated":true,"allOf":[{"$ref":"#/components/schemas/LegacyError"}]}}},"V1EmployeesGetResponse":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","description":"List of employees matching the search criteria","example":[{"id":"123e4567-e89b-12d3-a456-426614174000","employeeCode":"EMP-12345","employeeId":"EMP-12345","firstName":"John","middleName":"Michael","lastName":"Doe","fullName":"John Michael Doe","displayName":"John Doe","workEmail":"john.doe@company.com","designation":"Senior Software Engineer","department":"Engineering","status":"ACTIVE","type":"EMPLOYEE","startDate":"2023-01-15","endDate":null,"country":"USA","customerId":"550e8400-e29b-41d4-a716-446655440000","customerName":"Tech Corp Inc","entity":"Tech Corp Singapore Pte Ltd"}],"items":{"$ref":"#/components/schemas/EmployeeData"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"EmployeeData":{"required":["country","customerId","customerName","designation","displayName","firstName","fullName","id","lastName","startDate","status","type"],"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the employee","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"employeeCode":{"type":"string","description":"Human-readable employee code (optional)","nullable":true,"example":"EMP-12345"},"employeeId":{"type":"string","description":"Deprecated: Use employeeCode instead. Human-readable employee code (optional)","nullable":true,"example":"EMP-12345","deprecated":true},"firstName":{"type":"string","description":"Employee's first name","example":"John"},"middleName":{"type":"string","description":"Employee's middle name","nullable":true,"example":"Michael"},"lastName":{"type":"string","description":"Employee's last name","example":"Doe"},"fullName":{"type":"string","description":"Employee's full legal name","example":"John Michael Doe"},"displayName":{"type":"string","description":"Display name for the employee","example":"John Doe"},"workEmail":{"type":"string","description":"Employee's work email address","format":"email","nullable":true,"example":"john.doe@company.com"},"designation":{"type":"string","description":"Job title/position","example":"Senior Software Engineer"},"department":{"type":"string","description":"Department name","nullable":true,"example":"Engineering"},"status":{"type":"string","description":"Current employment status","example":"ACTIVE","enum":["ONBOARDING","ACTIVE","OFFBOARDING","ENDED","DELETED","UNKNOWN"]},"type":{"type":"string","description":"Type of employment","example":"EMPLOYEE","enum":["EMPLOYEE","CONTRACTOR","FREELANCER","HR_MEMBER","UNKNOWN"]},"startDate":{"type":"string","description":"Employment start date (ISO 8601 format YYYY-MM-DD)","format":"date","example":"2023-01-15"},"endDate":{"type":"string","description":"Employment end date (ISO 8601 format YYYY-MM-DD)","format":"date","nullable":true,"example":"2024-12-31"},"country":{"pattern":"^[A-Z]{3}$","type":"string","description":"ISO 3166-1 alpha-3 country code for work location","example":"USA"},"customerId":{"type":"string","description":"ID of the company this employee belongs to","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"customerName":{"type":"string","description":"Name of the company","example":"Tech Corp Inc"},"entity":{"type":"string","description":"Legal entity name for the employee's employment","nullable":true,"example":"Tech Corp Singapore Pte Ltd"}}},"OnboardingTrackerItem":{"required":["id","stage"],"type":"object","properties":{"id":{"type":"string","description":"Contract public ID (UUID)","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"employeeCode":{"type":"string","description":"Human-readable employee code","nullable":true,"example":"EMP-12345"},"stage":{"$ref":"#/components/schemas/OnboardingTrackerStage"}}},"OnboardingTrackerStage":{"type":"string","description":"- DRAFT: Contract is being drafted / defined\n- CONTRACT_SENT: Contract sent for signature\n- CONTRACT_SIGNED: All parties have signed\n- EMPLOYEE_INVITED: Employee invited to the platform\n- EMPLOYEE_DETAILS_IN_PROGRESS: Employee filling in their details\n- VERIFICATION: KYC / identity verification in progress\n- PAYROLL_SETUP: Payroll being configured\n","example":"VERIFICATION","enum":["DRAFT","CONTRACT_SENT","CONTRACT_SIGNED","EMPLOYEE_INVITED","EMPLOYEE_DETAILS_IN_PROGRESS","VERIFICATION","PAYROLL_SETUP"]},"OffboardingTrackerItem":{"required":["id","stage"],"type":"object","properties":{"id":{"type":"string","description":"Contract public ID (UUID)","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"employeeCode":{"type":"string","description":"Human-readable employee code","nullable":true,"example":"EMP-12345"},"stage":{"$ref":"#/components/schemas/OffboardingTrackerStage"},"pendingDocuments":{"type":"array","description":"List of pending documents when stage is DOCUMENTS_PENDING","nullable":true,"items":{"$ref":"#/components/schemas/OffboardingPendingDocument"}}}},"OffboardingTrackerStage":{"type":"string","description":"- OFFBOARDING_INITIATED: Offboarding process has started\n- DOCUMENTS_PENDING: Waiting for required documents\n- SETTLEMENT_PENDING: Waiting for final settlement\n- SETTLEMENT_COMPLETE: Final settlement completed\n","example":"DOCUMENTS_PENDING","enum":["OFFBOARDING_INITIATED","DOCUMENTS_PENDING","SETTLEMENT_PENDING","SETTLEMENT_COMPLETE"]},"OffboardingPendingDocument":{"type":"string","description":"Type of pending document blocking the offboarding process","example":"WET_INK_LETTER","enum":["SHORTFALL_PAY_DETAILS","WET_INK_LETTER","RESIGNATION_LETTER","GOVT_PORTAL_PROOF"]},"V1GetEmployeeDynamicDetailsSchemaResponse":{"required":["customFields","legalDetails"],"type":"object","properties":{"legalDetails":{"$ref":"#/components/schemas/EmployeeSchemaSection"},"customFields":{"$ref":"#/components/schemas/EmployeeSchemaSection"}}},"EmployeeSchemaSection":{"required":["fields","required"],"type":"object","properties":{"required":{"type":"boolean","description":"Whether the section is required"},"fields":{"type":"array","description":"List of fields in the section","items":{"$ref":"#/components/schemas/FieldDefinition"}}},"example":{"required":true,"fields":[{"key":"field1","label":"Field 1","type":"TEXT","required":true},{"key":"field2","label":"Field 2","type":"NUMBER","required":false},{"key":"field3","label":"Field 3","type":"DATE","required":true,"minDate":"2025-01-01","maxDate":"2025-12-31"},{"key":"field4","label":"Field 4","type":"SELECT","required":true,"options":["option1","option2"],"multiSelect":false},{"key":"field5","label":"Field 5","type":"OBJECT","required":false,"fields":[{"key":"field5a","label":"Field 5a","type":"TEXT","required":true},{"key":"field5b","label":"Field 5b","type":"NUMBER","required":false}]},{"key":"field6","label":"Field 6","type":"ARRAY","required":true,"minItems":1,"maxItems":3,"item":{"key":"field6a","label":"Field 6a","type":"TEXT","required":true}}]}},"V1SubmitEmployeesDynamicDetailsRequest":{"type":"object","properties":{"legalDetails":{"type":"object","additionalProperties":{"type":"string"},"description":"Flat key-value map of legal detail field values as defined by the schema.\nKeys correspond to `key` fields returned in `legalDetails.fields` from `GET /v1/employees/schema`.\n","example":{"nationalId":"S1234567A","taxId":"123456789"}},"customFields":{"type":"object","additionalProperties":{"type":"string"},"description":"Flat key-value map of custom field values as defined by the schema.\nKeys correspond to `key` fields returned in `customFields.fields` from `GET /v1/employees/schema`.\n","example":{"costCenter":"CC-001","projectCode":"PROJ-42"}}}},"EmploymentType":{"type":"string","description":"Type of employment context","example":"GLOBAL_PAYROLL","enum":["GLOBAL_PAYROLL"]},"V1GpEmploymentsPostRequest":{"required":["compensation","contact","employment","personal"],"type":"object","properties":{"personal":{"$ref":"#/components/schemas/V1GpEmploymentsPersonalInput"},"contact":{"$ref":"#/components/schemas/V1GpEmploymentsContactInput"},"employment":{"$ref":"#/components/schemas/V1GpEmploymentsEmploymentInput"},"compensation":{"$ref":"#/components/schemas/V1GpEmploymentsCompensationInput"},"address":{"$ref":"#/components/schemas/V1GpEmploymentsAddressInput"}}},"V1GpEmploymentsPersonalInput":{"required":["dateOfBirth","firstName","fullLegalName","gender","lastName"],"type":"object","properties":{"firstName":{"type":"string","description":"Employee's first name","example":"Foo"},"middleName":{"type":"string","description":"Employee's middle name (optional)","nullable":true,"example":null},"lastName":{"type":"string","description":"Employee's last name","example":"Bar"},"fullLegalName":{"type":"string","description":"Employee's full legal name","example":"Foo Bar"},"nameInNativeLanguage":{"type":"string","description":"Employee's name in native language","example":null},"dateOfBirth":{"type":"string","description":"Employee's date of birth (YYYY-MM-DD)","format":"date","example":"2000-10-11"},"gender":{"type":"string","description":"Employee's gender","example":"MALE","enum":["FEMALE","MALE","UNSPECIFIED"]},"maritalStatus":{"type":"string","description":"Employee's marital status","example":"SINGLE","enum":["DIVORCED","MARRIED","SINGLE","UNSPECIFIED"]},"religion":{"type":"string","description":"Employee's religion (optional)","nullable":true,"example":"Sikh"},"nationality":{"pattern":"^[A-Z]{3}$","type":"string","description":"Employee's nationality. ISO 3166-1 alpha-3 country code"}}},"V1GpEmploymentsContactInput":{"required":["personalEmail"],"type":"object","properties":{"personalEmail":{"type":"string","description":"Employee's personal email address","format":"email","example":"foo.bar@personal.com"},"personalPhoneNumber":{"pattern":"^\\+[1-9]\\d{1,14}$","type":"string","description":"Employee's personal phone number","example":"+41791234567"},"emergencyContact":{"required":["name","phoneNumber","relationship"],"type":"object","properties":{"name":{"type":"string","description":"Name of the emergency contact person"},"phoneNumber":{"pattern":"^\\+[1-9]\\d{1,14}$","type":"string","description":"Phone number of the emergency contact"},"relationship":{"type":"string","description":"Relationship to the employee","enum":["SPOUSE","DAUGHTER","SON","FATHER","MOTHER"]}},"description":"Emergency contact information","nullable":true}}},"V1GpEmploymentsEmploymentInput":{"required":["department","designation","employeeCode","entity","startDate","term"],"type":"object","properties":{"employeeCode":{"type":"string","description":"Human-readable employee code","example":"EMP-12345"},"entity":{"type":"string","description":"Legal entity name for the employee's employment","example":"Tech Corp Singapore Pte Ltd"},"workEmail":{"type":"string","description":"Employee's work email address","format":"email","example":"foo.bar@company.com"},"startDate":{"type":"string","description":"Date when employee joined the company (YYYY-MM-DD)","format":"date","example":"2023-01-15"},"term":{"type":"string","description":"Employment term (fixed-term or permanent)","example":"PERMANENT","enum":["FIXED","PERMANENT"]},"endDate":{"type":"string","description":"Date when employee left or will leave the company (optional)","format":"date","nullable":true,"example":null},"designation":{"type":"string","description":"Job title or position","example":"Software Engineer"},"department":{"type":"string","description":"Department name","example":"Engineering"},"reportsTo":{"type":"string","description":"Work email of the manager/supervisor","format":"email","example":"jane.smith@company.com"}}},"V1GpEmploymentsAddressInput":{"type":"object","properties":{"addressLine1":{"maxLength":200,"minLength":1,"type":"string","description":"Address line 1 (street address)","example":"123 Main Street"},"addressLine2":{"maxLength":200,"type":"string","description":"Address line 2 (apartment, suite, etc.) - optional","nullable":true,"example":"Apartment 4B"},"streetName":{"maxLength":200,"type":"string","description":"Street name (optional)","nullable":true,"example":"Main Street"},"city":{"maxLength":100,"minLength":1,"type":"string","description":"City name","example":"Zurich"},"subdivision":{"maxLength":100,"type":"string","description":"State, province, or canton (optional)","nullable":true,"example":"Zurich"},"country":{"pattern":"^[A-Z]{3}$","type":"string","description":"Country (ISO 3166-1 alpha-3 code)","example":"CHE"},"postalCode":{"maxLength":20,"minLength":1,"type":"string","description":"Postal or ZIP code","example":"8001"}}},"V1GpEmploymentsCompensationInput":{"required":["baseSalary"],"type":"object","properties":{"baseSalary":{"$ref":"#/components/schemas/V2CompensationComponent"},"additionalPays":{"type":"array","items":{"$ref":"#/components/schemas/V2CompensationComponent"}}}},"V2CompensationComponent":{"required":["billingRate","billingRateType","currency","frequency","name","payScheduleName","startDate"],"type":"object","properties":{"name":{"type":"string","description":"Name of the compensation component"},"billingRate":{"type":"number","description":"Amount/rate of the compensation component"},"billingRateType":{"type":"string","description":"Rate type of the compensation component.","enum":["VALUE","PERC_BASE_PAY","BASE_PAY_DAYS","CTC_DAYS","CTC_PERCENTAGE","EARNINGS_PERCENTAGE","BASIC_SALARY_PERCENTAGE","QUALIFYING_EARNINGS_PERCENTAGE"]},"currency":{"pattern":"^[A-Z]{3}$","type":"string","description":"ISO 4217 currency code"},"frequency":{"type":"string","description":"Payment frequency","enum":["WEEKLY","SEMIMONTHLY","BIWEEKLY","MONTHLY","ANNUALLY","SEMIANNUALLY","QUARTERLY","DAILY","ONETIME","HOURLY"]},"payScheduleName":{"type":"string","description":"Pay schedule name of the compensation component"},"startDate":{"type":"string","description":"Start date of the compensation component. YYYY-MM-DD","format":"date","example":"2025-01-01"},"endDate":{"type":"string","description":"End date of the compensation component. YYYY-MM-DD","format":"date","nullable":true,"example":"2025-12-31"},"isInstallment":{"type":"boolean","description":"Whether the compensation component is an installment. Defaults to false.","nullable":true},"numberOfInstallments":{"minimum":1,"type":"integer","description":"Number of installments.","nullable":true},"notes":{"type":"string","description":"Notes for the compensation component","nullable":true}}},"V1GpEmploymentsPostResponse":{"required":["id"],"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the employee","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"}}},"V1EmployeesEmployeeIdPersonalGetResponse":{"type":"object","properties":{"firstName":{"type":"string","description":"Employee's first name","example":"Foo"},"middleName":{"type":"string","description":"Employee's middle name (optional)","nullable":true,"example":null},"lastName":{"type":"string","description":"Employee's last name","example":"Bar"},"fullLegalName":{"type":"string","description":"Employee's full legal name","example":"Foo Bar"},"dateOfBirth":{"type":"string","description":"Employee's date of birth (YYYY-MM-DD)","format":"date","example":"2000-10-11"},"gender":{"type":"string","description":"Employee's gender","example":"MALE","enum":["FEMALE","MALE","UNSPECIFIED","UNKNOWN"]},"maritalStatus":{"type":"string","description":"Employee's marital status","example":"SINGLE","enum":["DIVORCED","MARRIED","SINGLE","UNSPECIFIED","WIDOWED","SEPARATED","UNKNOWN"]},"age":{"type":"integer","description":"Employee's age (computed from date of birth)","example":25},"religion":{"type":"string","description":"Employee's religion (optional)","nullable":true,"example":"Sikh"},"nationalities":{"type":"array","description":"List of nationalities associated with the employee","items":{"required":["country","type"],"type":"object","properties":{"country":{"pattern":"^[A-Z]{3}$","type":"string","description":"ISO 3166-1 alpha-3 country code (e.g., 'CHE')","example":"CHE"},"type":{"type":"string","description":"Type of nationality or residency status","example":"CITIZEN","enum":["CITIZEN","PERMANENT_RESIDENT","TEMPORARY_RESIDENT","UNKNOWN"]}}}}}},"EmployeeContact":{"type":"object","properties":{"personalEmail":{"type":"string","description":"Employee's personal email address","format":"email","example":"foo.bar@personal.com"},"personalPhoneNumber":{"pattern":"^\\+[1-9]\\d{1,14}$","type":"string","description":"Employee's personal phone number (optional)","nullable":true,"example":"+41791234567"},"emergencyContact":{"type":"object","properties":{"name":{"maxLength":200,"minLength":1,"type":"string","description":"Name of the emergency contact person","example":"Jane Doe"},"phoneNumber":{"pattern":"^\\+[1-9]\\d{1,14}$","type":"string","description":"Phone number of the emergency contact","example":"+41791234568"},"relationship":{"type":"string","description":"Relationship to the employee","example":"SPOUSE","enum":["SPOUSE","DAUGHTER","SON","FATHER","MOTHER","UNKNOWN"]}},"description":"Emergency contact information","nullable":true}}},"V1EmployeesEmployeeIdContactGetResponse":{"$ref":"#/components/schemas/EmployeeContact"},"V1EmployeesEmployeeIdAddressGetResponse":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdAddressDetails"},"V1EmployeesEmployeeIdAddressDetails":{"type":"object","properties":{"currentAddress":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdAddressAddress"},"permanentAddress":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdAddressAddress"}}},"V1EmployeesEmployeeIdAddressAddress":{"type":"object","properties":{"addressLine1":{"maxLength":200,"minLength":1,"type":"string","description":"Address line 1 (street address)","example":"123 Main Street"},"addressLine2":{"maxLength":200,"type":"string","description":"Address line 2 (apartment, suite, etc.) - optional","nullable":true,"example":"Apartment 4B"},"streetName":{"maxLength":200,"type":"string","description":"Street name (optional)","nullable":true,"example":"Main Street"},"landmark":{"maxLength":200,"type":"string","description":"Nearby landmark for easier location (optional)","nullable":true,"example":"Near Central Park"},"city":{"maxLength":100,"minLength":1,"type":"string","description":"City name","example":"Zurich"},"subdivision":{"maxLength":100,"type":"string","description":"State, province, or canton (optional)","nullable":true,"example":"Zurich"},"country":{"pattern":"^[A-Z]{3}$","type":"string","description":"Country (ISO 3166-1 alpha-3 code)","example":"CHE"},"postalCode":{"maxLength":20,"minLength":1,"type":"string","description":"Postal or ZIP code","example":"8001"}}},"V1EmployeesEmployeeIdBankGetResponse":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdBankDetails"},"V1EmployeesEmployeeIdBankDetails":{"type":"object","properties":{"accountNumber":{"maxLength":50,"minLength":1,"type":"string","description":"Bank account number","example":"1234567890"},"accountHolderName":{"maxLength":200,"minLength":1,"type":"string","description":"Name of the account holder","example":"Foo Bar"},"bankName":{"maxLength":200,"minLength":1,"type":"string","description":"Name of the bank","example":"Swiss National Bank"},"branchName":{"maxLength":200,"type":"string","description":"Bank branch name (optional)","nullable":true,"example":"Zurich Branch"},"swiftCode":{"pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","type":"string","description":"SWIFT/BIC code for international transfers (optional)","nullable":true,"example":"SNBZCHZZ"},"localBankCode":{"maxLength":50,"type":"string","description":"Local bank code (e.g., routing number, sort code, IFSC) - optional","nullable":true,"example":"12345"},"accountType":{"type":"string","description":"Type of bank account","example":"PERSONAL","enum":["PERSONAL","BUSINESS","SAVINGS","CHECKING","UNKNOWN"]},"currency":{"pattern":"^[A-Z]{3}$","type":"string","description":"ISO 4217 currency code","example":"CHF"},"country":{"pattern":"^[A-Z]{3}$","type":"string","description":"ISO 3166-1 alpha-3 country code where the bank is located","example":"CHE"}}},"V1EmployeesEmployeeIdEducationGetResponse":{"type":"object","properties":{"education":{"type":"array","description":"List of education records (ordered by most recent first)","items":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdEducationRecord"}}}},"V1EmployeesEmployeeIdEducationRecord":{"type":"object","properties":{"lastSchoolAttended":{"maxLength":300,"minLength":1,"type":"string","description":"Name of the educational institution","example":"University of Zurich"},"degree":{"maxLength":200,"minLength":1,"type":"string","description":"Degree or qualification earned","example":"Bachelor of Science in Computer Science"},"yearOfPassing":{"maximum":2100,"minimum":1900,"type":"integer","description":"Year of graduation or completion","format":"int32","example":2022},"grade":{"maxLength":50,"type":"string","description":"Grade or class achieved (optional)","nullable":true,"example":"A"},"gpa":{"maximum":10.0,"minimum":0.0,"type":"number","description":"Grade Point Average (optional)","format":"double","nullable":true,"example":3.8}}},"V1EmployeesEmployeeIdEmploymentGetResponse":{"type":"object","properties":{"employeeCode":{"type":"string","description":"Human-readable employee code (optional)","nullable":true,"example":"EMP-12345"},"employeeId":{"type":"string","description":"Deprecated: Use employeeCode instead. Human-readable employee code (optional)","nullable":true,"example":"EMP-12345","deprecated":true},"workEmail":{"type":"string","description":"Employee's work email address","format":"email","nullable":true,"example":"john.doe@company.com"},"entity":{"type":"string","description":"Legal entity name for the employee's employment","nullable":true,"example":"Tech Corp Singapore Pte Ltd"},"country":{"pattern":"^[A-Z]{3}$","type":"string","description":"ISO 3166-1 alpha-3 country code for the employee's country of employment","nullable":true,"example":"SGP"},"startDate":{"type":"string","description":"Date when employee joined the company (YYYY-MM-DD)","format":"date","example":"2023-01-15"},"status":{"type":"string","description":"Current employment status","example":"ACTIVE","enum":["ONBOARDING","ACTIVE","OFFBOARDING","ENDED","DELETED","UNKNOWN"]},"endDate":{"type":"string","description":"Date when employee left or will leave the company (optional)","format":"date","nullable":true,"example":null},"designation":{"type":"string","description":"Job title or position","example":"Software Engineer"},"department":{"type":"string","description":"Department name (optional)","nullable":true,"example":"Engineering"},"type":{"type":"string","description":"Type of employment","example":"EMPLOYEE","enum":["EMPLOYEE","HR_MEMBER","FREELANCER","CONTRACTOR","UNKNOWN"]},"term":{"type":"string","description":"Employment term (fixed-term or permanent)","example":"PERMANENT","enum":["FIXED","PERMANENT","UNKNOWN"]},"noticePeriod":{"type":"object","properties":{"value":{"type":"string","description":"Notice period value","example":"3"},"unit":{"type":"string","description":"Notice period unit","example":"MONTHS","enum":["DAYS","WEEKS","MONTHS","UNKNOWN"]}},"description":"Notice period details (optional).","nullable":true},"exitDetails":{"type":"object","properties":{"type":{"type":"string","description":"Type of termination","example":"RESIGNATION","enum":["RESIGNATION","TERMINATION","DID_NOT_JOIN","UNKNOWN"]},"reason":{"type":"string","description":"Reason for termination (optional)","nullable":true,"example":"Better opportunity"},"dateOfTermination":{"type":"string","description":"Last working day for terminated employees (optional)","format":"date","nullable":true,"example":"2024-12-31"}},"description":"Exit details for offboarded employees (optional)","nullable":true},"reportsTo":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the manager","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"firstName":{"type":"string","description":"Manager's first name","nullable":true,"example":"Jane"},"lastName":{"type":"string","description":"Manager's last name","nullable":true,"example":"Smith"},"designation":{"type":"string","description":"Manager's job designation/position","nullable":true,"example":"Engineering Manager"}},"description":"Manager/supervisor information for this employee","nullable":true}}},"V1EmployeesEmployeeIdEmploymentPatchRequest":{"minProperties":1,"type":"object","properties":{"employeeCode":{"maxLength":50,"minLength":1,"pattern":"^[a-zA-Z0-9\\-_]+$","type":"string","description":"The employee's unique identifier code within the organization.\nMust be alphanumeric with hyphens and underscores allowed.\n","example":"EMP-2024-001"}},"additionalProperties":false,"description":"Request body for updating employee employment details.\nCurrently supports updating employeeCode only (Phase 1).\nAdditional fields will be added in future phases.\n\nAt least one field must be provided; empty requests are not allowed.\n"},"V1EmployeesEmployeeIdEmploymentPatchResponse":{"required":["employeeCode","employeeId"],"type":"object","properties":{"employeeId":{"type":"string","description":"Unique identifier for the employee (employment public ID)","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"employeeCode":{"type":"string","description":"The updated employee code","example":"EMP-2024-001"}},"description":"Response after successfully updating employee employment details."},"V1EmployeesEmployeeIdCompensationGetResponse":{"type":"object","properties":{"compensationDetails":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdCompensationDetails"}}},"V1EmployeesEmployeeIdCompensationDetails":{"type":"object","properties":{"baseSalary":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdCompensationBaseSalary"},"designation":{"type":"string","description":"Employee's job title or designation","nullable":true,"example":"CSM"},"salaryFrequency":{"type":"string","description":"Frequency of salary payment","nullable":true,"example":"MONTHLY","enum":["WEEKLY","SEMIMONTHLY","BIWEEKLY","MONTHLY","ANNUALLY","SEMIANNUALLY","QUARTERLY","DAILY","ONETIME","HOURLY","UNKNOWN"]},"effectiveFrom":{"type":"string","description":"Date from which the compensation is effective (YYYY-MM-DD)","format":"date","nullable":true,"example":"2025-10-31"},"additionalPays":{"type":"array","description":"List of additional pay components","nullable":true,"items":{"$ref":"#/components/schemas/V1EmployeesEmployeeIdCompensationAdditionalPay"}}}},"V1EmployeesEmployeeIdCompensationBaseSalary":{"type":"object","properties":{"amount":{"type":"number","description":"Base salary amount","nullable":true,"example":50000.0},"currency":{"pattern":"^[A-Z]{3}$","type":"string","description":"ISO 4217 currency code","nullable":true,"example":"INR"},"frequency":{"type":"string","description":"Payment frequency","nullable":true,"example":"MONTHLY","enum":["WEEKLY","SEMIMONTHLY","BIWEEKLY","MONTHLY","ANNUALLY","SEMIANNUALLY","QUARTERLY","DAILY","ONETIME","HOURLY","UNKNOWN"]}}},"V1EmployeesEmployeeIdCompensationAdditionalPay":{"type":"object","properties":{"name":{"type":"string","description":"Name of the additional pay component","nullable":true,"example":"HRA"},"label":{"type":"string","description":"Display label for the additional pay component","nullable":true,"example":"House Rent Allowance"},"amount":{"type":"number","description":"Amount of the additional pay","nullable":true,"example":3497.0},"currency":{"pattern":"^[A-Z]{3}$","type":"string","description":"ISO 4217 currency code","nullable":true,"example":"INR"},"frequency":{"type":"string","description":"Payment frequency","nullable":true,"example":"MONTHLY","enum":["HOURLY","DAILY","WEEKLY","SEMIMONTHLY","MONTHLY","BI_MONTHLY","QUATERLY","TRI_ANNUALLY","HALFYEARLY","ANNUALLY","ONCE","CUSTOM","BI_WEEKLY","UNKNOWN"]}}},"V1EmployeesEmployeeIdDevActivatePostResponse":{"required":["activatedOn","employeeId","status"],"type":"object","properties":{"employeeId":{"type":"string","description":"Unique identifier for the employee (employment publicId)","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"status":{"type":"string","description":"The resulting employment status after activation","example":"ACTIVE","enum":["ACTIVE"]},"activatedOn":{"type":"string","description":"ISO 8601 timestamp of when the employment was activated","format":"date-time","example":"2026-03-23T10:00:00Z"}}},"V1EmployeesEmployeeIdDevDeactivatePostResponse":{"required":["employeeId","status"],"type":"object","properties":{"employeeId":{"type":"string","description":"The employee's employment publicId","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"status":{"type":"string","description":"Terminal offboarding status after deactivation","example":"COMPLETED","enum":["COMPLETED"]}}},"ApproverScope":{"type":"string","description":"Approval category scope","example":"TIME_OFF","enum":["TIME_OFF","TIME_SHEET","EXPENSE"]},"ApproverInfo":{"required":["approverId","scope"],"type":"object","properties":{"scope":{"$ref":"#/components/schemas/ApproverScope"},"approverId":{"type":"string","description":"UUID of the company user assigned as approver for this scope","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"}}},"DeleteEmployeeApproversRequest":{"required":["scopes"],"type":"object","properties":{"scopes":{"minItems":1,"type":"array","description":"List of approval scopes whose approver assignments should be removed","example":["TIME_OFF","TIME_SHEET"],"items":{"$ref":"#/components/schemas/ApproverScope"}}}},"V1EmployeesEmployeeIdPayslipsGetResponse":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PayslipData"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"PayslipData":{"required":["employeeId","payslipId","status"],"type":"object","properties":{"payslipId":{"type":"string","description":"Unique identifier of the payslip","format":"uuid","example":"019f4b79-b3fe-7138-b4b6-1037923bb712"},"employeeId":{"type":"string","description":"Unique identifier of the employee","format":"uuid","example":"019ed91c-17b4-797e-933a-2f99ee723033"},"type":{"type":"string","description":"Contract type associated with the payslip","nullable":true,"example":"EOR","enum":["EOR","GLOBAL_PAYROLL"]},"status":{"type":"string","description":"Status of the payslip","example":"AVAILABLE","enum":["PROCESSING","AVAILABLE"]}}},"V1EmployeesEmployeeIdPayslipsPayslipIdGetResponse":{"required":["downloadUrl"],"type":"object","properties":{"downloadUrl":{"$ref":"#/components/schemas/DownloadUrl"}}},"DownloadUrl":{"required":["expiresAt","ttlSeconds","url"],"type":"object","properties":{"url":{"type":"string","description":"Pre-signed download URL for the payslip","format":"uri","example":"https://storage.usemultiplier.com/payslips/signed/ps_mult_ind_001?token=..."},"expiresAt":{"type":"string","description":"ISO-8601 timestamp when the download URL expires","format":"date-time","example":"2026-06-26T11:30:00Z"},"ttlSeconds":{"type":"integer","description":"Time to live for the download URL in seconds","example":1800}}},"V1ExpensesGetResponse":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","description":"List of expenses","items":{"$ref":"#/components/schemas/V1ExpensesGetResponseExpense"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"V1ExpensesGetResponseExpense":{"required":["currency","expenseId","status","title","totalAmount"],"type":"object","properties":{"expenseId":{"type":"string","description":"Unique identifier for the expense","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"title":{"type":"string","description":"Expense title","example":"Business Travel - Singapore"},"status":{"type":"string","description":"Current status of the expense","example":"APPROVED","enum":["DRAFT","REVOKED","APPROVAL_IN_PROGRESS","APPROVED","REJECTED","PROCESSING","PAID","TO_BE_PAID","ON_HOLD","UNKNOWN"]},"totalAmount":{"type":"number","description":"Total expense amount","format":"float","example":1250.5},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"USD"},"submittedAt":{"type":"string","description":"When the expense was submitted","format":"date-time","example":"2025-10-15T10:30:00Z"},"createdOn":{"type":"string","description":"When the expense was created","format":"date-time","example":"2025-10-14T08:00:00Z"},"employeeId":{"type":"string","description":"Employee unique identifier. Use GET /v1/employees/{employeeId} for full employee details","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"items":{"type":"array","description":"List of expense line items","items":{"$ref":"#/components/schemas/V1ExpensesGetResponseItem"}}}},"V1ExpensesGetResponseItem":{"type":"object","properties":{"itemId":{"type":"string","description":"Unique identifier for the expense item","format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"title":{"type":"string","example":"Flight Ticket"},"amount":{"type":"number","format":"float","example":850.0},"date":{"type":"string","format":"date-time","example":"2025-10-10T00:00:00Z"},"category":{"$ref":"#/components/schemas/V1ExpensesGetResponseCategory"},"description":{"type":"string","example":"Round trip flight to Singapore"}},"description":"Expense line item"},"V1ExpensesGetResponseCategory":{"type":"object","properties":{"id":{"type":"string","description":"Category unique identifier","format":"uuid","example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"name":{"type":"string","example":"Travel"}},"description":"Expense category information"},"V1ExpensesExpenseIdGetResponse":{"required":["currency","expenseId","status","title","totalAmount"],"type":"object","properties":{"expenseId":{"type":"string","description":"Unique identifier for the expense","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"title":{"type":"string","description":"Expense title or description","example":"Business Travel - Singapore"},"status":{"type":"string","description":"Current status of the expense","example":"APPROVED","enum":["DRAFT","REVOKED","APPROVAL_IN_PROGRESS","APPROVED","REJECTED","PROCESSING","PAID","TO_BE_PAID","ON_HOLD","UNKNOWN"]},"totalAmount":{"type":"number","description":"Total expense amount","format":"float","example":1250.5},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"USD"},"submittedAt":{"type":"string","description":"When the expense was submitted for approval","format":"date-time","example":"2025-10-15T10:30:00Z"},"createdOn":{"type":"string","description":"When the expense was created","format":"date-time","example":"2025-10-14T08:00:00Z"},"updatedOn":{"type":"string","description":"When the expense was last updated","format":"date-time","example":"2025-10-16T14:20:00Z"},"employeeId":{"type":"string","description":"Employee unique identifier. Use GET /v1/employees/{employeeId} for full employee details","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"items":{"type":"array","description":"List of expense line items with full details","items":{"$ref":"#/components/schemas/V1ExpensesExpenseIdGetResponseItem"}}}},"V1ExpensesExpenseIdGetResponseItem":{"type":"object","properties":{"itemId":{"type":"string","description":"Unique identifier for the expense item","format":"uuid","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"title":{"type":"string","description":"Item title or description","example":"Flight Ticket"},"amount":{"type":"number","description":"Item amount in base currency","format":"float","example":850.0},"date":{"type":"string","description":"Date of the expense","format":"date-time","example":"2025-10-10T00:00:00Z"},"category":{"$ref":"#/components/schemas/V1ExpensesExpenseIdGetResponseCategory"},"description":{"type":"string","description":"Detailed description of the expense item","example":"Round trip flight to Singapore"},"receipts":{"type":"array","description":"Attached receipt documents","items":{"$ref":"#/components/schemas/V1ExpensesExpenseIdGetResponseReceipt"}}},"description":"Detailed expense line item"},"V1ExpensesExpenseIdGetResponseCategory":{"type":"object","properties":{"id":{"type":"string","description":"Category unique identifier","format":"uuid","example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"name":{"type":"string","description":"Category name","example":"Travel"}},"description":"Expense category information"},"V1ExpensesExpenseIdGetResponseReceipt":{"type":"object","properties":{"id":{"type":"string","description":"Receipt document unique identifier","format":"uuid","example":"c3d4e5f6-a7b8-9012-cdef-123456789012"},"name":{"type":"string","description":"Receipt file name","example":"flight-ticket.pdf"},"link":{"type":"string","description":"Download URL for the receipt","format":"uri","example":"https://storage.example.com/receipts/flight-ticket.pdf"}},"description":"Receipt document information"},"TimeOffDate":{"type":"object","properties":{"date":{"type":"string","description":"Date in YYYY-MM-DD format","format":"date","example":"2025-11-15"},"session":{"type":"string","description":"Session of the day","example":"FULL_DAY","enum":["MORNING","AFTERNOON","FULL_DAY"]}}},"TimeOffTypeInfo":{"type":"object","properties":{"typeId":{"type":"string","description":"ID of the time off type","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440001"},"key":{"type":"string","description":"Type key (e.g., 'annual', 'sick')","example":"annual"}}},"V1TimeoffsGetResponse":{"required":["page","timeOffs"],"type":"object","properties":{"timeOffs":{"type":"array","description":"List of time off requests","items":{"$ref":"#/components/schemas/TimeOffItem"}},"page":{"$ref":"#/components/schemas/Pagination"},"allCount":{"type":"integer","description":"Total count of all time offs (regardless of filters)","example":150},"pendingCount":{"type":"integer","description":"Count of time offs pending approval","example":10},"approvedCount":{"type":"integer","description":"Count of approved time offs","example":120}}},"TimeOffItem":{"type":"object","properties":{"timeOffId":{"type":"string","description":"Unique identifier for the time off","format":"uuid","example":"660e8400-e29b-41d4-a716-446655440003"},"status":{"type":"string","description":"Status of the time off","example":"APPROVED","enum":["DRAFT","APPROVAL_IN_PROGRESS","APPROVED","REJECTED","TAKEN","DELETED","REVOKED"]},"startDate":{"$ref":"#/components/schemas/TimeOffDate"},"endDate":{"$ref":"#/components/schemas/TimeOffDate"},"noOfDays":{"type":"number","description":"Number of days for the time off","format":"float","example":6.0},"description":{"type":"string","description":"Description or reason for the time off","example":"Family vacation"},"type":{"$ref":"#/components/schemas/TimeOffTypeInfo"},"createdOn":{"type":"string","description":"Timestamp when the time off was created","format":"date-time","example":"2025-10-23T10:30:00Z"},"updatedOn":{"type":"string","description":"Timestamp when the time off was last updated","format":"date-time","example":"2025-10-23T10:30:00Z"}}},"V1TimeoffsTimeOffIdGetResponse":{"required":["endDate","noOfDays","startDate","status","timeOffId"],"type":"object","properties":{"timeOffId":{"type":"string","description":"Unique identifier for the time off","format":"uuid","example":"660e8400-e29b-41d4-a716-446655440003"},"status":{"type":"string","description":"Current status of the time off request","example":"APPROVED","enum":["DRAFT","APPROVAL_IN_PROGRESS","APPROVED","REJECTED","TAKEN","DELETED","REVOKED"]},"startDate":{"$ref":"#/components/schemas/TimeOffDate"},"endDate":{"$ref":"#/components/schemas/TimeOffDate"},"noOfDays":{"type":"number","description":"Number of days for the time off (calculated)","format":"float","example":6.0},"description":{"type":"string","description":"Description or reason for the time off","example":"Family vacation"},"type":{"$ref":"#/components/schemas/TimeOffTypeInfo"},"createdOn":{"type":"string","description":"Timestamp when the time off was created","format":"date-time","example":"2025-10-23T10:30:00Z"},"updatedOn":{"type":"string","description":"Timestamp when the time off was last updated","format":"date-time","example":"2025-10-23T11:45:00Z"}}},"V1TimesheetsGetResponse":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V1TimesheetsGetResponseTimesheet"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"V1TimesheetsGetResponseTimesheet":{"required":["endDate","startDate","status","timesheetId"],"type":"object","properties":{"timesheetId":{"type":"string","description":"Unique identifier for the timesheet","example":"TS-001"},"employeeId":{"type":"string","description":"Employee unique identifier","example":"123e4567-e89b-12d3-a456-426614174000"},"startDate":{"type":"string","description":"Start date of the timesheet period","format":"date","example":"2025-10-01"},"endDate":{"type":"string","description":"End date of the timesheet period","format":"date","example":"2025-10-31"},"status":{"type":"string","description":"Current status of the timesheet","example":"APPROVED","enum":["OPEN","PARTIALLY_SUBMITTED","SUBMITTED","APPROVED","REJECTED","UNKNOWN"]},"totalDays":{"type":"integer","description":"Total number of days in the period","example":31},"totalSubmittedDays":{"type":"integer","description":"Number of days with submitted entries","example":22},"totalApprovedDays":{"type":"integer","description":"Number of days with approved entries","example":22},"totalRejectedDays":{"type":"integer","description":"Number of days with rejected entries","example":0},"totalTimeInMinutes":{"type":"integer","description":"Total time tracked in minutes","example":10560},"submittedOn":{"type":"string","description":"When the timesheet was submitted","format":"date-time","example":"2025-11-01T09:00:00Z"},"approvedOn":{"type":"string","description":"When the timesheet was approved","format":"date-time","example":"2025-11-02T14:30:00Z"},"updatedOn":{"type":"string","description":"When the timesheet was last updated","format":"date-time","example":"2025-11-02T14:30:00Z"}}},"V1TimesheetsTimesheetIdGetResponse":{"required":["endDate","startDate","status","timesheetId"],"type":"object","properties":{"timesheetId":{"type":"string","description":"Unique identifier for the timesheet","example":"TS-001"},"employeeId":{"type":"string","description":"Unique identifier for the timesheet","example":"123e4567-e89b-12d3-a456-426614174000"},"startDate":{"type":"string","description":"Start date of the timesheet period","format":"date","example":"2025-10-01"},"endDate":{"type":"string","description":"End date of the timesheet period","format":"date","example":"2025-10-31"},"status":{"type":"string","description":"Current status of the timesheet","example":"APPROVED","enum":["OPEN","PARTIALLY_SUBMITTED","SUBMITTED","APPROVED","REJECTED","UNKNOWN"]},"comment":{"type":"string","description":"Comment on the timesheet","example":"October timesheet"},"totalDays":{"type":"integer","description":"Total number of days in the period","example":31},"totalSubmittedDays":{"type":"integer","description":"Number of days with submitted entries","example":22},"totalApprovedDays":{"type":"integer","description":"Number of days with approved entries","example":22},"totalRejectedDays":{"type":"integer","description":"Number of days with rejected entries","example":0},"cutOffDate":{"type":"string","description":"Cut-off date for timesheet submission","format":"date","example":"2025-11-05"},"timeValueInputMethod":{"type":"string","description":"Method used for time entry input","example":"START_TIME_END_TIME","enum":["START_TIME_END_TIME","TOTAL_HOURS","UNKNOWN"]},"totalTimeSummary":{"$ref":"#/components/schemas/V1TimesheetsTimesheetIdGetResponseTotalTimeSummary"},"entries":{"type":"array","description":"Individual timesheet entries for each day","items":{"$ref":"#/components/schemas/V1TimesheetsTimesheetIdGetResponseEntry"}},"submittedOn":{"type":"string","description":"When the timesheet was submitted","format":"date-time","example":"2025-11-01T09:00:00Z"},"approvedOn":{"type":"string","description":"When the timesheet was approved","format":"date-time","example":"2025-11-02T14:30:00Z"},"createdOn":{"type":"string","description":"When the timesheet was created","format":"date-time","example":"2025-10-01T00:00:00Z"},"updatedOn":{"type":"string","description":"When the timesheet was last updated","format":"date-time","example":"2025-11-02T14:30:00Z"}}},"V1TimesheetsTimesheetIdGetResponseTotalTimeSummary":{"type":"object","properties":{"totalTimeInMinutes":{"type":"integer","description":"Total time tracked in minutes","example":10560},"totalLateTimeInMinutes":{"type":"integer","description":"Total late time in minutes","example":45},"summaryItems":{"type":"array","description":"Time summary broken down by day type and hours type","items":{"$ref":"#/components/schemas/V1TimesheetsTimesheetIdGetResponseSummaryItem"}}}},"V1TimesheetsTimesheetIdGetResponseSummaryItem":{"type":"object","properties":{"dayType":{"type":"string","description":"Type of day","example":"REGULAR_DAY","enum":["NOT_APPLICABLE","REGULAR_DAY","REST_DAY","REGULAR_HOLIDAY","SPECIAL_HOLIDAY","OPTIONAL_HOLIDAY","REST_DAY_REGULAR_HOLIDAY","REST_DAY_SPECIAL_HOLIDAY","WEEKEND","FULL_DAY_LEAVE","PARTIAL_LEAVE","ABSENT","COMP_OFF","UNKNOWN"]},"hoursType":{"type":"string","description":"Type of hours","example":"REGULAR_HOURS","enum":["REGULAR_HOURS","OVERTIME_HOURS","OVERTIME_AT_NIGHT_HOURS","NIGHT_SHIFT_HOURS","UNKNOWN"]},"totalTimeInMinutes":{"type":"integer","description":"Total time for this combination in minutes","example":9600}}},"V1TimesheetsTimesheetIdGetResponseEntry":{"type":"object","properties":{"entryId":{"type":"string","description":"Unique identifier for the entry","example":"entry-001"},"date":{"type":"string","description":"Date of the entry","format":"date","example":"2025-10-01"},"status":{"type":"string","description":"Status of the entry","example":"APPROVED","enum":["PARTIALLY_CREATED","PENDING","SUBMITTED","APPROVED","REJECTED","PAID","REVOKED","PAYROLL_INGESTED","UNKNOWN"]},"dayType":{"type":"string","description":"Type of day","example":"REGULAR_DAY","enum":["NOT_APPLICABLE","REGULAR_DAY","REST_DAY","REGULAR_HOLIDAY","SPECIAL_HOLIDAY","OPTIONAL_HOLIDAY","REST_DAY_REGULAR_HOLIDAY","REST_DAY_SPECIAL_HOLIDAY","WEEKEND","FULL_DAY_LEAVE","PARTIAL_LEAVE","ABSENT","COMP_OFF","UNKNOWN"]},"regularTimeInMinutes":{"type":"integer","description":"Regular working time in minutes","example":480},"overtimeTotalInMinutes":{"type":"integer","description":"Total overtime in minutes","example":60},"overtimeAtNightInMinutes":{"type":"integer","description":"Overtime at night in minutes","example":0},"nightShiftTimeInMinutes":{"type":"integer","description":"Night shift time in minutes","example":0},"lateTimeInMinutes":{"type":"integer","description":"Late time in minutes","example":0},"workTimes":{"type":"array","description":"Work time periods for the day","items":{"$ref":"#/components/schemas/V1TimesheetsTimesheetIdGetResponseTimeRange"}},"breakTimes":{"type":"array","description":"Break time periods for the day","items":{"$ref":"#/components/schemas/V1TimesheetsTimesheetIdGetResponseTimeRange"}},"isPaidLeave":{"type":"boolean","description":"Whether this day is paid leave","example":false},"comment":{"type":"string","description":"Comment for the entry","example":"Regular work day"},"submittedOn":{"type":"string","description":"When the entry was submitted","format":"date-time","example":"2025-10-01T18:30:00Z"},"approvedOn":{"type":"string","description":"When the entry was approved","format":"date-time","example":"2025-10-02T10:00:00Z"},"rejectedOn":{"type":"string","description":"When the entry was rejected","format":"date-time","example":null}}},"V1TimesheetsTimesheetIdGetResponseTimeRange":{"type":"object","properties":{"startTime":{"pattern":"^([01]\\d|2[0-3]):([0-5]\\d):([0-5]\\d)$","type":"string","description":"Start time in HH:mm:ss format","format":"time","example":"09:00:00"},"endTime":{"pattern":"^([01]\\d|2[0-3]):([0-5]\\d):([0-5]\\d)$","type":"string","description":"End time in HH:mm:ss format","format":"time","example":"64800"}}},"DepartmentItem":{"type":"object","properties":{"id":{"type":"string","description":"Department ID (UUID).","format":"uuid","example":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c"},"code":{"type":"string","description":"Department code","nullable":true,"example":"DEPT_99"},"name":{"type":"string","description":"Department name","example":"Global Sales"},"description":{"type":"string","description":"Department description","nullable":true,"example":"Internal code: GS-001"},"createdAt":{"type":"string","description":"Timestamp when the department was created (ISO 8601)","format":"date-time","example":"2026-03-24T10:00:00Z"}}},"V1DepartmentsGetResponse":{"required":["data"],"type":"object","properties":{"data":{"type":"array","description":"List of all departments for the company","items":{"$ref":"#/components/schemas/DepartmentItem"}}}},"V1DepartmentsPostRequest":{"required":["name"],"type":"object","properties":{"code":{"type":"string","description":"Department code (optional)","nullable":true,"example":"DEPT_99"},"name":{"type":"string","description":"Department name (required)","example":"Global Sales"},"description":{"type":"string","description":"Department description (optional)","nullable":true,"example":"Internal code: GS-001"}}},"V1DepartmentsPatchRequest":{"type":"object","properties":{"name":{"type":"string","description":"Department name. If omitted, existing name is preserved.","nullable":true,"example":"New Department Name"},"code":{"type":"string","description":"Department code. If omitted, existing code is preserved.","nullable":true,"example":"DEPT_99"},"description":{"type":"string","description":"Department description. If omitted, existing description is preserved.","nullable":true,"example":"Updated description"}}},"CustomerEntityItem":{"type":"object","properties":{"id":{"type":"string","description":"Entity public ID (UUID).","format":"uuid","example":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c"},"name":{"type":"string","description":"Entity legal name","example":"Acme Corp Singapore"}}},"V1EntitiesGetResponse":{"required":["data"],"type":"object","properties":{"data":{"type":"array","description":"List of all entities for the company","items":{"$ref":"#/components/schemas/CustomerEntityItem"}}}},"EmployeeStatus":{"type":"string","description":"Employment status filter","enum":["ONBOARDING","ACTIVE","OFFBOARDING","ENDED","DELETED","ALL"]},"SortByField":{"type":"string","description":"Field to sort by","enum":["startOn"]},"SortOrder":{"type":"string","description":"Sort direction","enum":["ASC","DESC"]},"ErrorItem":{"required":["message"],"type":"object","properties":{"property":{"type":"string","description":"The field that caused the error (only present for validation errors)","example":"email"},"message":{"type":"string","description":"Description of the error","example":"Email format is invalid"}}},"LegacyError":{"required":["code","message"],"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Request validation failed"},"details":{"type":"array","description":"Field-level error details. Only present for validation errors.","nullable":true,"items":{"$ref":"#/components/schemas/LegacyFieldError"}}},"deprecated":true},"LegacyFieldError":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"The field that caused the error","example":"email"},"message":{"type":"string","description":"Description of the field error","example":"Email format is invalid"}},"deprecated":true},"Pagination":{"required":["page","pageSize","totalCount","totalPages"],"type":"object","properties":{"page":{"type":"integer","description":"Current page number (1-based)","example":1},"pageSize":{"type":"integer","description":"Number of items per page","example":20},"totalCount":{"type":"integer","description":"Total number of items across all pages","example":100},"totalPages":{"type":"integer","description":"Total number of pages","example":5}},"description":"Pagination information for list responses"},"FieldDefinition":{"required":["key","required","type"],"type":"object","properties":{"key":{"type":"string","description":"Machine-readable field key","example":"first_name"},"label":{"type":"string","description":"Human-readable field label","example":"First Name"},"type":{"type":"string","description":"Definition type","example":"TEXT"},"required":{"type":"boolean","description":"Whether the Definition is required","example":true}},"discriminator":{"propertyName":"type","mapping":{"TEXT":"#/components/schemas/TextDefinition","NUMBER":"#/components/schemas/NumberDefinition","BOOLEAN":"#/components/schemas/BooleanDefinition","DATE":"#/components/schemas/DateDefinition","SELECT":"#/components/schemas/SelectDefinition"}}},"TextDefinition":{"allOf":[{"$ref":"#/components/schemas/FieldDefinition"},{"type":"object","properties":{"maxLength":{"type":"integer","description":"Maximum length of the text","example":100},"pattern":{"type":"string","description":"Regular expression pattern","example":"^[a-zA-Z0-9]+$"}}}]},"NumberDefinition":{"allOf":[{"$ref":"#/components/schemas/FieldDefinition"},{"type":"object","properties":{"minimum":{"type":"number","description":"Minimum value","example":0},"maximum":{"type":"number","description":"Maximum value","example":100}}}]},"BooleanDefinition":{"allOf":[{"$ref":"#/components/schemas/FieldDefinition"},{"type":"object","properties":{}}]},"DateDefinition":{"allOf":[{"$ref":"#/components/schemas/FieldDefinition"},{"type":"object","properties":{"minDate":{"type":"string","description":"Minimum date","format":"date","example":"2025-01-01"},"maxDate":{"type":"string","description":"Maximum date","format":"date","example":"2025-12-31"}},"description":"Date value in YYYY-MM-DD format"}]},"SelectDefinition":{"allOf":[{"$ref":"#/components/schemas/FieldDefinition"},{"type":"object","properties":{"options":{"type":"array","description":"List of allowed values","example":["option1","option2"],"items":{"type":"string"}},"multiSelect":{"type":"boolean","description":"Whether multiple values are allowed. In case of multiple values, the values are joined by `,`.","example":false}}}]},"StrategicPartner_CustomerListResponse":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","description":"List of customers for the partner","example":[{"id":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6","legalName":"Acme Corporation Pte Ltd","displayName":"Acme Corp","currency":"SGD","status":"ACTIVE"},{"id":"019a0ad5-75d6-7ca5-9995-d0ab28d119d2","legalName":"Beta Industries Ltd","displayName":"Beta Industries","currency":"GBP","status":"CREATED"}],"items":{"$ref":"#/components/schemas/StrategicPartner_CustomerResponse"}},"pagination":{"$ref":"#/components/schemas/StrategicPartner_Pagination"}}},"StrategicPartner_ErrorResponse":{"required":["code","correlationId","message","path","timestamp"],"type":"object","properties":{"timestamp":{"type":"string","description":"ISO-8601 UTC timestamp of when the error occurred","format":"date-time","example":"2026-03-19T10:15:30Z"},"code":{"type":"string","description":"HTTP status code category:\n- BAD_REQUEST: 400 - request validation or input error\n- UNAUTHORIZED: 401 - authentication failure\n- FORBIDDEN: 403 - authorization failure\n- NOT_FOUND: 404 - resource not found\n- CONFLICT: 409 - resource conflict\n- INTERNAL_SERVER_ERROR: 500 - unexpected server error\n- SERVICE_UNAVAILABLE: 503 - service unavailable\n","example":"BAD_REQUEST"},"message":{"type":"string","description":"Human-readable summary of the error","example":"Request validation failed"},"path":{"type":"string","description":"The request path that caused the error","example":"/v1/partner/customers"},"correlationId":{"type":"string","description":"Correlation ID for tracing this error across systems","example":"4bf92f3577b34da6a3ce929d0e0e4736"},"errors":{"type":"array","description":"Field-level error details. Present only for validation errors (VALIDATION_ERROR); omitted or null for all other error types.","items":{"$ref":"#/components/schemas/StrategicPartner_ErrorItem"}},"error":{"required":["code","message","type"],"type":"object","properties":{"type":{"type":"object","description":"Error category for client-side handling:\n- ValidationError: Request validation failed\n- NotFoundError: Resource doesn't exist\n- ConflictError: Resource already exists or state conflict\n- AuthenticationError: Invalid credentials\n- AuthorizationError: Insufficient permissions\n- ServerError: Unexpected server error\n","example":"ValidationError","enum":["ValidationError","NotFoundError","ConflictError","AuthenticationError","AuthorizationError","ServerError"]},"code":{"type":"object","description":"Common codes:\n- VALIDATION_FAILED: Request validation failed\n- RESOURCE_NOT_FOUND: Resource doesn't exist\n- RESOURCE_ALREADY_EXISTS: Duplicate resource\n- RESOURCE_CONFLICT: State conflict\n- AUTHENTICATION_FAILED: Invalid credentials\n- AUTHORIZATION_FAILED: Insufficient permissions\n- INTERNAL_ERROR: Server error\n","example":"VALIDATION_FAILED","enum":["VALIDATION_FAILED","RESOURCE_NOT_FOUND","RESOURCE_ALREADY_EXISTS","RESOURCE_CONFLICT","AUTHENTICATION_FAILED","AUTHORIZATION_FAILED","INTERNAL_ERROR"]},"message":{"type":"object","description":"Human-readable error message","example":"Request validation failed"},"details":{"type":"object","description":"Field-level validation errors (only present for validation_error type)","items":{"$ref":"#/components/schemas/StrategicPartner_FieldError"}}},"description":"Deprecated: use top-level fields (timestamp, code, message, path, correlationId, errors) instead. This field will be removed in a future version.","deprecated":true}},"description":"Standard error response for all API errors"},"StrategicPartner_ErrorItem":{"required":["message"],"type":"object","properties":{"property":{"type":"string","description":"Property path that caused the error, using dot notation","example":"email"},"message":{"type":"string","description":"Human-readable error message","example":"Email format is invalid"}},"description":"Individual error item"},"StrategicPartner_FieldError":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"Field path using dot notation for nested fields","example":"admin.email"},"message":{"type":"string","description":"Human-readable error message for this field","example":"Email address is not valid"}},"description":"Field-level validation error"},"StrategicPartner_CustomerCreateRequest":{"required":["country","currency","legalName"],"type":"object","properties":{"legalName":{"maxLength":200,"minLength":2,"type":"string","description":"Official legal name of the customer as registered","example":"Acme Corporation Pte Ltd"},"displayName":{"maxLength":100,"minLength":2,"type":"string","description":"Display name for the customer (defaults to legalName if not provided)","example":"Acme Corp"},"registrationNumber":{"maxLength":50,"minLength":3,"pattern":"^[A-Z0-9\\-]+$","type":"string","description":"Unique customer registration number (e.g., UEN, CRN, Tax ID).\nMust be alphanumeric with hyphens only.\n","example":"202301234A"},"currency":{"type":"string","description":"Primary operating currency for the customer","example":"USD","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNH","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GGP","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","IMP","INR","IQD","IRR","ISK","JEP","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SPL","SRD","SSP","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TVD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UYW","UZS","VEF","VES","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","YER","ZAR","ZMK","ZMW","ZWD","ZWL"]},"country":{"type":"string","description":"Country of incorporation (required for compliance and tax purposes)","example":"USA","enum":["ABW","AFG","AGO","AIA","ALA","ALB","AND","ARE","ARG","ARM","ASM","ATA","ATF","ATG","AUS","AUT","AZE","BDI","BEL","BEN","BES","BFA","BGD","BGR","BHR","BHS","BIH","BLM","BLR","BLZ","BMU","BOL","BRA","BRB","BRN","BTN","BVT","BWA","CAF","CAN","CCK","CHE","CHL","CHN","CIV","CMR","COD","COG","COK","COL","COM","CPV","CRI","CUB","CUW","CXR","CYM","CYP","CZE","DEU","DJI","DMA","DNK","DOM","DZA","ECU","EGY","ERI","ESH","ESP","EST","ETH","FIN","FJI","FLK","FRA","FRO","FSM","GAB","GBR","GEO","GGY","GHA","GIB","GIN","GLP","GMB","GNB","GNQ","GRC","GRD","GRL","GTM","GUF","GUM","GUY","HKG","HMD","HND","HRV","HTI","HUN","IDN","IMN","IND","IOT","IRL","IRN","IRQ","ISL","ISR","ITA","JAM","JEY","JOR","JPN","KAZ","KEN","KGZ","KHM","KIR","KNA","KOR","KWT","LAO","LBN","LBR","LBY","LCA","LIE","LKA","LSO","LTU","LUX","LVA","MAC","MAF","MAR","MCO","MDA","MDG","MDV","MEX","MHL","MKD","MLI","MLT","MMR","MNE","MNG","MNP","MOZ","MRT","MSR","MTQ","MUS","MWI","MYS","MYT","NAM","NCL","NER","NFK","NGA","NIC","NIU","NLD","NOR","NPL","NRU","NZL","OMN","PAK","PAN","PCN","PER","PHL","PLW","PNG","POL","PRI","PRK","PRT","PRY","PSE","PYF","QAT","REU","ROU","RUS","RWA","SAU","SDN","SEN","SGP","SGS","SHN","SJM","SLB","SLE","SLV","SMR","SOM","SPM","SRB","SSD","STP","SUR","SVK","SVN","SWE","SWZ","SXM","SYC","SYR","TCA","TCD","TGO","THA","TJK","TKL","TKM","TLS","TON","TTO","TUN","TUR","TUV","TWN","TZA","UGA","UKR","UMI","URY","USA","UZB","VAT","VCT","VEN","VGB","VIR","VNM","VUT","WLF","WSM","YEM","ZAF","ZMB","ZWE"]},"address":{"$ref":"#/components/schemas/StrategicPartner_Address"}}},"StrategicPartner_CustomerResponse":{"required":["displayName","id","legalName","status"],"type":"object","properties":{"id":{"type":"string","description":"Unique customer identifier (UUID v7 format)","example":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6"},"legalName":{"type":"string","description":"Official legal name of the customer","example":"Acme Corporation Pte Ltd"},"displayName":{"type":"string","description":"Display name for the customer","example":"Acme Corp"},"currency":{"type":"string","description":"Primary operating currency","example":"USD","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNH","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GGP","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","IMP","INR","IQD","IRR","ISK","JEP","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SPL","SRD","SSP","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TVD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UYW","UZS","VEF","VES","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","YER","ZAR","ZMK","ZMW","ZWD","ZWL"]},"status":{"$ref":"#/components/schemas/StrategicPartner_CustomerStatus"},"customerCode":{"type":"string","description":"External customer identifier provided by the partner","example":"CUST-12345"}}},"StrategicPartner_CustomerUpdateRequest":{"type":"object","properties":{"legalName":{"maxLength":200,"minLength":2,"type":"string","description":"Official legal name of the customer","example":"Acme Corporation Pte Ltd"},"displayName":{"maxLength":100,"minLength":2,"type":"string","description":"Display name for the customer","example":"Acme Corp"},"registrationNumber":{"maxLength":50,"minLength":3,"pattern":"^[A-Z0-9\\-]+$","type":"string","description":"Customer registration number","example":"202301234A"},"currency":{"type":"string","description":"Primary operating currency","example":"USD","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNH","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GGP","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","IMP","INR","IQD","IRR","ISK","JEP","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SPL","SRD","SSP","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TVD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UYW","UZS","VEF","VES","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","YER","ZAR","ZMK","ZMW","ZWD","ZWL"]},"address":{"$ref":"#/components/schemas/StrategicPartner_Address"}},"description":"Partial update request for customer. All fields are optional.\nOnly provided fields will be updated.\n"},"StrategicPartner_CustomerUserListResponse":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","description":"List of customer users","example":[{"id":"018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f","firstName":"John","lastName":"Doe","email":"john.doe@acme.com","role":"ADMIN","customerId":"018e3f7a-2b1c-7d8e-4f5a-6c7b8d9e0f1a"},{"id":"018e3f7a-4d5c-7e9f-1a2b-3c4d5e6f7a8b","firstName":"Jane","lastName":"Smith","email":"jane.smith@acme.com","role":"ADMIN","customerId":"018e3f7a-2b1c-7d8e-4f5a-6c7b8d9e0f1a"}],"items":{"$ref":"#/components/schemas/StrategicPartner_CustomerUserResponse"}},"pagination":{"$ref":"#/components/schemas/StrategicPartner_Pagination"}}},"StrategicPartner_CustomerUserCreateRequest":{"required":["email","firstName","lastName","role"],"type":"object","properties":{"firstName":{"maxLength":100,"minLength":1,"type":"string","description":"User's first name","example":"John"},"lastName":{"maxLength":100,"minLength":1,"type":"string","description":"User's last name","example":"Doe"},"email":{"type":"string","description":"User's email address","format":"email","example":"john.doe@acme.com"},"role":{"type":"string","description":"User's role within the customer:\n- ADMIN: Administrator user to fully manage customer account\n- BILLING_ADMIN: Billing administrator user to manage customer billing\n- PAYROLL_ADMIN: Payroll administrator user to manage customer payroll\n- HR_ADMIN: HR administrator user to manage customer HR\n","example":"ADMIN","enum":["ADMIN","BILLING_ADMIN","PAYROLL_ADMIN","HR_ADMIN","MANAGER"]}}},"StrategicPartner_CustomerUserResponse":{"required":["customerId","email","id","role"],"type":"object","properties":{"id":{"type":"string","description":"Unique customer user identifier","example":"018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f"},"firstName":{"type":"string","description":"User's first name","example":"John"},"lastName":{"type":"string","description":"User's last name","example":"Doe"},"email":{"type":"string","description":"User's email address","format":"email","example":"john.doe@acme.com"},"role":{"type":"string","description":"User's role within the customer:\n- ADMIN: Administrator user to fully manage customer account\n- BILLING_ADMIN: Billing administrator user to manage customer billing\n- PAYROLL_ADMIN: Payroll administrator user to manage customer payroll\n- HR_ADMIN: HR administrator user to manage customer HR\n","example":"ADMIN","enum":["ADMIN","BILLING_ADMIN","PAYROLL_ADMIN","HR_ADMIN","MANAGER"]},"customerId":{"type":"string","description":"Customer ID this user belongs to","example":"018e3f7a-2b1c-7d8e-4f5a-6c7b8d9e0f1a"}}},"StrategicPartner_PartnerUserCreateRequest":{"required":["email","firstName","lastName"],"type":"object","properties":{"email":{"type":"string","description":"User's email address","format":"email","example":"john.doe@example.com"},"firstName":{"maxLength":100,"minLength":1,"type":"string","description":"User's first name","example":"John"},"lastName":{"maxLength":100,"minLength":1,"type":"string","description":"User's last name","example":"Doe"}}},"StrategicPartner_PartnerUserResponse":{"required":["id"],"type":"object","properties":{"id":{"type":"string","description":"Partner user ID","format":"uuid","example":"018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f"}}},"StrategicPartner_PartnerDomainResponse":{"required":["fqdn","id","partnerId"],"type":"object","properties":{"id":{"type":"string","description":"Domain ID","format":"uuid","example":"018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f"},"fqdn":{"type":"string","description":"Fully qualified domain name","example":"partner.example.com"},"partnerId":{"type":"string","description":"Partner ID this domain belongs to","format":"uuid","example":"018e3f7a-2b1c-7d8e-4f5a-6c7b8d9e0f1a"}}},"StrategicPartner_PartnerDomainCreateRequest":{"required":["fqdn"],"type":"object","properties":{"fqdn":{"maxLength":253,"minLength":1,"pattern":"^([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$","type":"string","description":"Fully qualified domain name","example":"partner.example.com"}}},"StrategicPartner_PartnerConfigurationResponse":{"required":["id","key","partnerId","value"],"type":"object","properties":{"id":{"type":"string","description":"Configuration ID","format":"uuid","example":"018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f"},"key":{"type":"string","description":"Configuration key","example":"webhook_url"},"value":{"type":"object","description":"Configuration value (JSON object)","example":{"url":"https://partner.example.com/webhook","enabled":true}},"partnerId":{"type":"string","description":"Partner ID this configuration belongs to","format":"uuid","example":"018e3f7a-2b1c-7d8e-4f5a-6c7b8d9e0f1a"}}},"StrategicPartner_Pagination":{"required":["page","pageSize","totalCount"],"type":"object","properties":{"page":{"minimum":1,"type":"integer","description":"Current page number (1-indexed)","example":1},"pageSize":{"maximum":100,"minimum":1,"type":"integer","description":"Number of items per page","example":20},"totalCount":{"minimum":0,"type":"integer","description":"Total number of items across all pages","example":150},"totalPages":{"minimum":0,"type":"integer","description":"Total number of pages (calculated from totalCount and pageSize)","example":8}}},"StrategicPartner_Address":{"type":"object","properties":{"line1":{"maxLength":200,"minLength":1,"type":"string","description":"Street address (line 1)","example":"123 Robinson Road"},"line2":{"maxLength":200,"type":"string","description":"Additional street address information (line 2)","example":null},"city":{"maxLength":100,"minLength":1,"type":"string","description":"City or locality","example":"Singapore"},"state":{"maxLength":100,"type":"string","description":"State, province, or region (if applicable)","example":null},"postalCode":{"maxLength":20,"minLength":1,"type":"string","description":"Postal or ZIP code","example":"068899"},"country":{"type":"string","description":"ISO 3166-1 alpha-3 country code","example":"USA","enum":["ABW","AFG","AGO","AIA","ALA","ALB","AND","ARE","ARG","ARM","ASM","ATA","ATF","ATG","AUS","AUT","AZE","BDI","BEL","BEN","BES","BFA","BGD","BGR","BHR","BHS","BIH","BLM","BLR","BLZ","BMU","BOL","BRA","BRB","BRN","BTN","BVT","BWA","CAF","CAN","CCK","CHE","CHL","CHN","CIV","CMR","COD","COG","COK","COL","COM","CPV","CRI","CUB","CUW","CXR","CYM","CYP","CZE","DEU","DJI","DMA","DNK","DOM","DZA","ECU","EGY","ERI","ESH","ESP","EST","ETH","FIN","FJI","FLK","FRA","FRO","FSM","GAB","GBR","GEO","GGY","GHA","GIB","GIN","GLP","GMB","GNB","GNQ","GRC","GRD","GRL","GTM","GUF","GUM","GUY","HKG","HMD","HND","HRV","HTI","HUN","IDN","IMN","IND","IOT","IRL","IRN","IRQ","ISL","ISR","ITA","JAM","JEY","JOR","JPN","KAZ","KEN","KGZ","KHM","KIR","KNA","KOR","KWT","LAO","LBN","LBR","LBY","LCA","LIE","LKA","LSO","LTU","LUX","LVA","MAC","MAF","MAR","MCO","MDA","MDG","MDV","MEX","MHL","MKD","MLI","MLT","MMR","MNE","MNG","MNP","MOZ","MRT","MSR","MTQ","MUS","MWI","MYS","MYT","NAM","NCL","NER","NFK","NGA","NIC","NIU","NLD","NOR","NPL","NRU","NZL","OMN","PAK","PAN","PCN","PER","PHL","PLW","PNG","POL","PRI","PRK","PRT","PRY","PSE","PYF","QAT","REU","ROU","RUS","RWA","SAU","SDN","SEN","SGP","SGS","SHN","SJM","SLB","SLE","SLV","SMR","SOM","SPM","SRB","SSD","STP","SUR","SVK","SVN","SWE","SWZ","SXM","SYC","SYR","TCA","TCD","TGO","THA","TJK","TKL","TKM","TLS","TON","TTO","TUN","TUR","TUV","TWN","TZA","UGA","UKR","UMI","URY","USA","UZB","VAT","VCT","VEN","VGB","VIR","VNM","VUT","WLF","WSM","YEM","ZAF","ZMB","ZWE"]}},"description":"Physical address information.\nWhen used with customer, the country field is informational only -\nthe customer's country field is the authoritative source.\n"},"StrategicPartner_CustomerStatus":{"type":"string","description":"Customer account status:\n- UNKNOWN_COMPANY_STATUS: Unknown or unrecognized company status\n- CREATED: Customer record created\n- INVITED: Customer invited to join\n- INVITE_ACCEPTED: Customer accepted invitation\n- UNVERIFIED: Created but not yet verified\n- ACTIVE: Fully operational\n- INACTIVE: Temporarily suspended or closed\n","example":"ACTIVE","enum":["UNKNOWN_COMPANY_STATUS","CREATED","INVITED","INVITE_ACCEPTED","UNVERIFIED","ACTIVE","INACTIVE"]},"ClientAuth_TokenRequest":{"required":["client_id","client_secret","grant_type"],"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth 2.0 grant type (must be \"client_credentials\")","example":"client_credentials","enum":["client_credentials"]},"client_id":{"type":"string","description":"Client ID provided by Multiplier","example":"partner_abc123"},"client_secret":{"type":"string","description":"Client secret provided by Multiplier","format":"password","example":"secret_xyz789"},"scope":{"type":"string","description":"Optional scope (currently not supported)","example":null}}},"ClientAuth_TokenResponse":{"required":["access_token","expires_in","token_type"],"type":"object","properties":{"access_token":{"type":"string","description":"The access token to use for authenticated requests","example":"tok_abc123def456ghi789jkl012mno345pqrst"},"token_type":{"type":"string","description":"Token type (always \"Bearer\")","example":"Bearer","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Token expiration time in seconds","format":"int64","example":3600}}},"ClientAuth_ErrorResponse":{"required":["code","correlationId","message","path","timestamp"],"type":"object","properties":{"timestamp":{"type":"string","description":"ISO-8601 UTC timestamp of when the error occurred","format":"date-time","example":"2026-03-19T10:15:30Z"},"code":{"type":"string","description":"HTTP status code category:\n- BAD_REQUEST: 400 - request validation or input error\n- UNAUTHORIZED: 401 - authentication failure\n- FORBIDDEN: 403 - authorization failure\n- NOT_FOUND: 404 - resource not found\n- CONFLICT: 409 - resource conflict\n- INTERNAL_SERVER_ERROR: 500 - unexpected server error\n- SERVICE_UNAVAILABLE: 503 - service unavailable\n","example":"BAD_REQUEST"},"message":{"type":"string","description":"Human-readable summary of the error","example":"Request validation failed"},"path":{"type":"string","description":"The request path that caused the error","example":"/v1/client/token"},"correlationId":{"type":"string","description":"Correlation ID for tracing this error across systems","example":"4bf92f3577b34da6a3ce929d0e0e4736"},"errors":{"type":"array","description":"Field-level error details. Present only for validation errors (VALIDATION_ERROR); omitted or null for all other error types.","items":{"$ref":"#/components/schemas/ClientAuth_ErrorResponse_errors"}},"error":{"$ref":"#/components/schemas/ClientAuth_ErrorResponse_error"}},"description":"Standard error response for all API errors"},"ClientAuth_ErrorItem":{"required":["message"],"type":"object","properties":{"property":{"type":"string","description":"Property path that caused the error, using dot notation","example":"email"},"message":{"type":"string","description":"Human-readable error message","example":"Email format is invalid"}},"description":"Individual error item"},"ClientAuth_FieldError":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"Field path using dot notation for nested fields","example":"admin.email"},"message":{"type":"string","description":"Human-readable error message for this field","example":"Email address is not valid"}},"description":"Field-level validation error"},"ClientAuth_client_token_body":{"required":["client_id","client_secret","grant_type"],"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth 2.0 grant type (must be \"client_credentials\")","example":"client_credentials","enum":["client_credentials"]},"client_id":{"type":"string","description":"Client ID provided by Multiplier","example":"partner_abc123"},"client_secret":{"type":"string","description":"Client secret provided by Multiplier","format":"password","example":"secret_xyz789"},"scope":{"type":"string","description":"Optional scope (currently not supported)","example":null}}},"ClientAuth_client_token_body_1":{"required":["client_id","client_secret","grant_type"],"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth 2.0 grant type (must be \"client_credentials\")","example":"client_credentials","enum":["client_credentials"]},"client_id":{"type":"string","description":"Client ID provided by Multiplier","example":"partner_abc123"},"client_secret":{"type":"string","description":"Client secret provided by Multiplier","format":"password","example":"secret_xyz789"},"scope":{"type":"string","description":"Optional scope (currently not supported)","example":null}}},"ClientAuth_inline_response_200":{"required":["access_token","expires_in","token_type"],"type":"object","properties":{"access_token":{"type":"string","description":"The access token to use for authenticated requests","example":"tok_abc123def456ghi789jkl012mno345pqrst"},"token_type":{"type":"string","description":"Token type (always \"Bearer\")","example":"Bearer","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Token expiration time in seconds","format":"int64","example":3600}}},"ClientAuth_inline_response_400":{"required":["code","correlationId","message","path","timestamp"],"type":"object","properties":{"timestamp":{"type":"string","description":"ISO-8601 UTC timestamp of when the error occurred","format":"date-time","example":"2026-03-19T10:15:30Z"},"code":{"type":"string","description":"HTTP status code category:\n- BAD_REQUEST: 400 - request validation or input error\n- UNAUTHORIZED: 401 - authentication failure\n- FORBIDDEN: 403 - authorization failure\n- NOT_FOUND: 404 - resource not found\n- CONFLICT: 409 - resource conflict\n- INTERNAL_SERVER_ERROR: 500 - unexpected server error\n- SERVICE_UNAVAILABLE: 503 - service unavailable\n","example":"BAD_REQUEST"},"message":{"type":"string","description":"Human-readable summary of the error","example":"Request validation failed"},"path":{"type":"string","description":"The request path that caused the error","example":"/v1/client/token"},"correlationId":{"type":"string","description":"Correlation ID for tracing this error across systems","example":"4bf92f3577b34da6a3ce929d0e0e4736"},"errors":{"type":"array","description":"Field-level error details. Present only for validation errors (VALIDATION_ERROR); omitted or null for all other error types.","items":{"$ref":"#/components/schemas/ClientAuth_ErrorResponse_errors"}},"error":{"$ref":"#/components/schemas/ClientAuth_ErrorResponse_error"}},"description":"Standard error response for all API errors"},"ClientAuth_ErrorResponse_errors":{"required":["message"],"type":"object","properties":{"property":{"type":"string","description":"Property path that caused the error, using dot notation","example":"email"},"message":{"type":"string","description":"Human-readable error message","example":"Email format is invalid"}},"description":"Individual error item"},"ClientAuth_ErrorResponse_error_details":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"Field path using dot notation for nested fields","example":"admin.email"},"message":{"type":"string","description":"Human-readable error message for this field","example":"Email address is not valid"}},"description":"Field-level validation error"},"ClientAuth_ErrorResponse_error":{"required":["code","message","type"],"type":"object","properties":{"type":{"type":"string","description":"Error category for client-side handling:\n- ValidationError: Request validation failed\n- NotFoundError: Resource doesn't exist\n- ConflictError: Resource already exists or state conflict\n- AuthenticationError: Invalid credentials\n- AuthorizationError: Insufficient permissions\n- ServerError: Unexpected server error\n","example":"ValidationError","enum":["ValidationError","NotFoundError","ConflictError","AuthenticationError","AuthorizationError","ServerError"]},"code":{"type":"string","description":"Common codes:\n- VALIDATION_FAILED: Request validation failed\n- RESOURCE_NOT_FOUND: Resource doesn't exist\n- RESOURCE_ALREADY_EXISTS: Duplicate resource\n- RESOURCE_CONFLICT: State conflict\n- AUTHENTICATION_FAILED: Invalid credentials\n- AUTHORIZATION_FAILED: Insufficient permissions\n- INTERNAL_ERROR: Server error\n","example":"VALIDATION_FAILED","enum":["VALIDATION_FAILED","RESOURCE_NOT_FOUND","RESOURCE_ALREADY_EXISTS","RESOURCE_CONFLICT","AUTHENTICATION_FAILED","AUTHORIZATION_FAILED","INTERNAL_ERROR"]},"message":{"type":"string","description":"Human-readable error message","example":"Request validation failed"},"details":{"type":"array","description":"Field-level validation errors (only present for validation_error type)","items":{"$ref":"#/components/schemas/ClientAuth_ErrorResponse_error_details"}}},"description":"Deprecated: use top-level fields (timestamp, code, message, path, correlationId, errors) instead. This field will be removed in a future version.","deprecated":true},"UserService_TokenExchangeRequest":{"required":["grant_type","requested_subject","subject_token","subject_token_type"],"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth 2.0 grant type (must be \"urn:ietf:params:oauth:grant-type:token-exchange\")","example":"urn:ietf:params:oauth:grant-type:token-exchange","enum":["urn:ietf:params:oauth:grant-type:token-exchange"]},"subject_token":{"type":"string","description":"The partner access token to be exchanged","example":"partner_access_token_abc123"},"subject_token_type":{"type":"string","description":"Token type (must be \"urn:ietf:params:oauth:token-type:access_token\")","example":"urn:ietf:params:oauth:token-type:access_token","enum":["urn:ietf:params:oauth:token-type:access_token"]},"requested_subject":{"type":"string","description":"The platform user ID for whom the token is being requested (extension field)","example":"user_id_xyz789"},"scope":{"type":"string","description":"User scope/role for access permissions","example":"ADMIN","enum":["ADMIN","MANAGER","PAYROLL_ADMIN","BILLING_ADMIN","HR_ADMIN","IT_ADMIN"]}}},"UserService_UserScope":{"type":"string","description":"User scope/role for access permissions","example":"ADMIN","enum":["ADMIN","MANAGER","PAYROLL_ADMIN","BILLING_ADMIN","HR_ADMIN","IT_ADMIN"]},"UserService_TokenResponse":{"required":["access_token","expires_in","token_type"],"type":"object","properties":{"access_token":{"type":"string","description":"The access token (JWT) to use for authenticated requests","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"token_type":{"type":"string","description":"Token type (always \"Bearer\")","example":"Bearer","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Token expiration time in seconds","format":"int64","example":3600},"refresh_token":{"type":"string","description":"The refresh token (only included for token-exchange endpoint)","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.refresh..."},"customer_user_id":{"type":"string","description":"The customer user ID (UUID). Included when a user was auto-provisioned.","example":"759a086f-48b3-4e34-aefd-00c8a9e68523"}}},"UserService_ErrorResponse":{"required":["error"],"type":"object","properties":{"error":{"$ref":"#/components/schemas/UserService_ErrorResponse_error"}},"description":"Standard error response for all API errors"},"UserService_FieldError":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"Field path using dot notation for nested fields","example":"admin.email"},"message":{"type":"string","description":"Human-readable error message for this field","example":"Email address is not valid"}},"description":"Field-level validation error"},"UserService_AuthCodeRequest":{"type":"object","properties":{"customerUserId":{"type":"string","description":"The customer user ID for which to generate the auth code (UUID). Either this or (customerId+email+firstName+lastName) must be provided.","example":"759a086f-48b3-4e34-aefd-00c8a9e68523"},"customerId":{"type":"string","description":"The customer ID for auto-provisioning. Required if customerUserId is not provided.","example":"a7e55f28-8395-4884-8469-d16d90051b57"},"email":{"type":"string","description":"User email for auto-provisioning. Required if customerUserId is not provided.","format":"email","example":"john.doe@example.com"},"firstName":{"type":"string","description":"User first name for auto-provisioning. Required if customerUserId is not provided.","example":"John"},"lastName":{"type":"string","description":"User last name for auto-provisioning. Required if customerUserId is not provided.","example":"Doe"},"scope":{"type":"string","description":"User scope/role for access permissions","example":"ADMIN","enum":["ADMIN","MANAGER","PAYROLL_ADMIN","BILLING_ADMIN","HR_ADMIN","IT_ADMIN"]}}},"UserService_AuthCodeResponse":{"required":["auth_code","expires_in"],"type":"object","properties":{"auth_code":{"type":"string","description":"The generated authorization code","example":"abc123def456"},"expires_in":{"type":"integer","description":"Auth code expiration time in seconds","format":"int64","example":60},"customer_user_id":{"type":"string","description":"The customer user ID (UUID). Included when a user was auto-provisioned.","example":"759a086f-48b3-4e34-aefd-00c8a9e68523"}}},"UserService_AuthCodeTokenRequest":{"required":["client_id","code","grant_type"],"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth 2.0 grant type (must be \"authorization_code\")","example":"authorization_code","enum":["authorization_code"]},"code":{"type":"string","description":"The authorization code from the partner","example":"abc123def456"},"client_id":{"type":"string","description":"The client identifier","example":"partner_client_123"}}},"UserService_partner_tokenexchange_body":{"required":["grant_type","requested_subject","subject_token","subject_token_type"],"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth 2.0 grant type (must be \"urn:ietf:params:oauth:grant-type:token-exchange\")","example":"urn:ietf:params:oauth:grant-type:token-exchange","enum":["urn:ietf:params:oauth:grant-type:token-exchange"]},"subject_token":{"type":"string","description":"The partner access token to be exchanged","example":"partner_access_token_abc123"},"subject_token_type":{"type":"string","description":"Token type (must be \"urn:ietf:params:oauth:token-type:access_token\")","example":"urn:ietf:params:oauth:token-type:access_token","enum":["urn:ietf:params:oauth:token-type:access_token"]},"requested_subject":{"type":"string","description":"The platform user ID for whom the token is being requested (extension field)","example":"user_id_xyz789"},"scope":{"type":"string","description":"User scope/role for access permissions","example":"ADMIN","enum":["ADMIN","MANAGER","PAYROLL_ADMIN","BILLING_ADMIN","HR_ADMIN","IT_ADMIN"]}}},"UserService_inline_response_200":{"required":["access_token","expires_in","token_type"],"type":"object","properties":{"access_token":{"type":"string","description":"The access token (JWT) to use for authenticated requests","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"token_type":{"type":"string","description":"Token type (always \"Bearer\")","example":"Bearer","enum":["Bearer"]},"expires_in":{"type":"integer","description":"Token expiration time in seconds","format":"int64","example":3600},"refresh_token":{"type":"string","description":"The refresh token (only included for token-exchange endpoint)","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.refresh..."},"customer_user_id":{"type":"string","description":"The customer user ID (UUID). Included when a user was auto-provisioned.","example":"759a086f-48b3-4e34-aefd-00c8a9e68523"}}},"UserService_inline_response_400":{"required":["error"],"type":"object","properties":{"error":{"$ref":"#/components/schemas/UserService_ErrorResponse_error"}},"description":"Standard error response for all API errors"},"UserService_partner_requestauthcode_body":{"type":"object","properties":{"customerUserId":{"type":"string","description":"The customer user ID for which to generate the auth code (UUID). Either this or (customerId+email+firstName+lastName) must be provided.","example":"759a086f-48b3-4e34-aefd-00c8a9e68523"},"customerId":{"type":"string","description":"The customer ID for auto-provisioning. Required if customerUserId is not provided.","example":"a7e55f28-8395-4884-8469-d16d90051b57"},"email":{"type":"string","description":"User email for auto-provisioning. Required if customerUserId is not provided.","format":"email","example":"john.doe@example.com"},"firstName":{"type":"string","description":"User first name for auto-provisioning. Required if customerUserId is not provided.","example":"John"},"lastName":{"type":"string","description":"User last name for auto-provisioning. Required if customerUserId is not provided.","example":"Doe"},"scope":{"type":"string","description":"User scope/role for access permissions","example":"ADMIN","enum":["ADMIN","MANAGER","PAYROLL_ADMIN","BILLING_ADMIN","HR_ADMIN","IT_ADMIN"]}}},"UserService_inline_response_200_1":{"required":["auth_code","expires_in"],"type":"object","properties":{"auth_code":{"type":"string","description":"The generated authorization code","example":"abc123def456"},"expires_in":{"type":"integer","description":"Auth code expiration time in seconds","format":"int64","example":60},"customer_user_id":{"type":"string","description":"The customer user ID (UUID). Included when a user was auto-provisioned.","example":"759a086f-48b3-4e34-aefd-00c8a9e68523"}}},"UserService_partner_authcode_body":{"required":["client_id","code","grant_type"],"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth 2.0 grant type (must be \"authorization_code\")","example":"authorization_code","enum":["authorization_code"]},"code":{"type":"string","description":"The authorization code from the partner","example":"abc123def456"},"client_id":{"type":"string","description":"The client identifier","example":"partner_client_123"}}},"UserService_ErrorResponse_error_details":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"Field path using dot notation for nested fields","example":"admin.email"},"message":{"type":"string","description":"Human-readable error message for this field","example":"Email address is not valid"}},"description":"Field-level validation error"},"UserService_ErrorResponse_error":{"required":["code","message","type"],"type":"object","properties":{"type":{"type":"string","description":"Error category for client-side handling:\n- ValidationError: Request validation failed\n- NotFoundError: Resource doesn't exist\n- ConflictError: Resource already exists or state conflict\n- AuthenticationError: Invalid credentials\n- AuthorizationError: Insufficient permissions\n- ServerError: Unexpected server error\n","example":"ValidationError","enum":["ValidationError","NotFoundError","ConflictError","AuthenticationError","AuthorizationError","ServerError"]},"code":{"type":"string","description":"Common codes:\n- VALIDATION_FAILED: Request validation failed\n- RESOURCE_NOT_FOUND: Resource doesn't exist\n- RESOURCE_ALREADY_EXISTS: Duplicate resource\n- RESOURCE_CONFLICT: State conflict\n- AUTHENTICATION_FAILED: Invalid credentials\n- AUTHORIZATION_FAILED: Insufficient permissions\n- INTERNAL_ERROR: Server error\n","example":"VALIDATION_FAILED","enum":["VALIDATION_FAILED","RESOURCE_NOT_FOUND","RESOURCE_ALREADY_EXISTS","RESOURCE_CONFLICT","AUTHENTICATION_FAILED","AUTHORIZATION_FAILED","INTERNAL_ERROR"]},"message":{"type":"string","description":"Human-readable error message","example":"Request validation failed"},"details":{"type":"array","description":"Field-level validation errors (only present for validation_error type)","items":{"$ref":"#/components/schemas/UserService_ErrorResponse_error_details"}}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"BAD_REQUEST","message":"Invalid request parameters","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"pageSize must be between 1 and 100"}],"error":{"code":"BAD_REQUEST","message":"Invalid request parameters","details":null}}}}},"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"AUTHORIZATION_MISSING_TOKEN"}],"error":{"code":"UNAUTHORIZED","message":"AUTHORIZATION_MISSING_TOKEN","details":null}}}}},"Forbidden":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"FORBIDDEN","message":"Insufficient permissions","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Insufficient permissions"}],"error":{"code":"FORBIDDEN","message":"Insufficient permissions","details":null}}}}},"UnprocessableEntity":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"VALIDATION_ERROR","message":"Request validation failed","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"property":"status","message":"Must be a valid EmployeeStatus"},{"property":"pageSize","message":"Page size must be between 1 and 100"}],"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[{"field":"status","message":"Must be a valid EmployeeStatus"},{"field":"pageSize","message":"Page size must be between 1 and 100"}]}}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"An unexpected error occurred"}],"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred","details":null}}}}},"ServiceUnavailable":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"SERVICE_UNAVAILABLE","message":"A system error occurred","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"A system error occurred"}],"error":{"code":"SERVICE_UNAVAILABLE","message":"A system error occurred","details":null}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"NOT_FOUND","message":"The requested resource was not found","path":"/v1/employees/123","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"The requested resource was not found"}],"error":{"code":"NOT_FOUND","message":"The requested resource was not found","details":null}}}}},"Conflict":{"description":"Conflict - resource already exists or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"timestamp":"2026-03-19T10:15:30Z","code":"CONFLICT","message":"Resource already exists","path":"/v1/employees","correlationId":"4bf92f3577b34da6a3ce929d0e0e4736","errors":[{"message":"Resource already exists"}],"error":{"code":"CONFLICT","message":"Resource already exists","details":null}}}}}},"parameters":{"QueryPage":{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"style":"form","explode":true,"schema":{"minimum":1,"type":"integer","example":1,"default":1}},"QueryPageSize":{"name":"pageSize","in":"query","description":"Number of items per page","required":false,"style":"form","explode":true,"schema":{"maximum":100,"minimum":1,"type":"integer","example":20,"default":20}},"QueryStatus":{"name":"status","in":"query","description":"Filter by employment status","required":false,"style":"form","explode":true,"schema":{"$ref":"#/components/schemas/EmployeeStatus"},"example":"ACTIVE"},"QueryEmployeeId":{"name":"employeeId","in":"query","description":"Filter by employee ID (UUID, exact match)","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},"QueryEmployeeCode":{"name":"employeeCode","in":"query","description":"Filter by human-readable employee code (exact match)","required":false,"style":"form","explode":true,"schema":{"type":"string"},"example":"EMP-12345"},"QuerySortBy":{"name":"sortBy","in":"query","description":"Field to sort by. Currently only supports \"startOn\".","required":false,"style":"form","explode":true,"schema":{"$ref":"#/components/schemas/SortByField"},"example":"startOn"},"QuerySortOrder":{"name":"sortOrder","in":"query","description":"Sort direction","required":false,"style":"form","explode":true,"schema":{"$ref":"#/components/schemas/SortOrder"},"example":"DESC"},"PathEmployeeId":{"name":"employeeId","in":"path","description":"Unique identifier for the employee","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"123e4567-e89b-12d3-a456-426614174000"},"PathPayslipId":{"name":"payslipId","in":"path","description":"Unique identifier of the payslip","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"019f4b79-b3fe-7138-b4b6-1037923bb712"},"PathExpenseId":{"name":"expenseId","in":"path","description":"Unique identifier of the expense","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"550e8400-e29b-41d4-a716-446655440000"},"PathTimeOffId":{"name":"timeOffId","in":"path","description":"Unique identifier of the time off request","required":true,"style":"simple","explode":false,"schema":{"type":"string"},"example":"TO-001"},"PathTimesheetId":{"name":"timesheetId","in":"path","description":"Unique identifier of the timesheet","required":true,"style":"simple","explode":false,"schema":{"type":"string"},"example":"TS-001"},"PathCustomerId":{"name":"customerId","in":"path","description":"Customer ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c"},"PathDepartmentId":{"name":"departmentId","in":"path","description":"Department ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"},"example":"018e3b2a-1c4d-7f8e-9b0a-2d3e4f5a6b7c"}},"examples":{"CustomerListResponseFirstPage":{"summary":"First page of customers","description":"List of customers with pagination (page 1 of 3)","value":{"data":[{"id":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6","legalName":"Acme Corporation Pte Ltd","displayName":"Acme Corp","currency":"SGD","status":"ACTIVE"},{"id":"019a0ad5-75d6-7ca5-9995-d0ab28d119d2","legalName":"Beta Industries Ltd","displayName":"Beta Industries","currency":"GBP","status":"CREATED"},{"id":"019a0ad5-75d7-712f-861b-1589d92ee399","legalName":"Tech Innovations Inc","displayName":"Tech Innovations","currency":"USD","status":"ACTIVE"}],"pagination":{"page":1,"pageSize":20,"totalCount":45,"totalPages":3}}},"CustomerListResponseEmpty":{"summary":"Empty list (no customers)","description":"Response when partner has no customers yet","value":{"data":[],"pagination":{"page":1,"pageSize":20,"totalCount":0,"totalPages":0}}},"CustomerListResponseLastPage":{"summary":"Last page with fewer items","description":"Last page containing only 5 items","value":{"data":[{"id":"019a0ad5-75d8-7abd-987d-bf9881bb0801","legalName":"Global Services LLC","displayName":"Global Services","currency":"USD","status":"ACTIVE"},{"id":"019a0ad5-75d9-763c-a10a-1ee5a71cb2bf","legalName":"European Consulting GmbH","displayName":"European Consulting","currency":"EUR","status":"ACTIVE"}],"pagination":{"page":3,"pageSize":20,"totalCount":45,"totalPages":3}}},"CustomerCreateRequestMinimal":{"summary":"Minimal customer creation (required fields only)","description":"Create a customer with only required fields","value":{"legalName":"Acme Corporation Pte Ltd","currency":"SGD","country":"SGP"}},"CustomerCreateRequestComplete":{"summary":"Complete customer creation (all fields)","description":"Create a customer with all optional fields populated","value":{"legalName":"Acme Corporation Pte Ltd","displayName":"Acme Corp","registrationNumber":"202301234A","currency":"SGD","country":"SGP","address":{"line1":"123 Robinson Road","line2":"#15-01","city":"Singapore","postalCode":"068899","country":"SGP"}}},"CustomerCreateRequestUSA":{"summary":"US-based customer","description":"Create a customer based in the United States","value":{"legalName":"Tech Innovations Inc","displayName":"Tech Innovations","registrationNumber":"DE-123456789","currency":"USD","country":"USA","address":{"line1":"1234 Market Street","line2":"Suite 500","city":"San Francisco","state":"California","postalCode":"94103","country":"USA"}}},"CustomerResponsePending":{"summary":"Newly created customer (CREATED status)","description":"Customer just created","value":{"id":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6","legalName":"Acme Corporation Pte Ltd","displayName":"Acme Corp","currency":"SGD","status":"CREATED"}},"CustomerResponseActive":{"summary":"Active customer","description":"Fully operational customer","value":{"id":"019a0ad5-75d5-78d7-ad93-0ebb55da0eb6","legalName":"Acme Corporation Pte Ltd","displayName":"Acme Corp","currency":"SGD","status":"ACTIVE"}},"CustomerResponseMinimal":{"summary":"Customer without optional fields","description":"Customer created with only required fields","value":{"id":"019a0ad5-75d6-7ca5-9995-d0ab28d119d2","legalName":"Beta Industries Ltd","displayName":"Beta Industries Ltd","currency":"GBP","status":"ACTIVE"}},"CustomerUpdateRequestDisplayName":{"summary":"Update display name only","description":"Update just the customer display name","value":{"displayName":"Acme Corporation"}},"CustomerUpdateRequestAddress":{"summary":"Update address","description":"Update the customer's registered address","value":{"address":{"line1":"456 New Street","line2":"#20-05","city":"Singapore","postalCode":"049483","country":"SGP"}}},"CustomerUpdateRequestMultiple":{"summary":"Update fields","description":"Update display name","value":{"displayName":"Acme Corp International"}},"CustomerUpdateRequestActivate":{"summary":"Activate customer","description":"Change customer status from PENDING to ACTIVE","value":{"status":"ACTIVE"}},"CustomerUpdateRequestDeactivate":{"summary":"Deactivate customer","description":"Change customer status to INACTIVE","value":{"status":"INACTIVE"}},"CustomerUserListResponseFirstPage":{"summary":"First page of customer users","description":"Example of the first page of customer users with pagination","value":{"data":[{"id":"018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f","firstName":"John","lastName":"Doe","email":"john.doe@acme.com","role":"ADMIN","customerId":"018e3f7a-2b1c-7d8e-4f5a-6c7b8d9e0f1a"},{"id":"018e3f7a-4d5c-7e9f-1a2b-3c4d5e6f7a8b","firstName":"Jane","lastName":"Smith","email":"jane.smith@acme.com","role":"ADMIN","customerId":"018e3f7a-2b1c-7d8e-4f5a-6c7b8d9e0f1a"}],"pagination":{"page":1,"pageSize":20,"totalPages":3,"totalElements":45,"hasNext":true,"hasPrevious":false}}},"CustomerUserListResponseEmpty":{"summary":"Empty list of customer users","description":"Example when no customer users exist","value":{"data":[],"pagination":{"page":1,"pageSize":20,"totalPages":0,"totalElements":0,"hasNext":false,"hasPrevious":false}}},"CustomerUserListResponseLastPage":{"summary":"Last page of customer users","description":"Example of the last page with fewer items","value":{"data":[{"id":"018e3f7a-5e6d-7f8a-2b3c-4d5e6f7a8b9c","firstName":"Bob","lastName":"Johnson","email":"bob.johnson@acme.com","role":"ADMIN","customerId":"018e3f7a-2b1c-7d8e-4f5a-6c7b8d9e0f1a"}],"pagination":{"page":3,"pageSize":20,"totalPages":3,"totalElements":45,"hasNext":false,"hasPrevious":true}}},"CustomerUserCreateRequestAdmin":{"summary":"Create an admin user","description":"Example of creating an admin user for a customer","value":{"firstName":"John","lastName":"Doe","email":"john.doe@acme.com","role":"ADMIN"}},"CustomerUserResponseAdmin":{"summary":"Admin user created","description":"Example response after successfully creating an admin user","value":{"id":"018e3f7a-3c4b-7a1d-9f2e-5b8c6d4a1e3f","firstName":"John","lastName":"Doe","email":"john.doe@acme.com","role":"ADMIN","customerId":"018e3f7a-2b1c-7d8e-4f5a-6c7b8d9e0f1a"}}},"securitySchemes":{"BearerAuth":{"type":"http","description":"JWT Bearer token authentication.\n\nTo authenticate:\n1. Obtain a JWT token from your authentication endpoint\n2. Click the \"Authorize\" button above\n3. Enter your token in the format: your-jwt-token\n4. Click \"Authorize\" to apply to all requests\n\nThe token will be automatically included in the Authorization header\nas: Authorization: Bearer {token}\n","scheme":"bearer","bearerFormat":"JWT"}}}}