openapi: 3.0.1 info: version: 1.0.1 title: Leapsome API contact: name: Support url: https://leapsome.zendesk.com description: The Content API enables you to export some raw data from Leapsome for usage within your own systems and beyond what the Leapsome application offers natively. Usage is restricted to a maximum of 20 requests per second when making requests in parallel. If you exceed this limit, you will receive a 429 status code. servers: - url: https://api.leapsome.com/v1 paths: /: get: summary: API info operationId: apiInfo security: [] responses: '200': description: success content: application/json: schema: type: object properties: name: type: string example: Leapsome API version: type: string example: 1.0.0 /token: get: summary: Get JWT access token operationId: getToken security: [] tags: - auth parameters: - name: secret in: query required: true description: 'API Secret from [Leapsome admin page](www.leapsome.com:3000/app/#/team/settings/) ' schema: type: string example: yvpBwdF1kE74e2aXuzsG responses: '200': description: Authorization successfull content: application/json: schema: $ref: '#/components/schemas/AuthInfo' '401': description: Authorization failed. This usually means that `secret` is missing or is incorrect. /goals: get: summary: List goals description: 'Setting multiple filters will result in a subset of goals that satisfy *all* constraints. All filters except for `search` accept comma-separated values. ' operationId: listGoals security: - bearerAuth: [] tags: - goals parameters: - name: userId in: query required: false description: select goals containing *any* of the userIds. explode: false schema: type: array items: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a - name: teamId in: query required: false description: select goals containing *any* of the teamIds. explode: false schema: type: array items: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a - name: tagId in: query required: false description: select goals containing *all* of the tagIds. explode: false schema: type: array items: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a - name: type in: query required: false description: select goals that match by `type` to *any* of the types listed. explode: false schema: type: array items: type: string enum: - company - team - user - name: search in: query required: false description: 'search on title, user name and team name fields. Special symbols must be URL-encoded. Search is performed on a whole value of a text field, without splitting it into words (e.g. search for `ark` will match `Marketing`). ' schema: type: string - name: state in: query description: only include goals that match provided state explode: false schema: type: array items: type: string enum: - live - draft - archived - $ref: '#/components/parameters/limitParam' - $ref: '#/components/parameters/cursorParam' responses: '200': description: A paginated array of user goals headers: X-Next: $ref: '#/components/headers/X-Next' content: application/json: schema: $ref: '#/components/schemas/PaginatedGoals' examples: example-1: value: meta: count: 1 cursor: 58d55e3ffdc2eb20547edd0a nextPage: string data: - id: 5b237f6868794d5c08555812 type: user user: id: 58d55e3ffdc2eb20547edd0a email: example@example.com fullName: John Doe preferredName: John Doe team: id: 5b237f6868794d5c08555812 name: Rocket Scientists name: Become a great place to work (d) description: Make it entertaining contributors: - id: 58d55e3ffdc2eb20547edd0a email: example@example.com fullName: John Doe preferredName: John Doe progress: 50 status: live managedBy: id: 58d55e3ffdc2eb20547edd0a email: example@example.com fullName: John Doe preferredName: John Doe tags: - id: 5b237f6868794d5c08555812 name: string deadline: '2019-08-24T14:15:22Z' keyResults: - id: 5b237f6868794d5c08555812 name: Bring Glassdoor score up above 4 metric: type: currency start: 0 end: 1000 current: 650 weight: 30 ownerUser: id: 58d55e3ffdc2eb20547edd0a email: example@example.com fullName: John Doe preferredName: John Doe ownerTeam: id: 5b237f6868794d5c08555812 name: Engineer parent: _id: 5cb0855f0f089e6924b742e4 name: Enhance Employee Experience and Retention status: live progressStatus: onTrack createdAt: '2019-08-23T11:53:06.741Z' updatedAt: '2019-08-23T11:53:06.741Z' /goals/tags: get: summary: get list of goal tags operationId: listTags security: - bearerAuth: [] tags: - goals responses: '200': description: An array of goal tags content: application/json: schema: $ref: '#/components/schemas/Tags' /goals/{goalId}: get: summary: Get goal details operationId: getGoalDetails parameters: - in: path name: goalId required: true schema: type: string pattern: ^[0-9a-f]{24}$ description: ID of the goal security: - bearerAuth: [] tags: - goals responses: '200': description: Goal details content: application/json: schema: $ref: '#/components/schemas/Goal' /goals/{goalId}/comments: get: summary: get list of comments for a goal operationId: listGoalComments parameters: - in: path name: goalId required: true schema: type: string description: ID of the goal security: - bearerAuth: [] tags: - goals responses: '200': description: An array of goal comments ordered by creation date (descending) content: application/json: schema: $ref: '#/components/schemas/Comments' /goals/{goalId}/key-results/{keyResultId}: post: summary: Update key result operationId: updateKeyResult parameters: - in: path name: goalId required: true schema: type: string pattern: ^[0-9a-f]{24}$ description: ID of the goal - in: path name: keyResultId required: true schema: type: string pattern: ^[0-9a-f]{24}$ description: ID of the key result security: - bearerAuth: [] tags: - goals requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KeyResultUpdate' responses: '200': description: Updated goal content: application/json: schema: $ref: '#/components/schemas/Goal' /goals/{goalId}/initiatives/{initiativeId}: post: summary: Update initiative operationId: updateInitiative parameters: - in: path name: goalId required: true schema: type: string pattern: ^[0-9a-f]{24}$ description: ID of the goal - in: path name: initiativeId required: true schema: type: string pattern: ^[0-9a-f]{24}$ description: ID of the initiative security: - bearerAuth: [] tags: - goals requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InitiativeUpdate' responses: '200': description: Updated goal content: application/json: schema: $ref: '#/components/schemas/Goal' /reviews: get: summary: List review cycles description: Get a paginated list of all review cycles or templates in your Leapsome instance operationId: listReviews security: - bearerAuth: [] parameters: - name: filter in: query required: false description: 'Use predefined filters to filter the list: "all" gives all cycles, "draft" all draft cycles, "upcoming" all cycles that haven''t been launched yet, "ongoing" all currently ongoing cycles and "complete" all completed cycles. Use "templates" to filter for all templates.' explode: false schema: type: string items: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a enum: - all - draft - upcoming - ongoing - complete - schema: type: number in: query name: page description: Page number, starting at 0 - schema: type: number default: 20 in: query name: pageSize description: Page size for pagination - schema: type: string in: query name: template description: 'ID of the template that the cycle was created from (use filter = "templates" to filter for all templates) ' - schema: type: string in: query name: sort description: Sort by "creationDate" or "kickoffDate" (descending order) - schema: type: string in: query name: name description: Filter by review cycle name (partial match, case-insensitive) - schema: type: string in: query name: templateName description: Filter by template name (partial match, case-insensitive) - only returns cycles created from templates - schema: type: string format: date-time in: query name: conversationDeadlineAfter description: Filter for review cycles with conversation deadline after the specified date (ISO 8601 format) - schema: type: string format: date-time in: query name: lastModifiedAfter description: Filter for review cycles where any participant was last modified after the specified date (ISO 8601 format) responses: '200': description: A list of review cycles headers: {} content: application/json: schema: type: object x-examples: example-1: data: - _id: 5a869af092cf001f4ce73c26 name: Mid-2018 Biannual Performance Feedback status: complete properties: data: type: array items: type: object properties: _id: type: string name: type: string status: type: string enum: - new - draft - peerNominationsPending - peerApprovalPending - peerReviewsPending - managerReviewsPending - conversationsPending - complete createdAt: type: string format: date-time kickoffDate: type: string format: date-time description: Planned kickoff date template: type: string description: ID of the underlying template lastModifiedOn: type: string format: date-time description: Most recent modification date among any participant in the review cycle examples: example-1: value: data: - _id: 5a869af092cf001f4ce73c26 name: Performance Review Q1 2022 status: peerReviewsPending createdAt: '2018-02-16T08:48:48.363Z' kickoffDate: '2018-02-18T08:48:48.363Z' template: 63e42f779f7f18396a38f54d lastModifiedOn: '2018-02-20T10:15:30.000Z' tags: - reviews parameters: [] /reviews/{reviewCycleId}: get: summary: List review cycles description: Provides details of a specific review cycle operationId: getReviewDetails security: - bearerAuth: [] parameters: [] responses: '200': description: 'Details of a specific review cycle. ' headers: {} content: application/json: schema: type: object x-examples: example-1: data: _id: 5a869af092cf001f4ce73c26 name: Mid-2018 Biannual Performance Feedback status: complete questions: - _id: 58d55e55fdc2eb20547edd14 text: Drives innovation - _id: 58d55e55fdc2eb20547edd16 text: Delivers results - _id: 58d55e55fdc2eb20547edd0e text: Priorisiert effektiv - _id: 58d55e55fdc2eb20547edd0f text: Takes ownership - _id: 58d55e55fdc2eb20547edd20 text: Provides structure - _id: 58d55e55fdc2eb20547edd21 text: Manages expectations - _id: 58d55e55fdc2eb20547edd17 text: Communicates verbally - _id: 58d55e55fdc2eb20547edd18 text: Communicates in written - _id: 58d55e55fdc2eb20547edd1b text: Motivates - _id: 58d55e55fdc2eb20547edd1e text: Gibt Feedback - _id: 5a869af092cf001f4ce73c24 text: What was your biggest achievement? - _id: 5a869af092cf001f4ce73c25 text: What is this person's most important development goal? timeline: start: '2018-03-02T08:46:11.444Z' peerNominationsDeadline: '1970-01-01T00:00:00.000Z' peerApprovalDeadline: '1970-01-01T00:00:00.000Z' peerReviewsDeadline: '2018-04-13T08:46:11.444Z' managerReviewsDeadline: '2018-04-27T08:46:11.444Z' conversationsDeadline: '2018-05-07T08:46:11.444Z' createdAt: '2018-02-16T08:48:48.363Z' __v2: true properties: data: type: object properties: _id: type: string name: type: string status: type: string enum: - new - peerNominationsPending - peerApprovalPending - peerReviewsPending - managerReviewsPending - conversationsPending - complete questions: type: array items: type: object properties: _id: type: string name: type: string timeline: type: object properties: start: type: string format: date-time peerNominationsDeadline: type: string format: date-time peerApprovalDeadline: type: string format: date-time peerReviewsDeadline: type: string format: date-time managerReviewsDeadline: type: string format: date-time conversationsDeadline: type: string format: date-time createdAt: type: string format: date-time __v2: type: boolean ? '' : type: string examples: example-1: value: data: _id: 5a869af092cf001f4ce73c26 name: Performance Review Q2 status: complete questions: - _id: 58d55e55fdc2eb20547edd16 name: Delivers results - _id: 58d55e55fdc2eb20547edd0f name: Takes ownership - _id: 58d55e55fdc2eb20547edd20 name: Provides structure - _id: 58d55e55fdc2eb20547edd21 name: Manages expectations timeline: start: '2018-03-02T08:46:11.444Z' peerNominationsDeadline: '1970-01-01T00:00:00.000Z' peerApprovalDeadline: '1970-01-01T00:00:00.000Z' peerReviewsDeadline: '2018-04-13T08:46:11.444Z' managerReviewsDeadline: '2018-04-27T08:46:11.444Z' conversationsDeadline: '2018-05-07T08:46:11.444Z' createdAt: '2018-02-16T08:48:48.363Z' __v2: true tags: - reviews parameters: - schema: type: string name: reviewCycleId in: path required: true description: ID of your review cycle /reviews/{reviewCycleId}/participants: get: summary: List review cycle participants description: Provides a paginated list of cycle participants operationId: getReviewParticipants security: - bearerAuth: [] parameters: - schema: type: number in: query name: page description: Number of page, starting at 0 - schema: type: string default: '20' in: query name: pageSize description: Results per page responses: '200': description: Meta information for review cycle participants headers: X-Next: schema: type: string description: Next page content: application/json: schema: type: object x-examples: example-1: data: - _id: 58d55e3ffdc2eb20547edd0a reviewee: user: 58d55e3ffdc2eb20547edd0a name: Louise Leapsome preferredName: null status: pending averageRating: 0 / 100 managers: - user: 58d55e3ffdc2eb20547edd00 name: Peter Pan preferredName: null status: complete averageRating: 50 / 100 additionalManagers: - user: 58d625f5fdc2eb20547ede85 name: Jack Johnson preferredName: null status: pending averageRating: 0 / 100 peers: - user: 58d625f5fdc2eb20547ede83 name: Susanne Leader preferredName: null status: declined averageRating: 0 / 100 - user: 62ab64e3339234d9c4a527f2 name: Jason Minor preferredName: null status: complete averageRating: 75 / 100 directReports: - user: 62ab64e3339234d9c4a527f1 name: Sandra Susie preferredName: Sandra von Susie status: complete averageRating: 75 / 100 __v2: true properties: data: type: array items: type: object properties: _id: type: string reviewee: type: object properties: user: type: string name: type: string status: type: string enum: - pending - started - complete averageRating: type: string example: 7 / 10 managers: type: array items: type: object properties: user: type: string name: type: string status: type: string enum: - pending - started - complete averageRating: type: string example: 7 / 10 additionalManagers: type: array items: type: object properties: user: type: string name: type: string status: type: string enum: - pending - started - complete averageRating: type: string example: 7 / 10 peers: type: array items: type: object properties: user: type: string name: type: string status: type: string enum: - invited - pending - started - complete - declined averageRating: type: string example: 7 / 10 directReports: type: array items: type: object properties: user: type: string name: type: string status: type: string enum: - pending - started - complete averageRating: type: string example: 7 / 10 __v2: type: boolean examples: example-1: value: data: - _id: 58d55e3ffdc2eb20547edd0a signatureReviewee: '2025-03-04T13:15:11.574+00:00' signatureManager: '2025-03-04T13:15:11.574+00:00' lastModifiedOn: '2025-03-04T13:15:11.574+00:00' lastModifiedBy: 58d55e3ffdc2eb20547edd0a reviewee: user: 58d55e3ffdc2eb20547edd0a name: Louise Leapsome preferredName: null status: pending averageRating: 0 / 100 lastModifiedOn: '2025-03-04T13:15:11.574+00:00' lastModifiedBy: 58d55e3ffdc2eb20547edd0a managers: - user: 58d55e3ffdc2eb20547edd00 name: Peter Pan preferredName: null status: complete averageRating: 50 / 100 lastModifiedOn: '2025-03-04T13:15:11.574+00:00' lastModifiedBy: 58d55e3ffdc2eb20547edd00 additionalManagers: - user: 58d625f5fdc2eb20547ede85 name: Jack Johnson preferredName: null status: pending averageRating: 0 / 100 lastModifiedOn: '2025-03-04T13:15:11.574+00:00' lastModifiedBy: 58d625f5fdc2eb20547ede85 peers: - user: 58d625f5fdc2eb20547ede83 name: Susanne Leader preferredName: null status: declined averageRating: 0 / 100 lastModifiedOn: '2025-03-04T13:15:11.574+00:00' lastModifiedBy: 58d625f5fdc2eb20547ede83 - user: 62ab64e3339234d9c4a527f2 name: Jason Minor preferredName: null status: complete averageRating: 75 / 100 lastModifiedOn: '2025-03-04T13:15:11.574+00:00' lastModifiedBy: 62ab64e3339234d9c4a527f2 directReports: - user: 62ab64e3339234d9c4a527f1 name: Sandra Susie preferredName: Sandra von Susie status: complete averageRating: 75 / 100 lastModifiedOn: '2025-03-04T13:15:11.574+00:00' lastModifiedBy: 62ab64e3339234d9c4a527f1 __v2: true tags: - reviews parameters: - schema: type: string name: reviewCycleId in: path required: true description: ID of your review cycle /reviews/{reviewCycleId}/participants/{userId}/overview: get: summary: Get results for a specific reviewee description: Provides answers of all reviewers for a specific reviewee, if admins have access to these operationId: getReviewParticipantResults security: - bearerAuth: [] parameters: [] responses: '200': description: Relevant questions, answers (if visible) and contributor details (if not anonymous) headers: {} content: application/json: schema: type: object x-examples: example-1: data: lastModifiedOn: '2025-03-04T13:15:11.574+00:00' questions: - _id: 61f5656be4a7ef185491a621 name: Placeholder Company Skills - _id: 58d55e55fdc2eb20547edd16 name: Delivers results - _id: 58d55e55fdc2eb20547edd20 name: Provides structure - _id: 58d55e55fdc2eb20547edd14 name: Drives innovation - _id: 58d55e55fdc2eb20547edd0f name: Takes ownership - _id: 58d55e55fdc2eb20547edd21 name: Manages expectations - _id: 58d55e55fdc2eb20547edd18 name: Communicates in written - _id: 58d55e55fdc2eb20547edd1b name: Motivates - _id: 58d55e55fdc2eb20547edd17 name: Communicates verbally answers: - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd16 type: Peer Review rating: 4 scale: 6 comment: '' - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd20 type: Peer Review rating: 3 scale: 6 comment: '' - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd14 type: Peer Review rating: 4 scale: 6 comment: '' - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd0f type: Peer Review rating: 4 scale: 6 comment: '' - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd21 type: Peer Review rating: 6 scale: 6 comment: '' multipleChoice: A users: - _id: 58d625f5fdc2eb20547ede84 fullName: Susanne Leader preferredName: Susanne von Leader email: susanne@leapsome.com teams: Managers (Auto), Sales location: London lastModifiedOn: '2025-03-04T13:15:11.574+00:00' - _id: 62ac40b5f1f4baf9a1b6fb52 fullName: Louise Leapsome preferredName: Louise von Leapsome email: louise@leapsome.com teams: Managers (Auto), Marketing location: Berlin lastModifiedOn: '2025-03-04T13:15:11.574+00:00' __v2: true properties: data: type: object properties: questions: type: array items: type: object properties: _id: type: string example: 61f5656be4a7ef185491a621 name: type: string example: What's your overall feedback? average: type: number example: 75 minimum: 0 maximum: 100 exclusiveMinimum: false description: Normalized average score (0-100) of all answers to this question answers: type: array items: type: object properties: authorId: type: string example: 62ac40b5f1f4baf9a1b6fb52 receiverId: type: string example: 62ac40b5f1f4baf9a1b6fb52 question: type: string example: 61f5656be4a7ef185491a621 type: type: string enum: - Peer Review - Manager Review - Direct Report Review - Self-Evaluation rating: type: integer example: 7 scale: type: integer example: 10 comment: type: string example: Great job! multipleChoice: type: string example: A users: type: array items: type: object properties: _id: type: string example: 62ac40b5f1f4baf9a1b6fb52 fullName: type: string example: Jack Johnson preferredName: type: string example: Jack von Johnson (Full name) email: type: string format: email example: jack.johnson@leapsome.com teams: type: string example: Marketing, Sales location: type: string example: Berlin __v2: type: boolean examples: example-1: value: data: questions: - _id: 61f5656be4a7ef185491a621 name: Placeholder Company Skills average: 80 - _id: 58d55e55fdc2eb20547edd16 name: Delivers results average: 100 - _id: 58d55e55fdc2eb20547edd20 name: Provides structure average: 90 - _id: 58d55e55fdc2eb20547edd14 name: Drives innovation average: 90 - _id: 58d55e55fdc2eb20547edd0f name: Takes ownership average: 90 - _id: 58d55e55fdc2eb20547edd21 name: Manages expectations average: 70 - _id: 58d55e55fdc2eb20547edd18 name: Communicates in written average: 100 - _id: 58d55e55fdc2eb20547edd1b name: Motivates average: 80 - _id: 58d55e55fdc2eb20547edd17 name: Communicates verbally average: 70 answers: - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd16 type: Peer Review rating: 6 scale: 6 comment: Great job! - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd20 type: Peer Review rating: 3 scale: 6 comment: You can improve here - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd14 type: Peer Review rating: 4 scale: 6 comment: '' - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd0f type: Peer Review rating: 4 scale: 6 comment: '' - authorId: 62ac40b5f1f4baf9a1b6fb52 receiverId: 58d625f5fdc2eb20547ede84 question: 58d55e55fdc2eb20547edd21 type: Peer Review rating: 6 scale: 6 comment: '' users: - _id: 58d625f5fdc2eb20547ede84 fullName: Susanne Leader preferredName: Susanne Leader email: susanne@leapsome.com teams: Managers (Auto), Sales location: London - _id: 62ac40b5f1f4baf9a1b6fb52 fullName: Louise Leapsome preferredName: Louise Leapsome email: louise@leapsome.com teams: Managers (Auto), Marketing location: Berlin __v2: true tags: - reviews parameters: - schema: type: string name: reviewCycleId in: path required: true description: ID of your review cycle - schema: type: string name: userId in: path required: true /employees: get: summary: List employees description: Get a paginated list of employees with optional filtering by email, Leapsome ID, displayed name, or status. Returns basic employee information including teams, departments, and custom attributes. operationId: listEmployees security: - bearerAuth: [] tags: - users parameters: - name: email in: query required: false description: Filter by employee email address schema: type: string format: email - name: employeeId in: query required: false description: Filter by Leapsome user ID schema: type: string pattern: ^[0-9a-f]{24}$ - name: displayedName in: query required: false description: Filter by displayed name (partial match, case-insensitive) schema: type: string - name: status in: query required: false description: Filter by user status schema: type: string enum: - created - active - invited - removed - deactivated - preBoardingInvited - preBoardingActive - name: page in: query required: false description: Page number for pagination (starts at 1) schema: type: integer minimum: 1 default: 1 - name: pageSize in: query required: false description: Number of results per page schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: '200': description: A list of employees content: application/json: schema: $ref: '#/components/schemas/EmployeeList' '401': description: Authorization failed. Token is missing or invalid. /employees/{userId}/access-roles: put: summary: Update employee access roles description: 'Update the secondary access roles and user-specific access scope for one employee. Primary access roles cannot be updated through this endpoint. For roles with `userScopeType` set to `userSpecific`, provide a matching `accessRoleCustomConfigurations` entry. The public API only supports `include.users` in user-specific access scope configurations. Requires the standard Super Admin access role; for API tokens, assign that role to the API key. ' operationId: updateEmployeeAccessRoles security: - bearerAuth: [] tags: - users parameters: - name: userId in: path required: true description: Employee ID whose secondary access roles are being updated schema: type: string pattern: ^[0-9a-f]{24}$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateEmployeeAccessRolesRequest' responses: '200': description: Updated employee access roles content: application/json: schema: $ref: '#/components/schemas/UpdateEmployeeAccessRolesResponse' '400': description: Invalid request. Primary access roles are not allowed, roles must belong to the account, and USER_SPECIFIC roles require a matching include.users scope. '401': description: Authorization failed. Token is missing or invalid. '403': description: Insufficient permissions. Super Admin access role is required. '404': description: Employee not found. /time-tracking/timesheets: get: summary: List timesheets description: Get a paginated list of timesheets with optional filtering by username (email) or employee ID. Returns timesheet details including status, dates, and work hour calculations. Requires permission to manage time tracking policies. operationId: listTimesheets security: - bearerAuth: [] tags: - timeTracking parameters: - name: username in: query required: false description: Filter by employee email address schema: type: string format: email - name: employeeId in: query required: false description: Filter by Leapsome employee ID schema: type: string pattern: ^[0-9a-f]{24}$ - name: offset in: query required: false description: Number of results to skip schema: type: integer minimum: 0 default: 0 - name: limit in: query required: false description: Maximum number of results to return schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: '200': description: A list of timesheets content: application/json: schema: $ref: '#/components/schemas/TimesheetList' '401': description: Authorization failed. Token is missing or invalid. '403': description: Insufficient permissions. Permission to manage time tracking policies is required. /payroll-cycles: get: summary: List payroll cycles description: Get a paginated list of payroll cycles with optional filtering by name or status. Returns payroll cycle details including dates, status, and compensation configuration. Requires permission to manage payroll policies. operationId: listPayrollCycles security: - bearerAuth: [] tags: - payroll parameters: - name: name in: query required: false description: Filter by payroll cycle name (partial match, case-insensitive) schema: type: string - name: status in: query required: false description: Filter by payroll cycle status schema: type: string enum: - draft - active - completed - archived - name: offset in: query required: false description: Number of results to skip schema: type: integer minimum: 0 default: 0 - name: limit in: query required: false description: Maximum number of results to return schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: '200': description: A list of payroll cycles content: application/json: schema: $ref: '#/components/schemas/PayrollCycleList' '401': description: Authorization failed. Token is missing or invalid. '403': description: Insufficient permissions. Permission to manage payroll policies is required. /payroll-cycles/{payrollCycleId}/participants: get: summary: List payroll cycle participants description: Get participants for a specific payroll cycle with optional filtering by username (email) or employee ID. Requires permission to manage payroll policies. operationId: listPayrollCycleParticipants security: - bearerAuth: [] tags: - payroll parameters: - name: payrollCycleId in: path required: true description: ID of the payroll cycle schema: type: string pattern: ^[0-9a-f]{24}$ - name: username in: query required: false description: Filter by employee email address schema: type: string format: email - name: employeeId in: query required: false description: Filter by Leapsome employee ID schema: type: string pattern: ^[0-9a-f]{24}$ - name: offset in: query required: false description: Number of results to skip schema: type: integer minimum: 0 default: 0 - name: limit in: query required: false description: Maximum number of results to return schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: '200': description: A list of payroll cycle participants content: application/json: schema: $ref: '#/components/schemas/PayrollCycleParticipantList' '401': description: Authorization failed. Token is missing or invalid. '403': description: Insufficient permissions. Permission to manage payroll policies is required. '404': description: Payroll cycle not found. /work-locations: get: summary: List work locations description: Get a paginated list of work locations with optional filtering by ID, name, or status. Returns full work location details including address information. operationId: listWorkLocations security: - bearerAuth: [] tags: - workLocations parameters: - name: workLocationId in: query required: false description: Filter by specific work location ID schema: type: string pattern: ^[0-9a-f]{24}$ - name: name in: query required: false description: Filter by work location name (partial match, case-insensitive) schema: type: string - name: status in: query required: false description: Filter by work location status schema: type: string enum: - active - inactive - name: page in: query required: false description: Page number for pagination (starts at 1) schema: type: integer minimum: 1 maximum: 1000 default: 1 - name: pageSize in: query required: false description: Number of results per page schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: '200': description: A list of work locations content: application/json: schema: $ref: '#/components/schemas/WorkLocationList' '401': description: Authorization failed. Token is missing or invalid. /absences: get: summary: List absences description: "Get a paginated list of absences in your Leapsome instance. You can filter by date range, \nstatus, and\ \ user. Requires admin permissions for absence management.\n" operationId: listAbsences security: - bearerAuth: [] tags: - absences parameters: - name: absenceStartFrom in: query required: false description: Filter absences that start on or after this date schema: type: string format: date-time example: '2024-01-01T00:00:00.000Z' - name: absenceStartUntil in: query required: false description: Filter absences that start on or before this date schema: type: string format: date-time example: '2024-12-31T23:59:59.999Z' - name: status in: query required: false description: Filter by absence status schema: type: string enum: - active - removed - pendingRemoval - name: userId in: query required: false description: Filter absences for a specific user schema: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a - name: page in: query required: false description: Page number for pagination (starts at 1) schema: type: integer minimum: 1 maximum: 1000 default: 1 - name: pageSize in: query required: false description: Number of results per page schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: '200': description: A list of absences content: application/json: schema: type: array items: $ref: '#/components/schemas/Absence' examples: example-1: value: - _id: 66a1b2c3d4e5f6789012345a createdAt: '2024-01-15T08:30:00.000Z' updatedAt: '2024-01-15T08:30:00.000Z' userId: 58d55e3ffdc2eb20547edd0a start: '2024-02-01T00:00:00.000Z' end: '2024-02-05T23:59:59.999Z' absenceType: paidVacation activityType: nonWorkingPaid status: active timeUnit: days actualAbsenceDuration: 5 - _id: 66a1b2c3d4e5f6789012345b createdAt: '2024-01-20T09:15:00.000Z' updatedAt: '2024-01-20T09:15:00.000Z' userId: 58d55e3ffdc2eb20547edd0b start: '2024-03-10T00:00:00.000Z' end: '2024-03-12T23:59:59.999Z' absenceType: sickLeave activityType: nonWorkingPaid status: active timeUnit: days actualAbsenceDuration: 3 '401': description: Authorization failed. Token is missing or invalid. '403': description: Insufficient permissions. Admin access to absence management is required. /feedback: get: summary: List feedback description: 'Get a paginated list of instant feedback and praise items. Supports filtering by type (praise or instantFeedback), sender, and receiver. ' operationId: listFeedback security: - bearerAuth: [] tags: - feedback parameters: - name: type in: query required: false description: Filter by feedback type schema: type: string enum: - praise - instantFeedback - name: receiverId in: query required: false description: Filter by receiver user ID schema: type: string pattern: ^[0-9a-f]{24}$ - name: senderId in: query required: false description: Filter by sender user ID schema: type: string pattern: ^[0-9a-f]{24}$ - name: offset in: query required: false description: Number of results to skip schema: type: integer minimum: 0 default: 0 - name: limit in: query required: false description: Maximum number of results to return schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: '200': description: A list of feedback items content: application/json: schema: $ref: '#/components/schemas/FeedbackList' '401': description: Authorization failed. Token is missing or invalid. /feedback/praise: post: summary: Create praise description: 'Create a new praise item. Requires the instant feedback praise permission. Returns the ID of the created feedback. ' operationId: createPraise security: - bearerAuth: [] tags: - feedback requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePraiseRequest' responses: '201': description: Praise created successfully content: application/json: schema: $ref: '#/components/schemas/CreatePraiseResponse' '401': description: Authorization failed. Token is missing or invalid. '403': description: Insufficient permissions. Praise permission is required. /feedback/instant: post: summary: Create instant feedback description: 'Create instant feedback for a user. By default only visible to the receiver. Requires the instant feedback permission. ' operationId: createInstantFeedback security: - bearerAuth: [] tags: - feedback requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateInstantFeedbackRequest' responses: '201': description: Instant feedback created successfully content: application/json: schema: $ref: '#/components/schemas/CreateFeedbackResponse' '401': description: Authorization failed. Token is missing or invalid. '403': description: Insufficient permissions. Instant feedback permission is required. /feedback/private-note: post: summary: Create private note description: 'Create a private note about a user. Private notes are only visible to the sender and cannot be seen by the receiver or anyone else. ' operationId: createPrivateNote security: - bearerAuth: [] tags: - feedback requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePrivateNoteRequest' responses: '201': description: Private note created successfully content: application/json: schema: $ref: '#/components/schemas/CreateFeedbackResponse' '401': description: Authorization failed. Token is missing or invalid. /documents/categories: get: summary: List document categories description: 'List all active user document categories for the team. Use the returned category IDs when uploading documents via the upload endpoint. ' operationId: listDocumentCategories security: - bearerAuth: [] tags: - documents responses: '200': description: List of document categories content: application/json: schema: type: array items: $ref: '#/components/schemas/DocumentCategory' '401': description: Authorization failed. Token is missing or invalid. /users/{userId}/documents: post: summary: Upload user document description: 'Upload a document to a user''s profile in a single request. Send the file as multipart/form-data along with the target category. The backend handles storage and confirmation automatically. Maximum file size: 25 MB. ' operationId: uploadUserDocument security: - bearerAuth: [] tags: - documents parameters: - name: userId in: path required: true description: Leapsome user ID of the document owner schema: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/UploadUserDocumentRequest' responses: '201': description: Document uploaded successfully content: application/json: schema: $ref: '#/components/schemas/UploadUserDocumentResponse' '400': description: Invalid request. File extension or MIME type not allowed, or file exceeds size limit. '401': description: Authorization failed. Token is missing or invalid. '403': description: No upload permission for the specified category. '404': description: User not found. /access-roles: get: summary: List access roles description: 'Get a list of all access roles for the account. Returns role details including name, scope type, and system default information. Requires the standard Super Admin access role; for API tokens, assign that role to the API key. ' operationId: listAccessRoles security: - bearerAuth: [] tags: - accessRoles responses: '200': description: List of access roles content: application/json: schema: type: array items: $ref: '#/components/schemas/PublicAccessRole' '401': description: Authorization failed. Token is missing or invalid. '403': description: Insufficient permissions. Super Admin access role is required. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT headers: X-Next: description: A link to the next page of responses schema: type: string format: url example: https://api.leapsome.com/v1/goals?cursor=58d55e3ffdc2eb20547edd0a&limit=100 parameters: cursorParam: name: cursor in: query required: false description: 'Start showing results from this location. Typically, you do not need to set this parameter manually, it is mainly used in "x-next" header ' schema: type: string pattern: ^[0-9a-f]{24}$ limitParam: name: limit in: query description: Maximal number of results in a response schema: type: integer minimum: 1 maximum: 1000 default: 100 schemas: AuthInfo: type: object required: - token - expiresIn properties: token: type: string example: expiresIn: type: integer description: seconds until the token expires example: 18000 PaginatedGoals: type: object properties: meta: $ref: '#/components/schemas/Meta' data: type: array items: $ref: '#/components/schemas/Goal' Meta: type: object required: - count - cursor - nextPage properties: count: type: integer description: number of results returned in this request minimum: 1 maximum: 1000 cursor: type: string description: 'Will be set to `null` if complete set have been returned. ' pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a nullable: true nextPage: type: string format: url description: URL of the next result page. `null` means no more results available. nullable: true User: type: object required: - id - email - fullName properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a email: type: string format: email example: example@example.com fullName: type: string example: John Doe preferredName: type: string example: John von Doe (Full name) Comments: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Comment' Comment: type: object required: - id - content - sender - createdAt - updatedAt properties: id: type: string content: type: string description: The comment body which can contain html tags sender: type: object required: - id - firstname - lastname - picture properties: id: type: string firstname: type: string lastname: type: string picture: type: string format: url createdAt: type: string format: date-time example: '2019-08-23T11:53:06.741Z' updatedAt: type: string format: date-time example: '2019-08-23T11:53:06.741Z' Goal: type: object required: - id - type - name - description - contributors - progress - status - managedBy - tags - deadline - keyResults - parent - createdAt - updatedAt properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 5b237f6868794d5c08555812 type: type: string enum: - user - team - company example: user user: allOf: - $ref: '#/components/schemas/User' - nullable: true description: 'Information about the user, who''s assigned to this goal. Will be `null` for Team and Company goals. ' team: type: object nullable: true description: 'Information about the team, that''s assigned to this goal. Will be `null` for User and Company goals. ' properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 5b237f6868794d5c08555812 name: type: string example: Rocket Scientists name: type: string example: Become a great place to work (d) description: type: string example: Make it entertaining contributors: type: array items: $ref: '#/components/schemas/User' progress: type: integer minimum: 0 maximum: 100 example: 50 status: type: string enum: - archived - live - draft - removed example: live managedBy: $ref: '#/components/schemas/User' tags: type: array items: type: object required: - id - name properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 5b237f6868794d5c08555812 name: type: string deadline: type: string format: date-time nullable: true keyResults: type: array items: $ref: '#/components/schemas/KeyResults' parent: $ref: '#/components/schemas/ParentGoal' progressStatus: type: string enum: - onTrack - offTrack - inputNeeded - done - canceled nullable: true createdAt: type: string format: date-time example: '2019-08-23T11:53:06.741Z' updatedAt: type: string format: date-time example: '2019-08-23T11:53:06.741Z' KeyResults: type: object required: - id - name - metric - weight - ownerTeam - ownerUser - contributors - contributorTeams properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 5b237f6868794d5c08555812 name: type: string example: Bring Glassdoor score up above 4 metric: type: object required: - type - start - end - current properties: type: type: string example: currency enum: - none - numerical - percentage - currency start: type: integer end: type: integer current: type: integer weight: type: integer minimum: 0 maximum: 100 example: 30 ownerUser: $ref: '#/components/schemas/User' ownerTeam: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 5b237f6868794d5c08555812 name: type: string example: Engineer contributors: type: array items: $ref: '#/components/schemas/User' contributorTeams: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 5b237f6868794d5c08555812 name: type: string example: Engineer Tags: type: array items: $ref: '#/components/schemas/Tag' Tag: type: object required: - id - name - status - createdAt - updatedAt properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 5b237f6868794d5c08555812 name: type: string example: Marketing status: type: string enum: - active - viewOnly - removed createdAt: type: string format: date-time example: '2019-08-23T11:53:06.741Z' updatedAt: type: string format: date-time example: '2019-08-23T11:53:06.741Z' KeyResultUpdate: type: object properties: name: type: string example: Bring Glassdoor score up above 4 metric: type: object required: - type - start - end - current properties: type: type: string enum: - none - numerical - percentage - currency start: type: integer end: type: integer current: type: integer weight: type: integer minimum: 0 maximum: 100 InitiativeUpdate: type: object properties: name: type: string description: type: string status: type: string enum: - notStarted - inProgress - completed - blocked ParentGoal: type: object nullable: true properties: _id: type: string pattern: ^[0-9a-f]{24}$ example: 5cb0855f0f089e6924b742e4 name: type: string example: Enhance Employee Experience and Retention status: type: string enum: - live - draft - archived example: live Absence: type: object required: - _id - createdAt - updatedAt - userId - start - end - absenceType - activityType - status - timeUnit properties: _id: type: string pattern: ^[0-9a-f]{24}$ example: 66a1b2c3d4e5f6789012345a description: Unique identifier for the absence createdAt: type: string format: date-time example: '2024-01-15T08:30:00.000Z' description: When the absence was created updatedAt: type: string format: date-time example: '2024-01-15T08:30:00.000Z' description: When the absence was last modified userId: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a description: ID of the user taking the absence start: type: string format: date-time example: '2024-02-01T00:00:00.000Z' description: Start date and time of the absence startDayTime: type: string example: 09:00 description: Start time of the absence (HH:mm format) startDayDuration: type: string enum: - fullDay - halfDayMorning - halfDayAfternoon example: fullDay description: Duration type for the start day of the absence end: type: string format: date-time example: '2024-02-05T23:59:59.999Z' description: End date and time of the absence endDayTime: type: string example: '17:00' description: End time of the absence (HH:mm format) endDayDuration: type: string enum: - fullDay - halfDayMorning - halfDayAfternoon example: fullDay description: Duration type for the end day of the absence absenceType: type: string enum: - paidVacation - sickLeave - parentalLeave - unpaidVacation - familyCare - childCare - shortTermAllowance - quarantine - lockout - irrevocableExemption - voluntaryMilitaryService - unlawfulStrike - lawfulStrike - unexcusedAbsence - remoteWork - otherPaidLeave - educationalLeave - gardenLeave - longtermSickLeave example: paidVacation description: Type of absence being taken activityType: type: string enum: - nonWorkingPaid - nonWorkingUnpaid - working - nonWorkingPartiallyPaid example: nonWorkingPaid description: Activity type classification of the absence status: type: string enum: - active - removed - pendingRemoval example: active description: Current status of the absence timeUnit: type: string enum: - days - hours example: days description: Unit of time used for measuring the absence duration comment: type: string example: Medical appointment description: Optional comment or note about the absence actualAbsenceDuration: type: number nullable: true example: 5 description: Actual duration of the absence in the specified time unit EmployeeList: type: object properties: data: type: array items: $ref: '#/components/schemas/Employee' meta: type: object properties: page: type: integer description: Current page number pageSize: type: integer description: Number of items per page totalCount: type: integer description: Total number of employees Employee: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a description: Leapsome user ID email: type: string format: email example: jane.doe@example.com description: Employee email address firstname: type: string example: Jane description: Employee first name lastname: type: string example: Doe description: Employee last name middlename: type: string example: von description: Employee middle name fullname: type: string example: Jane Doe description: Employee full name displayedName: type: string example: Jane von Doe description: Employee displayed/preferred name status: type: string enum: - created - active - invited - deactivated - preBoardingInvited - preBoardingActive - removed example: active description: Current status of the employee lifecycleStatus: type: string enum: - hired - active - leave - offboarding - terminated - deactivated - notSet - preBoarding example: active description: Current lifecycle status of the employee manager: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string additionalManagers: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string example: Jane Doe indirectManagers: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string example: John Doe startDate: type: string format: date-time example: '2024-01-01T00:00:00.000Z' description: Employee start date endDate: type: string format: date-time example: '2024-12-31T23:59:59.999Z' description: Employee end date phone: type: string example: '+1234567890' description: Employee phone number teams: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string example: Team Red description: Teams the employee belongs to departments: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string example: Department Blue description: Departments the employee belongs to businessUnits: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string example: Business Unit Green description: Business units the employee belongs to costCenters: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string example: Cost Center Yellow description: Cost centers the employee belongs to divisions: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string example: Division Purple description: Divisions the employee belongs to otherGroups: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string example: Other Group Orange description: Other groups the employee belongs to level: type: string example: Senior description: Employee's level title: type: string example: Software Engineer description: Employee's job title workLocation: type: object nullable: true properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string example: Berlin Office description: Employee's work location compensation: type: object nullable: true properties: salary: type: number example: 75000 description: Employee's salary amount currency: type: string example: EUR description: Currency of the salary frequency: type: string enum: - year - month - hour example: year description: Salary remuneration period description: Employee's compensation information additionalCompensations: type: array nullable: true items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a description: Compensation ID name: type: string example: Annual Bonus description: Name of the compensation amount: type: number nullable: true example: 5000 description: Amount of the compensation amountType: type: string nullable: true enum: - fixed - variable example: fixed description: Type of the compensation amount recurrence: type: string enum: - oneTime - monthly - every3Months - every6Months - every12Months example: every12Months description: Recurrence of the compensation comment: type: string nullable: true example: Performance bonus description: Comment for the compensation effectiveAt: type: string format: date-time example: '2024-01-01T00:00:00.000Z' description: Effective date of the compensation validUntil: type: string format: date-time nullable: true example: '2024-12-31T23:59:59.999Z' description: Valid until date of the compensation description: Employee's additional compensations customAttributes: type: object additionalProperties: true description: Custom attributes defined for the employee WorkLocationList: type: object properties: data: type: array items: $ref: '#/components/schemas/WorkLocation' meta: type: object properties: page: type: integer description: Current page number pageSize: type: integer description: Number of items per page totalCount: type: integer description: Total number of work locations WorkLocation: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a description: Work location ID name: type: string example: Berlin Office description: Name of the work location status: type: string enum: - active - inactive example: active description: Current status of the work location remote: type: boolean nullable: true example: false description: Whether this is a remote work location currency: type: string nullable: true example: EUR description: Default currency for this work location street: type: string nullable: true example: 123 Main Street description: Street address zip: type: string nullable: true example: '10115' description: ZIP/postal code city: type: string nullable: true example: Berlin description: City administrativeDivision: type: string nullable: true example: Berlin description: State/province/administrative division country: type: string nullable: true example: Germany description: Country dateFormat: type: string nullable: true enum: - MM-DD-YYYY - DD-MM-YYYY - YYYY-MM-DD - MM/DD/YYYY - DD/MM/YYYY - YYYY/MM/DD - DD.MM.YYYY - MMMM DD, YYYY - DD MMMM YYYY - YYYY MMMM DD example: DD.MM.YYYY description: Date format used in this work location primary: type: boolean nullable: true example: true description: Whether this is the primary work location createdAt: type: string format: date-time nullable: true example: '2024-01-15T08:30:00.000Z' description: When the work location was created updatedAt: type: string format: date-time nullable: true example: '2024-01-20T10:15:00.000Z' description: When the work location was last updated TimesheetList: type: object properties: data: type: array items: $ref: '#/components/schemas/Timesheet' meta: type: object properties: page: type: integer description: Current page number pageSize: type: integer description: Number of items per page totalCount: type: integer description: Total number of timesheets Timesheet: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a description: Timesheet ID user: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a name: type: string email: type: string format: email example: jane.doe@example.com description: Employee email address status: type: string enum: - open - pendingApproval - closed example: open description: Current status of the timesheet startDate: type: string format: date-time description: Start date of the timesheet period endDate: type: string format: date-time description: End date of the timesheet period hoursWorked: type: string example: PT10H description: Total hours worked in the period (duration in ISO 8601 format) compensableHours: type: string example: PT10H description: Total compensable hours in the period (duration in ISO 8601 format) overtimeHours: type: string example: PT10H description: Total overtime hours in the period (duration in ISO 8601 format) workDuration: type: string example: PT10H description: Total work duration in the period (duration in ISO 8601 format) projects: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ title: type: string description: Projects the employee worked on in the timesheet period PayrollCycleList: type: object properties: data: type: array items: $ref: '#/components/schemas/PayrollCycle' meta: type: object properties: page: type: integer description: Current page number pageSize: type: integer description: Number of items per page totalCount: type: integer description: Total number of payroll cycles PayrollCycle: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a description: Payroll cycle ID name: type: string example: Q1 2024 Payroll description: Name of the payroll cycle status: type: string enum: - open - pendingApproval - approved - overdue - future - reopened example: open description: Current status of the payroll cycle startAt: type: string format: date-time description: Start date of the payroll period endAt: type: string format: date-time description: End date of the payroll period customPeriodStartAt: type: string format: date-time description: Start date of the custom period customPeriodEndAt: type: string format: date-time description: End date of the custom period reviewStartAt: type: string format: date-time description: Start date of the review period approvalStartAt: type: string format: date-time description: Start date of the approval period approvedAt: type: string format: date-time description: Date when the payroll cycle was approved approvedBy: type: string pattern: ^[0-9a-f]{24}$ description: User ID of the user who approved the payroll cycle prorateType: type: string enum: - weekly - biWeekly - semiMonthly - thirtyDays - actualNumberOfMonthDays example: weekly description: Type of prorate used for the payroll cycle compensations: type: object properties: salaryTypeCustomName: type: string description: Custom name for the salary type baseSalaryCustomName: type: string description: Custom name for the base salary salaryPerHourCustomName: type: string description: Custom name for the salary per hour compensableTimeCustomName: type: string description: Custom name for the compensable time hoursWorkedCustomName: type: string description: Custom name for the hours worked paidAbsencesCustomName: type: string description: Custom name for the paid absences createdAt: type: string format: date-time description: When the payroll cycle was created updatedAt: type: string format: date-time description: When the payroll cycle was last updated PayrollCycleParticipantList: type: object properties: data: type: array items: $ref: '#/components/schemas/PayrollCycleParticipant' meta: type: object properties: page: type: integer description: Current page number pageSize: type: integer description: Number of items per page totalCount: type: integer description: Total number of participants PayrollCycleParticipant: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a description: Payroll cycle participant ID name: type: string example: John Doe description: Name of the participant email: type: string format: email example: jane.doe@example.com description: Email address of the participant compensations: type: array items: type: object properties: name: type: string description: Name of the compensation amount: type: number description: Amount of the compensation amountType: type: string enum: - fixed - variable description: Type of the compensation recurrence: type: string enum: - monthly - every3Months - every6Months - every12Months description: Recurrence of the compensation comment: type: string description: Comment for the compensation effectiveAt: type: string format: date-time description: Effective date of the compensation validUntil: type: string format: date-time description: Valid until date of the compensation salaryInfoPeriods: type: array items: type: object properties: currency: type: string salary: type: number description: Salary for the period salaryRemunerationPeriod: type: string enum: - year - month - hour description: Remuneration period of the salary compensationType: type: string enum: - fixed - hourly description: Type of the compensation baseSalary: type: number description: Base salary for the period isActiveParticipant: type: boolean description: Whether the participant is active in the payroll cycle FeedbackList: type: object properties: data: type: array items: $ref: '#/components/schemas/FeedbackItem' meta: type: object properties: offset: type: integer description: Number of results skipped limit: type: integer description: Maximum number of results returned totalCount: type: integer description: Total number of feedback items FeedbackItem: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 58d55e3ffdc2eb20547edd0a description: Feedback item ID type: type: string enum: - praise - instantFeedback description: Type of feedback sender: type: object nullable: true properties: id: type: string pattern: ^[0-9a-f]{24}$ nullable: true description: Sender user ID (null if anonymous) name: type: string description: Sender display name ("Anonymous" if anonymous) description: The user who sent the feedback receivers: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Receiver user or team ID name: type: string description: Receiver display name description: Users or teams who received the feedback message: type: string nullable: true description: The feedback message content badge: type: object nullable: true properties: name: type: string description: Badge name icon: type: string description: Badge icon path description: Badge attached to the feedback (praise only) visibility: type: string enum: - public - receiver - senderOnly description: Visibility level of the feedback createdAt: type: string format: date-time description: When the feedback was created likesCount: type: integer description: Number of likes on the feedback commentsCount: type: integer description: Number of comments on the feedback CreatePraiseRequest: type: object required: - senderId - receiverIds - message properties: senderId: type: string pattern: ^[0-9a-f]{24}$ description: User ID of the sender receiverIds: type: array items: type: string pattern: ^[0-9a-f]{24}$ minItems: 1 description: User IDs of the praise receivers message: type: string minLength: 1 description: The praise message content visibility: type: string enum: - public - receiver default: public description: Visibility level of the praise CreatePraiseResponse: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: ID of the created feedback item CreateInstantFeedbackRequest: type: object required: - senderId - receiverId - message properties: senderId: type: string pattern: ^[0-9a-f]{24}$ description: User ID of the sender receiverId: type: string pattern: ^[0-9a-f]{24}$ description: User ID of the feedback receiver message: type: string minLength: 1 description: The feedback message content visibility: type: string enum: - public - receiver - manager - senderOnly default: receiver description: Visibility level of the feedback CreatePrivateNoteRequest: type: object required: - senderId - receiverId - message properties: senderId: type: string pattern: ^[0-9a-f]{24}$ description: User ID of the sender receiverId: type: string pattern: ^[0-9a-f]{24}$ description: User ID the private note is about message: type: string minLength: 1 description: The private note content CreateFeedbackResponse: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: ID of the created feedback item UploadUserDocumentRequest: type: object required: - file - category properties: file: type: string format: binary description: The document file to upload (max 25 MB) category: type: string pattern: ^[0-9a-f]{24}$ description: ID of the user document category (from GET /documents/categories) example: 58d55e3ffdc2eb20547edd0a description: type: string description: Optional human-readable description for the document example: Annual performance review for 2024 UploadUserDocumentResponse: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: ID of the uploaded document example: 58d55e3ffdc2eb20547edd0a DocumentCategory: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Category ID. Use this value as the `category` field when uploading documents. example: 58d55e3ffdc2eb20547edd0a name: type: string description: Display name of the category example: Past Reviews PublicAccessRole: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Access role ID name: type: string description: Display name of the access role userScopeType: type: string enum: - none - roleSpecific - userSpecific description: How user scope is determined for this role isSystemDefault: type: boolean description: Whether this is a built-in system role systemDefaultType: type: string description: System default role identifier when `isSystemDefault` is true active: type: boolean description: Whether the role is active UpdateEmployeeAccessRolesRequest: type: object required: - accessRoleIds properties: accessRoleIds: type: array items: type: string pattern: ^[0-9a-f]{24}$ description: Full desired set of secondary access role IDs for the employee. Primary access role IDs are not allowed. accessRoleCustomConfigurations: type: array description: User-specific scope configurations for access roles with `userScopeType` set to `userSpecific`. Only `include.users` is supported. items: $ref: '#/components/schemas/PublicUserAccessRoleCustomConfiguration' UpdateEmployeeAccessRolesResponse: type: object properties: userId: type: string pattern: ^[0-9a-f]{24}$ accessRoleIds: type: array items: type: string pattern: ^[0-9a-f]{24}$ accessRoleCustomConfigurations: type: array items: $ref: '#/components/schemas/PublicUserAccessRoleCustomConfiguration' PublicUserAccessRoleCustomConfiguration: type: object required: - accessRole - userSpecificAccessScope additionalProperties: false properties: accessRole: type: string pattern: ^[0-9a-f]{24}$ description: Access role ID this custom user scope belongs to userSpecificAccessScope: $ref: '#/components/schemas/PublicUserSpecificAccessScope' PublicUserSpecificAccessScope: type: object required: - include additionalProperties: false properties: include: type: object required: - users additionalProperties: false properties: users: type: array minItems: 1 items: type: string pattern: ^[0-9a-f]{24}$ description: User IDs the target employee may access when using this role