openapi: 3.0.3
info:
  title: Lattice HRIS API
  description: >
    REST API (v2) for Lattice's HRIS product covering employee records,
    organizational hierarchy, and HR core data. Supports service account
    Bearer token authentication and is designed for HR system integrations
    including Okta SCIM provisioning. Also exposes v2 review submission
    endpoints shared with the Talent API.
  version: v2
  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/v2
    description: Lattice HRIS API v2 production server

security:
  - BearerAuth: []

tags:
  - name: Reviews
    description: Create, update, and submit performance reviews (v2)

paths:

  /reviews/draft:
    post:
      summary: Create a draft review
      operationId: createDraftReview
      tags: [Reviews]
      description: >
        Saves initial responses for a review as a draft. The review must
        exist and the caller must have permission to complete it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDraftReviewRequest"
      responses:
        "201":
          description: Draft review created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DraftReviewResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

  /reviews/{id}/submit:
    post:
      summary: Submit a review
      operationId: submitReview
      tags: [Reviews]
      description: >
        Submits a drafted review. The review must be in drafted state and
        all required questions must have valid responses.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The review entity ID
      responses:
        "200":
          description: Review submitted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubmitReviewResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

  /reviews/{id}/draft:
    put:
      summary: Update a draft review
      operationId: updateDraftReview
      tags: [Reviews]
      description: >
        Updates existing draft responses for a review. The review must be
        in drafted state.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The review entity ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateDraftReviewRequest"
      responses:
        "200":
          description: Draft review updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DraftReviewResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

components:

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

  responses:
    BadRequest:
      description: Bad request - validation failed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponseDto"
    Unauthorized:
      description: Unauthorized - missing or invalid bearer token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponseDto"
    Forbidden:
      description: Forbidden - caller lacks required permissions
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponseDto"
    NotFound:
      description: Not found - the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponseDto"
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponseDto"

  schemas:

    ErrorResponseDto:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        title:
          type: string
          description: Short error summary
        detail:
          type: string
          description: Specific explanation of the error
        errors:
          type: array
          items:
            type: string
          description: Optional array of field-level validation errors
      required: [status, title, detail]

    ReviewResponseItem:
      type: object
      description: A single answer to a review question
      properties:
        questionRevisionId:
          type: string
          format: uuid
          description: The entity ID of the question revision being answered
        comment:
          type: string
          nullable: true
          description: Free-form text response for free-text questions
        rating:
          type: string
          nullable: true
          description: Rating value for rated questions
        choices:
          type: array
          items:
            type: string
          nullable: true
          description: Selected choices for multiple-select questions
      required: [questionRevisionId]

    CreateDraftReviewRequest:
      type: object
      properties:
        reviewId:
          type: string
          format: uuid
          description: The entity ID of the review (review request)
        responses:
          type: array
          items:
            $ref: "#/components/schemas/ReviewResponseItem"
          minItems: 1
          description: Collection of review answers
      required: [reviewId, responses]

    UpdateDraftReviewRequest:
      type: object
      properties:
        responses:
          type: array
          items:
            $ref: "#/components/schemas/ReviewResponseItem"
          minItems: 1
          description: Updated collection of review answers
      required: [responses]

    SavedReviewResponse:
      type: object
      properties:
        questionRevisionId:
          type: string
          format: uuid
        comment:
          type: string
          nullable: true
        rating:
          type: string
          nullable: true
        choices:
          type: array
          items:
            type: string
          nullable: true
      required: [questionRevisionId]

    DraftReviewResponseDto:
      type: object
      description: Review data returned after creating or updating a draft
      properties:
        id:
          type: string
          format: uuid
          description: Review ID
        revieweeId:
          type: string
          format: uuid
          description: Employee being reviewed
        cycleId:
          type: string
          format: uuid
          description: Associated review cycle ID
        direction:
          type: string
          enum: [downward, self, peer, upward]
          description: Direction of the review
        state:
          type: string
          enum: [unstarted, drafted, submitted, rejected, shared]
          description: Current state of the review
        responses:
          type: array
          items:
            $ref: "#/components/schemas/SavedReviewResponse"
          description: Saved review responses
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp of last update
        submittedAt:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 UTC timestamp of submission
      required: [id, revieweeId, cycleId, direction, state, responses, updatedAt]

    DraftReviewResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/DraftReviewResponseDto"
      required: [data]

    SubmitReviewData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Review UUID
        revieweeId:
          type: string
          format: uuid
          description: Employee UUID
        cycleId:
          type: string
          format: uuid
          description: Cycle UUID
        direction:
          type: string
          enum: [downward, self, peer, upward]
        state:
          type: string
          enum: [submitted]
          description: Always "submitted" after successful submission
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp
        submittedAt:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp
      required: [id, revieweeId, cycleId, direction, state, updatedAt, submittedAt]

    SubmitReviewResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/SubmitReviewData"
      required: [data]