openapi: 3.0.3
info:
  title: Classic Models API — Workforce domain
  version: 4.7.0
  description: 'Offices, employees and the reporting hierarchy. Workforce domain subset of the shared classic-models-api backend, as exposed by the workforce domain''s Kong gateway. Paths and server below are the gateway''s, not the backend''s: the gateway rewrites /workforce/v1/... onto /classic-models/api/v1/... upstream. Requires a bearer token from the classic-models realm.'
paths:
  /workforce/v1/employees/:
    post:
      operationId: create_employee
      description: Add a new employee to the organization with their job details and office assignment.
      summary: Create a new employee
      tags:
        - Employees
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EmployeeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EmployeeRequest'
        required: true
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
          description: ""
    get:
      operationId: list_employees
      description: Retrieve a paginated list of all employees in the organization with their details.
      summary: List all employees
      parameters:
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
      tags:
        - Employees
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEmployeeList'
          description: ""
  /workforce/v1/employees/{employeenumber}/:
    patch:
      operationId: patch_employee
      description: Update specific fields of an existing employee record.
      summary: Partially update an employee
      parameters:
        - in: path
          name: employeenumber
          schema:
            type: integer
            maximum: 2147483647
            minimum: -2147483648
          description: A unique value identifying this employee.
          required: true
      tags:
        - Employees
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedEmployeeRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedEmployeeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedEmployeeRequest'
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
          description: ""
    put:
      operationId: update_employee
      description: Update all fields of an existing employee record.
      summary: Update an employee
      parameters:
        - in: path
          name: employeenumber
          schema:
            type: integer
            maximum: 2147483647
            minimum: -2147483648
          description: A unique value identifying this employee.
          required: true
      tags:
        - Employees
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EmployeeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EmployeeRequest'
        required: true
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
          description: ""
    get:
      operationId: get_employee
      description: Retrieve detailed information about a specific employee by their employee number.
      summary: Get a specific employee
      parameters:
        - in: path
          name: employeenumber
          schema:
            type: integer
            maximum: 2147483647
            minimum: -2147483648
          description: A unique value identifying this employee.
          required: true
      tags:
        - Employees
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
          description: ""
    delete:
      operationId: delete_employee
      description: Remove an employee from the organization.
      summary: Delete an employee
      parameters:
        - in: path
          name: employeenumber
          schema:
            type: integer
            maximum: 2147483647
            minimum: -2147483648
          description: A unique value identifying this employee.
          required: true
      tags:
        - Employees
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "204":
          description: No response body
  /workforce/v1/employees/{employeenumber}/customers/:
    get:
      operationId: get_employee_customers
      description: Retrieve all customers assigned to a specific sales representative. This endpoint supports sales rep performance tracking and customer management.
      summary: Get customers by sales rep
      parameters:
        - in: path
          name: employeenumber
          schema:
            type: integer
          description: The employee number of the sales representative
          required: true
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
      tags:
        - Employees
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCustomerList'
          description: ""
  /workforce/v1/employees/{employeenumber}/reports/:
    get:
      operationId: get_employee_reports
      description: Retrieve all employees reporting to a specific manager. This endpoint supports organizational hierarchy and team management.
      summary: Get employees by manager
      parameters:
        - in: path
          name: employeenumber
          schema:
            type: integer
          description: The employee number of the manager
          required: true
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
      tags:
        - Employees
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEmployeeList'
          description: ""
  /workforce/v1/offices/:
    post:
      operationId: create_office
      description: Add a new office location to the company's network.
      summary: Create a new office
      tags:
        - Offices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfficeRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OfficeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OfficeRequest'
        required: true
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Office'
          description: ""
    get:
      operationId: list_offices
      description: Retrieve a paginated list of all company office locations worldwide.
      summary: List all offices
      parameters:
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
      tags:
        - Offices
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedOfficeList'
          description: ""
  /workforce/v1/offices/{officecode}/:
    patch:
      operationId: patch_office
      description: Update specific fields of an existing office location.
      summary: Partially update an office
      parameters:
        - in: path
          name: officecode
          schema:
            type: string
          description: A unique value identifying this office.
          required: true
      tags:
        - Offices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedOfficeRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedOfficeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedOfficeRequest'
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Office'
          description: ""
    put:
      operationId: update_office
      description: Update all fields of an existing office location.
      summary: Update an office
      parameters:
        - in: path
          name: officecode
          schema:
            type: string
          description: A unique value identifying this office.
          required: true
      tags:
        - Offices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfficeRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OfficeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OfficeRequest'
        required: true
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Office'
          description: ""
    get:
      operationId: get_office
      description: Retrieve detailed information about a specific office by its code.
      summary: Get a specific office
      parameters:
        - in: path
          name: officecode
          schema:
            type: string
          description: A unique value identifying this office.
          required: true
      tags:
        - Offices
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Office'
          description: ""
    delete:
      operationId: delete_office
      description: Remove an office location from the company network.
      summary: Delete an office
      parameters:
        - in: path
          name: officecode
          schema:
            type: string
          description: A unique value identifying this office.
          required: true
      tags:
        - Offices
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "204":
          description: No response body
  /workforce/v1/offices/{officecode}/employees/:
    get:
      operationId: get_office_employees
      description: Retrieve all employees working in a specific office. This endpoint supports office management and organizational charts.
      summary: Get employees by office
      parameters:
        - in: path
          name: officecode
          schema:
            type: string
          description: The office code
          required: true
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
      tags:
        - Offices
      security:
        - ApiKeyAuth: []
        - JWTAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEmployeeList'
          description: ""
components:
  schemas:
    Customer:
      type: object
      description: Customer information and contact details
      properties:
        customernumber:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        customername:
          type: string
          maxLength: 50
        contactlastname:
          type: string
          maxLength: 50
        contactfirstname:
          type: string
          maxLength: 50
        phone:
          type: string
          maxLength: 50
        addressline1:
          type: string
          maxLength: 50
        addressline2:
          type: string
          nullable: true
          maxLength: 50
        city:
          type: string
          maxLength: 50
        state:
          type: string
          nullable: true
          maxLength: 50
        postalcode:
          type: string
          nullable: true
          maxLength: 15
        country:
          type: string
          maxLength: 50
        creditlimit:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
          nullable: true
        salesrepemployeenumber:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          nullable: true
      required:
        - addressline1
        - city
        - contactfirstname
        - contactlastname
        - country
        - customername
        - customernumber
        - phone
    Employee:
      type: object
      description: Employee information and hierarchy
      properties:
        employeenumber:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        lastname:
          type: string
          maxLength: 50
        firstname:
          type: string
          maxLength: 50
        extension:
          type: string
          maxLength: 10
        email:
          type: string
          maxLength: 100
        jobtitle:
          type: string
          maxLength: 50
        officecode:
          type: string
        reportsto:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          nullable: true
      required:
        - email
        - employeenumber
        - extension
        - firstname
        - jobtitle
        - lastname
        - officecode
    EmployeeRequest:
      type: object
      description: Employee information and hierarchy
      properties:
        employeenumber:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        lastname:
          type: string
          minLength: 1
          maxLength: 50
        firstname:
          type: string
          minLength: 1
          maxLength: 50
        extension:
          type: string
          minLength: 1
          maxLength: 10
        email:
          type: string
          minLength: 1
          maxLength: 100
        jobtitle:
          type: string
          minLength: 1
          maxLength: 50
        officecode:
          type: string
          minLength: 1
        reportsto:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          nullable: true
      required:
        - email
        - employeenumber
        - extension
        - firstname
        - jobtitle
        - lastname
        - officecode
    Office:
      type: object
      description: Company office locations
      properties:
        officecode:
          type: string
          maxLength: 10
        city:
          type: string
          maxLength: 50
        phone:
          type: string
          maxLength: 50
        addressline1:
          type: string
          maxLength: 50
        addressline2:
          type: string
          nullable: true
          maxLength: 50
        state:
          type: string
          nullable: true
          maxLength: 50
        country:
          type: string
          maxLength: 50
        postalcode:
          type: string
          maxLength: 15
        territory:
          type: string
          maxLength: 10
      required:
        - addressline1
        - city
        - country
        - officecode
        - phone
        - postalcode
        - territory
    OfficeRequest:
      type: object
      description: Company office locations
      properties:
        officecode:
          type: string
          minLength: 1
          maxLength: 10
        city:
          type: string
          minLength: 1
          maxLength: 50
        phone:
          type: string
          minLength: 1
          maxLength: 50
        addressline1:
          type: string
          minLength: 1
          maxLength: 50
        addressline2:
          type: string
          nullable: true
          maxLength: 50
        state:
          type: string
          nullable: true
          maxLength: 50
        country:
          type: string
          minLength: 1
          maxLength: 50
        postalcode:
          type: string
          minLength: 1
          maxLength: 15
        territory:
          type: string
          minLength: 1
          maxLength: 10
      required:
        - addressline1
        - city
        - country
        - officecode
        - phone
        - postalcode
        - territory
    PaginatedCustomerList:
      type: object
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
    PaginatedEmployeeList:
      type: object
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Employee'
    PaginatedOfficeList:
      type: object
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Office'
    PatchedEmployeeRequest:
      type: object
      description: Employee information and hierarchy
      properties:
        employeenumber:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        lastname:
          type: string
          minLength: 1
          maxLength: 50
        firstname:
          type: string
          minLength: 1
          maxLength: 50
        extension:
          type: string
          minLength: 1
          maxLength: 10
        email:
          type: string
          minLength: 1
          maxLength: 100
        jobtitle:
          type: string
          minLength: 1
          maxLength: 50
        officecode:
          type: string
          minLength: 1
        reportsto:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          nullable: true
    PatchedOfficeRequest:
      type: object
      description: Company office locations
      properties:
        officecode:
          type: string
          minLength: 1
          maxLength: 10
        city:
          type: string
          minLength: 1
          maxLength: 50
        phone:
          type: string
          minLength: 1
          maxLength: 50
        addressline1:
          type: string
          minLength: 1
          maxLength: 50
        addressline2:
          type: string
          nullable: true
          maxLength: 50
        state:
          type: string
          nullable: true
          maxLength: 50
        country:
          type: string
          minLength: 1
          maxLength: 50
        postalcode:
          type: string
          minLength: 1
          maxLength: 15
        territory:
          type: string
          minLength: 1
          maxLength: 10
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication using X-API-Key header
    JWTAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
servers:
  - url: https://workforce-dev.sttlab.local
    description: Workforce gateway (dev)