openapi: 3.1.0
info:
  title: Justworks Time Off API
  description: |
    Manage time-off balances, policies, and requests in the Justworks
    Partner API. Time-off balances are produced as asynchronous reports —
    submit a request, then poll the report endpoint until ready.
  version: '2026-05-25'
  contact:
    name: Justworks Partner Support
    url: https://public-api.justworks.com/v1/docs

servers:
  - url: https://public-api.justworks.com
    description: Production Server

security:
  - OAuth2: []

tags:
  - name: Time Off Balances
    description: Asynchronous balance reports for time-off policies
  - name: Time Off Policies
    description: Read access to time-off policy catalog
  - name: Time Off Requests
    description: Read access to time-off requests submitted by members

paths:
  /v1/time-off/balances:
    post:
      summary: Justworks Create Time Off Balances Report
      description: Request an asynchronous time-off balance report for a member, policy, and as-of date.
      operationId: createTimeOffBalancesReport
      tags:
        - Time Off Balances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - member_id
                - policy_id
                - as_of_date
              properties:
                member_id:
                  type: string
                policy_id:
                  type: string
                as_of_date:
                  type: string
                  format: date
      responses:
        '202':
          description: Report accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  report_id:
                    type: string

  /v1/time-off/balances/{report_id}:
    get:
      summary: Justworks Get Time Off Balances Report
      description: Retrieve a time-off balance report by id. Poll until status indicates the report is ready.
      operationId: getTimeOffBalancesReport
      tags:
        - Time Off Balances
      parameters:
        - name: report_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Time-off balance report
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        member_id:
                          type: string
                        policy_id:
                          type: string
                        unit_type:
                          type: string
                        available:
                          type: number
                        used:
                          type: number

  /v1/time-off/policies:
    get:
      summary: Justworks List Time Off Policies
      description: List time-off policies configured for the company.
      operationId: listTimeOffPolicies
      tags:
        - Time Off Policies
      parameters:
        - name: status
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of policies
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimeOffPolicy'
                  next_cursor:
                    type: string
                    nullable: true

  /v1/time-off/requests:
    get:
      summary: Justworks List Time Off Requests
      description: List time-off requests within a date range, optionally filtered by member, policy, or status.
      operationId: listTimeOffRequests
      tags:
        - Time Off Requests
      parameters:
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: member_id
          in: query
          schema:
            type: string
        - name: policy_id
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of time-off requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimeOffRequest'
                  next_cursor:
                    type: string
                    nullable: true

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://secure.justworks.com/oauth/authorize
          tokenUrl: https://public-api.justworks.com/oauth/token
          refreshUrl: https://public-api.justworks.com/oauth/token
          scopes:
            time_off:read: Read time-off policies, balances, and requests

  schemas:
    TimeOffPolicy:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
        type:
          type: string
        deactivation_date:
          type: string
          format: date
          nullable: true
        effective_date:
          type: string
          format: date

    TimeOffRequest:
      type: object
      properties:
        id:
          type: string
        member_id:
          type: string
        policy_id:
          type: string
        status:
          type: string
        unit_type:
          type: string
        amount:
          type: number
        end_date:
          type: string
          format: date
        notes:
          type: string
        start_date:
          type: string
          format: date
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time