openapi: 3.0.3
info:
  title: Lattice Talent API
  description: >
    REST API for Lattice's Talent product suite covering users, departments,
    goals, OKRs, performance review cycles, reviewees, reviews, continuous
    feedback, competencies, and tags. Uses cursor-based pagination and Bearer
    token authentication.
  version: v1
  contact:
    name: Lattice Developer Support
    email: customercare@lattice.com
    url: https://developers.lattice.com
  termsOfService: https://lattice.com/legal/terms-of-service
  license:
    name: Proprietary
    url: https://lattice.com/legal/terms-of-service
servers:
  - url: https://api.latticehq.com/v1
    description: Lattice Talent API v1 production server

security:
  - BearerAuth: []

tags:
  - name: Users
    description: Manage and retrieve user records
  - name: Departments
    description: Manage and retrieve department records
  - name: Goals
    description: Create, read, and update goals and OKRs
  - name: Goal Updates
    description: Create and retrieve goal progress updates
  - name: Feedbacks
    description: Retrieve continuous feedback
  - name: Review Cycles
    description: Manage performance review cycles
  - name: Reviewees
    description: Manage reviewees within a review cycle
  - name: Reviews
    description: Submit and update performance reviews
  - name: Tags
    description: Retrieve tags used across goals and feedback
  - name: Competencies
    description: Retrieve competencies
  - name: Me
    description: Retrieve information about the authenticated user

paths:

  /me:
    get:
      summary: Get authenticated user
      operationId: getMe
      tags: [Me]
      description: Returns information about the current user associated with the provided API token.
      responses:
        "200":
          description: Authenticated user object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /users:
    get:
      summary: List users
      operationId: listUsers
      tags: [Users]
      description: >
        Returns a paginated list of users in Lattice. By default, returns
        active users. A status parameter of NULL will retrieve all users
        regardless of status.
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [ACTIVE, INVITED, CREATED, DEACTIVATED, NULL]
          description: Filter by user status; NULL returns all users.
      responses:
        "200":
          description: Paginated list of users
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /user/{id}:
    get:
      summary: Get user by ID
      operationId: getUser
      tags: [Users]
      description: Returns a user with the given id. If cannot find user, returns a 404.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The user identifier
      responses:
        "200":
          description: User object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /departments:
    get:
      summary: List departments
      operationId: listDepartments
      tags: [Departments]
      description: Returns a paginated list of all departments in Lattice.
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of departments
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DepartmentList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /department/{id}:
    get:
      summary: Get department by ID
      operationId: getDepartment
      tags: [Departments]
      description: Returns a department with the given id. If cannot find department, returns a 404.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The department identifier
      responses:
        "200":
          description: Department object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Department"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /goals:
    get:
      summary: List goals
      operationId: listGoals
      tags: [Goals]
      description: Returns a paginated list of goals in Lattice.
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
        - name: state
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/GoalStateEnum"
          description: Filter by goal state
      responses:
        "200":
          description: Paginated list of goals
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GoalList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

    post:
      summary: Create goal
      operationId: createGoal
      tags: [Goals]
      description: Creates a new goal in Lattice.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GoalCreate"
      responses:
        "200":
          description: Created goal object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Goal"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /goal/{id}:
    get:
      summary: Get goal by ID
      operationId: getGoal
      tags: [Goals]
      description: Returns a goal with the given id. If cannot find goal, returns a 404.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The goal identifier
      responses:
        "200":
          description: Goal object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Goal"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /goals/{id}:
    put:
      summary: Update goal
      operationId: updateGoal
      tags: [Goals]
      description: Updates an existing goal with the provided information.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The unique identifier of the goal to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GoalUpdate"
      responses:
        "200":
          description: Updated goal object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Goal"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /goal/{id}/updates:
    get:
      summary: List goal updates for a goal
      operationId: getGoalUpdates
      tags: [Goal Updates]
      description: Returns paginated progress updates for a specific goal.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The goal identifier
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of goal updates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GoalUpdateList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

    post:
      summary: Create goal update
      operationId: createGoalUpdate
      tags: [Goal Updates]
      description: Creates a progress update for a specific goal.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The goal identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GoalUpdateCreate"
      responses:
        "200":
          description: Created goal update object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GoalUpdateItem"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /goalUpdates:
    get:
      summary: List all goal updates
      operationId: getAllGoalUpdates
      tags: [Goal Updates]
      description: Returns a paginated list of all goal updates across all goals.
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of all goal updates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GoalUpdateList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /feedbacks:
    get:
      summary: List feedbacks
      operationId: listFeedbacks
      tags: [Feedbacks]
      description: Returns a paginated list of all continuous feedback in Lattice. Newest feedback will be returned first.
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
        - name: onlyPublic
          in: query
          required: false
          schema:
            type: boolean
          description: Filter to public feedback only
      responses:
        "200":
          description: Paginated list of feedback
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedbackList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /feedback/{id}:
    get:
      summary: Get feedback by ID
      operationId: getFeedback
      tags: [Feedbacks]
      description: Returns a feedback with the given id. If cannot find feedback, returns a 404.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The feedback identifier
      responses:
        "200":
          description: Feedback object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Feedback"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /reviewCycles:
    get:
      summary: List review cycles
      operationId: listReviewCycles
      tags: [Review Cycles]
      description: Returns a paginated list of all review cycles in Lattice.
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of review cycles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReviewCycleList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /reviewCycle/{id}:
    get:
      summary: Get review cycle by ID
      operationId: getReviewCycle
      tags: [Review Cycles]
      description: Returns a review cycle with the given id. If cannot find review cycle, returns a 404.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The review cycle identifier
      responses:
        "200":
          description: Review cycle object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReviewCycle"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /reviewCycle/{id}/reviewees:
    get:
      summary: List reviewees in a review cycle
      operationId: listReviewCycleReviewees
      tags: [Reviewees]
      description: Returns a paginated list of all reviewees in a review cycle.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The review cycle identifier
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of reviewees
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RevieweeList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /reviewCycle/{id}/reviews:
    get:
      summary: List reviews in a review cycle
      operationId: listReviewCycleReviews
      tags: [Reviews]
      description: Returns a paginated list of all reviews in a review cycle.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The review cycle identifier
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of reviews
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReviewList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /reviewee/{id}/reviews:
    get:
      summary: List reviews for a reviewee
      operationId: listRevieweeReviews
      tags: [Reviews]
      description: Returns a paginated list of all reviews for a specific reviewee.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The reviewee identifier
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of reviews
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReviewList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /tags:
    get:
      summary: List tags
      operationId: listTags
      tags: [Tags]
      description: Returns a paginated list of all tags in Lattice.
      parameters:
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of tags
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /tag/{id}:
    get:
      summary: Get tag by ID
      operationId: getTag
      tags: [Tags]
      description: Returns a tag with the given id.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The tag identifier
      responses:
        "200":
          description: Tag object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tag"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /competency/{id}:
    get:
      summary: Get competency by ID
      operationId: getCompetency
      tags: [Competencies]
      description: Returns a competency with the given id. If cannot find competency, returns a 404.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The competency identifier
      responses:
        "200":
          description: Competency object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Competency"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /user/{id}/goals:
    get:
      summary: List goals for a user
      operationId: listUserGoals
      tags: [Goals]
      description: Returns a paginated list of goals for a specific user.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The user identifier
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of goals
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GoalList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /user/{id}/directReports:
    get:
      summary: List direct reports for a user
      operationId: listUserDirectReports
      tags: [Users]
      description: Returns a paginated list of direct reports for a specific user.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The user identifier
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of users
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /user/{id}/tasks:
    get:
      summary: List tasks for a user
      operationId: listUserTasks
      tags: [Users]
      description: Returns a paginated list of tasks for a specific user.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The user identifier
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/startingAfter"
      responses:
        "200":
          description: Paginated list of tasks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

  /user/{id}/customAttributes:
    get:
      summary: List custom attributes for a user
      operationId: listUserCustomAttributes
      tags: [Users]
      description: Returns custom attribute values for a specific user.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The user identifier
      responses:
        "200":
          description: List of custom attribute values
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomAttributeValueList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "500":
          $ref: "#/components/responses/ServerError"

components:

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >
        API key passed as a Bearer token in the Authorization header.
        Example: Authorization: Bearer <your-api-key>

  parameters:
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        format: int32
      description: Maximum number of items to return per page
    startingAfter:
      name: startingAfter
      in: query
      required: false
      schema:
        type: string
      description: Cursor for fetching the next page of results

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Could not find the requested resource
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    UnprocessableEntity:
      description: Unprocessable - request is syntactically valid but cannot be processed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ServerError:
      description: Server error while processing request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  schemas:

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
      required: [error]

    ObjectReference:
      type: object
      description: A lightweight reference to another Lattice object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
      required: [id, object, url]

    ListReference:
      type: object
      description: A reference to a paginated list of related objects
      properties:
        object:
          type: string
          enum: [list]
        url:
          type: string
      required: [object, url]

    PaginatedList:
      type: object
      properties:
        object:
          type: string
          enum: [list]
        hasMore:
          type: boolean
          description: Whether or not there are more elements available after this set
        endingCursor:
          type: string
          nullable: true
          description: The cursor to use to get the next set of items in the list
      required: [object, hasMore]

    User:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        name:
          type: string
          nullable: true
        preferredName:
          type: string
          nullable: true
        email:
          type: string
          format: email
        title:
          type: string
          nullable: true
        status:
          type: string
          enum: [ACTIVE, INVITED, CREATED, DEACTIVATED]
        isAdmin:
          type: boolean
        externalUserId:
          type: string
          nullable: true
        manager:
          $ref: "#/components/schemas/ObjectReference"
          nullable: true
        department:
          $ref: "#/components/schemas/ObjectReference"
          nullable: true
        directReports:
          $ref: "#/components/schemas/ListReference"
        tasks:
          $ref: "#/components/schemas/ListReference"
        customAttributes:
          $ref: "#/components/schemas/ListReference"
        timezone:
          type: string
          nullable: true
        startDate:
          type: string
          format: date
          nullable: true
        birthDate:
          type: string
          format: date
          nullable: true
        gender:
          type: string
          nullable: true
        jobFunction:
          type: string
          nullable: true
        jobLevel:
          type: string
          nullable: true
        jobType:
          type: string
          nullable: true
        createdAt:
          type: integer
          description: Unix timestamp
        updatedAt:
          type: integer
          description: Unix timestamp
      required: [id, object, url, email, status, isAdmin, directReports, tasks, customAttributes]

    UserList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/User"
          required: [data]

    Department:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
          description: Markdown-formatted description
        createdAt:
          type: integer
          description: Unix timestamp
      required: [id, object, url, name, createdAt]

    DepartmentList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Department"
          required: [data]

    GoalStateEnum:
      type: string
      enum: [Draft, Active, Ended, Archived]

    GoalStatusEnum:
      type: string
      enum: [NotUpdated, OnTrack, Progressing, OffTrack]

    GoalTypeEnum:
      type: string
      enum: [Company, Department, Group, Individual]

    OkrTypeEnum:
      type: string
      enum: [objective, key_result]

    AmountTypeEnum:
      type: string
      enum: [Percent, Dollar, Digit, Binary]

    Goal:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
          description: Markdown-formatted description
        state:
          $ref: "#/components/schemas/GoalStateEnum"
        status:
          $ref: "#/components/schemas/GoalStatusEnum"
        goalType:
          $ref: "#/components/schemas/GoalTypeEnum"
        okrType:
          $ref: "#/components/schemas/OkrTypeEnum"
        isPrivate:
          type: boolean
        priority:
          type: integer
          nullable: true
        amountType:
          $ref: "#/components/schemas/AmountTypeEnum"
          nullable: true
        startingAmount:
          type: number
          format: float
          nullable: true
        endingAmount:
          type: number
          format: float
          nullable: true
        currentAmount:
          type: number
          format: float
          nullable: true
        startDate:
          type: string
          format: date
          nullable: true
        dueDate:
          type: string
          format: date
          nullable: true
        createdAt:
          type: integer
          description: Unix timestamp
        updatedAt:
          type: integer
          description: Unix timestamp
        publishedAt:
          type: integer
          nullable: true
          description: Unix timestamp
        completedAt:
          type: integer
          nullable: true
          description: Unix timestamp
        archivedAt:
          type: integer
          nullable: true
          description: Unix timestamp
        owners:
          $ref: "#/components/schemas/ListReference"
        department:
          $ref: "#/components/schemas/ObjectReference"
          nullable: true
        parentGoal:
          $ref: "#/components/schemas/ObjectReference"
          nullable: true
        childGoals:
          $ref: "#/components/schemas/ListReference"
        tags:
          $ref: "#/components/schemas/ListReference"
      required: [id, object, url, name, state, status, goalType, okrType, isPrivate, owners, childGoals, tags, createdAt, updatedAt]

    GoalList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Goal"
          required: [data]

    GoalCreate:
      type: object
      properties:
        name:
          type: string
        startDate:
          type: string
          format: date
        dueDate:
          type: string
          format: date
        ownerIds:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
        description:
          type: string
        priority:
          type: number
          minimum: 1
          maximum: 10
        private:
          type: boolean
          default: false
        okrType:
          $ref: "#/components/schemas/OkrTypeEnum"
        amountType:
          type: string
          enum: [percent, dollar, digit, binary]
          nullable: true
        startingAmount:
          type: number
          nullable: true
        goalAmount:
          type: number
          nullable: true
        companyGoal:
          type: boolean
          default: false
        departmentId:
          type: string
          format: uuid
          nullable: true
        departmentsVisibleToIds:
          type: array
          items:
            type: string
            format: uuid
        goalCycleId:
          type: string
          format: uuid
          nullable: true
        tagNames:
          type: array
          items:
            type: string
          maxItems: 5
        isDraft:
          type: boolean
          default: false
        parentId:
          type: string
          format: uuid
          nullable: true
      required: [name, startDate, dueDate, ownerIds]

    GoalUpdate:
      allOf:
        - $ref: "#/components/schemas/GoalCreate"
        - type: object
          properties:
            name:
              type: string
            description:
              type: string
            startDate:
              type: string
              format: date
            dueDate:
              type: string
              format: date
            priority:
              type: number
              minimum: 1
              maximum: 10
            private:
              type: boolean
            ownerIds:
              type: array
              items:
                type: string
                format: uuid
              minItems: 1
            okrType:
              $ref: "#/components/schemas/OkrTypeEnum"
            amountType:
              type: string
              enum: [percent, dollar, digit, binary]
              nullable: true
            startingAmount:
              type: number
              nullable: true
            goalAmount:
              type: number
              nullable: true
            companyGoal:
              type: boolean
            departmentId:
              type: string
              format: uuid
              nullable: true
            departmentsVisibleToIds:
              type: array
              items:
                type: string
                format: uuid
            goalCycleId:
              type: string
              format: uuid
              nullable: true
            tagNames:
              type: array
              items:
                type: string
              maxItems: 5
            isDraft:
              type: boolean
            parentId:
              type: string
              format: uuid
              nullable: true
          required: [name, description, startDate, dueDate, priority, private, ownerIds, okrType, amountType, startingAmount, goalAmount, companyGoal, departmentId, departmentsVisibleToIds, goalCycleId, tagNames, isDraft, parentId]

    GoalUpdateItem:
      type: object
      description: A progress update for a goal
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        goal:
          $ref: "#/components/schemas/ObjectReference"
        author:
          $ref: "#/components/schemas/ObjectReference"
        comment:
          type: string
          nullable: true
        currentAmount:
          type: number
          format: float
          nullable: true
        createdAt:
          type: integer
          description: Unix timestamp
      required: [id, object, url, goal, author, createdAt]

    GoalUpdateList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/GoalUpdateItem"
          required: [data]

    GoalUpdateCreate:
      type: object
      properties:
        comment:
          type: string
        currentAmount:
          type: number
          nullable: true

    Feedback:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        author:
          $ref: "#/components/schemas/ObjectReference"
        targets:
          type: object
          description: FeedbackTargetsList of users the feedback addresses
        body:
          type: string
          description: Feedback text content
        associatedValues:
          type: object
          description: CompanyValuesList of related company values
          nullable: true
        feedbackRequest:
          type: object
          description: Original feedback request; null if unsolicited
          nullable: true
        competency:
          $ref: "#/components/schemas/ObjectReference"
          nullable: true
        visibility:
          type: string
          description: Who can view this feedback
        isPublic:
          type: boolean
          description: Company-wide visibility flag
        createdAt:
          type: integer
          description: Unix timestamp
      required: [id, object, url, author, targets, body, visibility, isPublic, createdAt]

    FeedbackList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Feedback"
          required: [data]

    ReviewCycleStageEnum:
      type: string
      enum: [Draft, PreLaunch, Launching, PeerSelection, CollectingReviews, Calibration, Ended]

    ReviewCycle:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        name:
          type: string
        stage:
          $ref: "#/components/schemas/ReviewCycleStageEnum"
        creator:
          $ref: "#/components/schemas/ObjectReference"
        reviewees:
          $ref: "#/components/schemas/ListReference"
        reviews:
          $ref: "#/components/schemas/ListReference"
        calibrationEnabled:
          type: boolean
        weightedScoresEnabled:
          type: boolean
        autocalculatedWeightedScoresEnabled:
          type: boolean
        peerSelectionStartedAt:
          type: integer
          nullable: true
          description: Unix timestamp
        reviewsStartedAt:
          type: integer
          nullable: true
          description: Unix timestamp
        reviewsEndedAt:
          type: integer
          nullable: true
          description: Unix timestamp
        calibrationEndedAt:
          type: integer
          nullable: true
          description: Unix timestamp
        weightedScoresEndedAt:
          type: integer
          nullable: true
          description: Unix timestamp
        createdAt:
          type: integer
          description: Unix timestamp
        updatedAt:
          type: integer
          description: Unix timestamp
      required: [id, object, url, name, stage, creator, reviewees, reviews, calibrationEnabled, weightedScoresEnabled, autocalculatedWeightedScoresEnabled, createdAt, updatedAt]

    ReviewCycleList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/ReviewCycle"
          required: [data]

    WeightedScore:
      type: object
      properties:
        manual:
          type: number
          format: float
          nullable: true
        autoCalculated:
          type: number
          format: float
          nullable: true

    Reviewee:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        externalUserId:
          type: string
          nullable: true
        reviewCycle:
          $ref: "#/components/schemas/ObjectReference"
        user:
          $ref: "#/components/schemas/ObjectReference"
        reviews:
          $ref: "#/components/schemas/ListReference"
        revieweeFacingPDFUrl:
          type: string
          nullable: true
        managerFacingPDFUrl:
          type: string
          nullable: true
        closedAt:
          type: integer
          nullable: true
          description: Unix timestamp when closed
        esignatureGivenAt:
          type: integer
          nullable: true
          description: Unix timestamp of e-signature
        responsesReleasedAt:
          type: integer
          nullable: true
          description: Unix timestamp when responses were released
        weightedScore:
          $ref: "#/components/schemas/WeightedScore"
          nullable: true
        createdAt:
          type: integer
          description: Unix timestamp
        updatedAt:
          type: integer
          description: Unix timestamp
      required: [id, object, url, reviewCycle, user, reviews, createdAt, updatedAt]

    RevieweeList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Reviewee"
          required: [data]

    ReviewDirectionEnum:
      type: string
      enum: [downward, self, peer, upward]

    ReviewStateEnum:
      type: string
      enum: [unstarted, drafted, submitted, rejected, shared]

    Review:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        revieweeId:
          type: string
          format: uuid
        cycleId:
          type: string
          format: uuid
        direction:
          $ref: "#/components/schemas/ReviewDirectionEnum"
        state:
          $ref: "#/components/schemas/ReviewStateEnum"
        updatedAt:
          type: string
          format: date-time
        submittedAt:
          type: string
          format: date-time
          nullable: true
      required: [id, revieweeId, cycleId, direction, state, updatedAt]

    ReviewList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Review"
          required: [data]

    Tag:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        name:
          type: string
        createdAt:
          type: integer
          description: Unix timestamp
        updatedAt:
          type: integer
          description: Unix timestamp
      required: [id, object, url, name, createdAt, updatedAt]

    TagList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Tag"
          required: [data]

    Competency:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
      required: [id, object, name]

    Task:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        url:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        dueDate:
          type: string
          format: date
          nullable: true
        completedAt:
          type: integer
          nullable: true
          description: Unix timestamp
        createdAt:
          type: integer
          description: Unix timestamp
        updatedAt:
          type: integer
          description: Unix timestamp
      required: [id, object, url, name, createdAt, updatedAt]

    TaskList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Task"
          required: [data]

    CustomAttribute:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
      required: [id, object, name, type]

    CustomAttributeValue:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        attribute:
          $ref: "#/components/schemas/CustomAttribute"
        value:
          type: string
          nullable: true
      required: [id, object, attribute]

    CustomAttributeValueList:
      allOf:
        - $ref: "#/components/schemas/PaginatedList"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/CustomAttributeValue"
          required: [data]