openapi: 3.1.0
info:
  title: Remote Time and Attendance API
  description: |
    Manage time off, leave policies, leave balances, and timesheets for
    employees on Remote.com. The API exposes both manager-driven and
    employee-driven flows and surfaces every state change via webhooks
    (requested, approved, declined, cancellation_requested, started,
    taken, etc.).
  version: '2026-05-22'
  contact:
    name: Remote API Support
    url: https://support.remote.com/
  x-logo:
    url: https://remote.com/favicon.ico

servers:
  - url: https://gateway.remote.com/v1
    description: Production
  - url: https://gateway.remote-sandbox.com/v1
    description: Sandbox

security:
  - BearerAuth: []

tags:
  - name: Time Off
    description: Time-off requests and approvals
  - name: Leave Policies
    description: Per-country leave policy definitions
  - name: Leave Balances
    description: Per-employee leave balances
  - name: Timesheets
    description: Hourly and salaried timesheets

paths:
  /timeoff:
    get:
      summary: List Time Off Requests
      operationId: listTimeOffRequests
      tags: [Time Off]
      parameters:
        - { name: employment_id, in: query, schema: { type: string, format: uuid } }
        - { name: status, in: query, schema: { $ref: '#/components/schemas/TimeOffStatus' } }
        - { name: starts_after, in: query, schema: { type: string, format: date } }
        - { name: ends_before, in: query, schema: { type: string, format: date } }
      responses:
        '200':
          description: Time-off requests.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimeOffList' }
    post:
      summary: Create A Time Off Request
      operationId: createTimeOffRequest
      tags: [Time Off]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TimeOffCreateRequest' }
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimeOffEnvelope' }

  /timeoff/{timeoff_id}:
    parameters:
      - { name: timeoff_id, in: path, required: true, schema: { type: string, format: uuid } }
    get:
      summary: Show A Time Off Request
      operationId: showTimeOffRequest
      tags: [Time Off]
      responses:
        '200':
          description: Request.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimeOffEnvelope' }
    patch:
      summary: Update A Time Off Request
      operationId: updateTimeOffRequest
      tags: [Time Off]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TimeOffCreateRequest' }
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimeOffEnvelope' }

  /timeoff/{timeoff_id}/approve:
    parameters:
      - { name: timeoff_id, in: path, required: true, schema: { type: string, format: uuid } }
    post:
      summary: Approve A Time Off Request
      operationId: approveTimeOffRequest
      tags: [Time Off]
      responses:
        '200':
          description: Approved.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimeOffEnvelope' }

  /timeoff/{timeoff_id}/decline:
    parameters:
      - { name: timeoff_id, in: path, required: true, schema: { type: string, format: uuid } }
    post:
      summary: Decline A Time Off Request
      operationId: declineTimeOffRequest
      tags: [Time Off]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason: { type: string }
      responses:
        '200':
          description: Declined.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimeOffEnvelope' }

  /timeoff/{timeoff_id}/cancel:
    parameters:
      - { name: timeoff_id, in: path, required: true, schema: { type: string, format: uuid } }
    post:
      summary: Cancel A Time Off Request
      operationId: cancelTimeOffRequest
      tags: [Time Off]
      responses:
        '200':
          description: Canceled.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimeOffEnvelope' }

  /leave_policies:
    get:
      summary: List Leave Policies
      operationId: listLeavePolicies
      tags: [Leave Policies]
      parameters:
        - { name: country_code, in: query, schema: { type: string } }
      responses:
        '200':
          description: Leave policies.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LeavePolicyList' }

  /leave_policies/{leave_policy_id}:
    parameters:
      - { name: leave_policy_id, in: path, required: true, schema: { type: string, format: uuid } }
    get:
      summary: Show A Leave Policy
      operationId: showLeavePolicy
      tags: [Leave Policies]
      responses:
        '200':
          description: Leave policy.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LeavePolicyEnvelope' }

  /leave_balances:
    get:
      summary: List Leave Balances
      operationId: listLeaveBalances
      tags: [Leave Balances]
      parameters:
        - { name: employment_id, in: query, required: true, schema: { type: string, format: uuid } }
      responses:
        '200':
          description: Leave balances for the employment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      leave_balances:
                        type: array
                        items:
                          type: object
                          properties:
                            leave_type: { type: string }
                            remaining_days: { type: number }
                            used_days: { type: number }
                            accrued_days: { type: number }
                            unit:
                              type: string
                              enum: [days, hours]

  /timesheets:
    get:
      summary: List Timesheets
      operationId: listTimesheets
      tags: [Timesheets]
      parameters:
        - { name: employment_id, in: query, schema: { type: string, format: uuid } }
        - { name: status, in: query, schema: { type: string, enum: [draft, submitted, approved, sent_back] } }
        - { name: period_start, in: query, schema: { type: string, format: date } }
      responses:
        '200':
          description: Timesheets.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimesheetList' }

  /timesheets/{timesheet_id}:
    parameters:
      - { name: timesheet_id, in: path, required: true, schema: { type: string, format: uuid } }
    get:
      summary: Show A Timesheet
      operationId: showTimesheet
      tags: [Timesheets]
      responses:
        '200':
          description: Timesheet.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimesheetEnvelope' }

  /timesheets/{timesheet_id}/approve:
    parameters:
      - { name: timesheet_id, in: path, required: true, schema: { type: string, format: uuid } }
    post:
      summary: Approve A Timesheet
      operationId: approveTimesheet
      tags: [Timesheets]
      responses:
        '200':
          description: Approved.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimesheetEnvelope' }

  /timesheets/{timesheet_id}/send_back:
    parameters:
      - { name: timesheet_id, in: path, required: true, schema: { type: string, format: uuid } }
    post:
      summary: Send A Timesheet Back For Revision
      operationId: sendTimesheetBack
      tags: [Timesheets]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason: { type: string }
      responses:
        '200':
          description: Sent back.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TimesheetEnvelope' }

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    TimeOffStatus:
      type: string
      enum: [requested, approved, declined, cancellation_requested, canceled, started, taken]

    TimeOff:
      type: object
      properties:
        id: { type: string, format: uuid }
        employment_id: { type: string, format: uuid }
        leave_type: { type: string }
        leave_policy_id: { type: string, format: uuid }
        status: { $ref: '#/components/schemas/TimeOffStatus' }
        start_date: { type: string, format: date }
        end_date: { type: string, format: date }
        total_days: { type: number }
        note: { type: string }
        created_at: { type: string, format: date-time }

    TimeOffList:
      type: object
      properties:
        data:
          type: object
          properties:
            timeoff:
              type: array
              items: { $ref: '#/components/schemas/TimeOff' }

    TimeOffEnvelope:
      type: object
      properties:
        data:
          type: object
          properties:
            timeoff: { $ref: '#/components/schemas/TimeOff' }

    TimeOffCreateRequest:
      type: object
      required: [employment_id, leave_type, start_date, end_date]
      properties:
        employment_id: { type: string, format: uuid }
        leave_type: { type: string }
        leave_policy_id: { type: string, format: uuid }
        start_date: { type: string, format: date }
        end_date: { type: string, format: date }
        note: { type: string }

    LeavePolicy:
      type: object
      properties:
        id: { type: string, format: uuid }
        country_code: { type: string }
        leave_type: { type: string }
        accrual_method:
          type: string
          enum: [annual, monthly, per_period, statutory]
        annual_allowance: { type: number }
        unit:
          type: string
          enum: [days, hours]

    LeavePolicyList:
      type: object
      properties:
        data:
          type: object
          properties:
            leave_policies:
              type: array
              items: { $ref: '#/components/schemas/LeavePolicy' }

    LeavePolicyEnvelope:
      type: object
      properties:
        data:
          type: object
          properties:
            leave_policy: { $ref: '#/components/schemas/LeavePolicy' }

    Timesheet:
      type: object
      properties:
        id: { type: string, format: uuid }
        employment_id: { type: string, format: uuid }
        period_start: { type: string, format: date }
        period_end: { type: string, format: date }
        status:
          type: string
          enum: [draft, submitted, approved, sent_back]
        total_hours: { type: number }
        entries:
          type: array
          items:
            type: object
            properties:
              date: { type: string, format: date }
              hours: { type: number }
              notes: { type: string }

    TimesheetList:
      type: object
      properties:
        data:
          type: object
          properties:
            timesheets:
              type: array
              items: { $ref: '#/components/schemas/Timesheet' }

    TimesheetEnvelope:
      type: object
      properties:
        data:
          type: object
          properties:
            timesheet: { $ref: '#/components/schemas/Timesheet' }