feat: Added api docs for approver org_employees api

reference/approver.yaml

@@ -3157,6 +3157,104 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/401'
+  /approver/org_employees:
+    get:
+      x-internal: false
+      tags:
+        - Employees
+      summary: List organisation employees
+      operationId: org_employees_list
+      security:
+        - oauth2:
+            - '*'
+      description: |
+        Returns all employees from organisations in the same group as the approver's current
+        organisation where the approver has at least one non-disabled user expense approval.
+
+        This API supplies employee filter values for Team Expenses and Reports.
+        Each employee includes `org_id` to identify their organisation.
+
+        Pass `org_id=eq.<org_id>` to list employees for one authorised organisation.
+        Omit `org_id` to list employees across all authorised organisations.
+        An unauthorised `org_id` returns an empty `data` array with `count: 0`.
+
+        Filtering on response fields, sorting and pagination are supported. See the
+        [Guide to Data APIs](https://docs.fylehq.com/docs/fyle-platform-docs/ZG9jOjI3Mzk2NTM3-guide-to-data-ap-is#filtering)
+        for query syntax. Delegates with the APPROVE or ALL scope can access this API.
+      parameters:
+        - in: query
+          name: org_id
+          required: false
+          description: Filter by organisation; omit to return employees from all authorised organisations.
+          schema:
+            type: string
+            example: eq.orwruogwnngg
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required:
+                  - data
+                  - count
+                  - offset
+                properties:
+                  count:
+                    $ref: '#/components/schemas/count'
+                  offset:
+                    $ref: '#/components/schemas/offset'
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/approver_org_employee_out'
+              example:
+                count: 1
+                offset: 0
+                data:
+                  - id: ouxNjRaFhue2
+                    user_id: usdM767Q2gox
+                    org_id: orwruogwnngg
+                    email: john.doe@example.com
+                    full_name: John Doe
+                    roles:
+                      - FYLER
+                    mobile: '+12131234567'
+                    is_mobile_verified: true
+                    sms_opt_out_source: null
+                    commute_details:
+                      id: null
+                      home_location: null
+                      work_location: null
+                      distance: null
+                      distance_unit: null
+                    is_enabled: true
+                    has_accepted_invite: true
+                    delegatees: []
+        '400':
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/400'
+        '401':
+          description: Unauthorized request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '403':
+          description: The current user does not have permission to access this API.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: you don't have permissions to access this resource
   /approver/orgs:
     get:
       x-internal: false
@@ -12103,6 +12201,68 @@ components:
             $ref: '#/components/schemas/category_out_embed'
           description: |
             List of categories that this employee is allowed to access.
+    approver_org_employee_out:
+      type: object
+      additionalProperties: false
+      required:
+        - id
+        - user_id
+        - org_id
+        - email
+        - full_name
+        - roles
+        - commute_details
+        - mobile
+        - is_mobile_verified
+        - sms_opt_out_source
+        - is_enabled
+        - has_accepted_invite
+        - delegatees
+      properties:
+        id:
+          $ref: '#/components/schemas/id_string'
+        user_id:
+          $ref: '#/components/schemas/user_id'
+        org_id:
+          $ref: '#/components/schemas/org_id'
+        email:
+          $ref: '#/components/schemas/email'
+        full_name:
+          $ref: '#/components/schemas/user_full_name'
+        roles:
+          type: array
+          items:
+            $ref: '#/components/schemas/role'
+        commute_details:
+          $ref: '#/components/schemas/commute_details'
+        mobile:
+          type: string
+          nullable: true
+          example: '+12131234567'
+          description: Mobile number of the employee.
+        is_mobile_verified:
+          type: boolean
+          nullable: true
+          description: Whether the employee's mobile number is verified.
+          example: false
+        sms_opt_out_source:
+          type: string
+          nullable: true
+          maxLength: 255
+          description: Whether the employee opted out of SMS through the web app or SMS.
+          example: WEB_APP
+        is_enabled:
+          allOf:
+            - $ref: '#/components/schemas/is_enabled'
+          description: Whether the employee is enabled in the organisation.
+        has_accepted_invite:
+          $ref: '#/components/schemas/has_accepted_invite'
+        delegatees:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/delegatees'
+          description: List of users who are delegatees for this employee.
     org_summary_out:
       type: object
       additionalProperties: false

src/approver/openapi.yaml

@@ -194,6 +194,8 @@ paths:
     $ref: paths/approver@files@download.yaml
   /approver/employees:
     $ref: paths/approver@employees.yaml
+  /approver/org_employees:
+    $ref: paths/approver@org_employees.yaml
   /approver/orgs:
     $ref: paths/approver@orgs.yaml
   /approver/org_settings:

src/approver/paths/approver@org_employees.yaml

@@ -0,0 +1,97 @@
+get:
+  x-internal: false
+  tags:
+    - Employees
+  summary: List organisation employees
+  operationId: org_employees_list
+  security:
+    - oauth2:
+        - '*'
+  description: |
+    Returns all employees from organisations in the same group as the approver's current
+    organisation where the approver has at least one non-disabled user expense approval.
+
+    This API supplies employee filter values for Team Expenses and Reports.
+    Each employee includes `org_id` to identify their organisation.
+
+    Pass `org_id=eq.<org_id>` to list employees for one authorised organisation.
+    Omit `org_id` to list employees across all authorised organisations.
+    An unauthorised `org_id` returns an empty `data` array with `count: 0`.
+
+    Filtering on response fields, sorting and pagination are supported. See the
+    [Guide to Data APIs](https://docs.fylehq.com/docs/fyle-platform-docs/ZG9jOjI3Mzk2NTM3-guide-to-data-ap-is#filtering)
+    for query syntax. Delegates with the APPROVE or ALL scope can access this API.
+  parameters:
+    - in: query
+      name: org_id
+      required: false
+      description: Filter by organisation; omit to return employees from all authorised organisations.
+      schema:
+        type: string
+        example: eq.orwruogwnngg
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            type: object
+            additionalProperties: false
+            required:
+              - data
+              - count
+              - offset
+            properties:
+              count:
+                $ref: ../../components/schemas/count.yaml
+              offset:
+                $ref: ../../components/schemas/offset.yaml
+              data:
+                type: array
+                items:
+                  $ref: ../../components/schemas/employee.yaml#/approver_org_employee_out
+          example:
+            count: 1
+            offset: 0
+            data:
+              - id: ouxNjRaFhue2
+                user_id: usdM767Q2gox
+                org_id: orwruogwnngg
+                email: john.doe@example.com
+                full_name: John Doe
+                roles:
+                  - FYLER
+                mobile: '+12131234567'
+                is_mobile_verified: true
+                sms_opt_out_source: null
+                commute_details:
+                  id: null
+                  home_location: null
+                  work_location: null
+                  distance: null
+                  distance_unit: null
+                is_enabled: true
+                has_accepted_invite: true
+                delegatees: []
+    '400':
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/400.yaml
+    '401':
+      description: Unauthorized request
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/401.yaml
+    '403':
+      description: The current user does not have permission to access this API.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                example: you don't have permissions to access this resource

src/components/schemas/employee.yaml

@@ -795,6 +795,70 @@ spender_employee_out:
         List of users who are delegatees for this employee.
 
 
+approver_org_employee_out:
+  type: object
+  additionalProperties: false
+  required:
+    - id
+    - user_id
+    - org_id
+    - email
+    - full_name
+    - roles
+    - commute_details
+    - mobile
+    - is_mobile_verified
+    - sms_opt_out_source
+    - is_enabled
+    - has_accepted_invite
+    - delegatees
+  properties:
+    id:
+      $ref: ./fields.yaml#/id_string
+    user_id:
+      $ref: ./fields.yaml#/user_id
+    org_id:
+      $ref: ./fields.yaml#/org_id
+    email:
+      $ref: ./fields.yaml#/email
+    full_name:
+      $ref: ./fields.yaml#/user_full_name
+    roles:
+      type: array
+      items:
+        $ref: ./fields.yaml#/role
+    commute_details:
+      $ref: ./fields.yaml#/commute_details
+    mobile:
+      type: string
+      nullable: true
+      example: '+12131234567'
+      description: Mobile number of the employee.
+    is_mobile_verified:
+      type: boolean
+      nullable: true
+      description: Whether the employee's mobile number is verified.
+      example: false
+    sms_opt_out_source:
+      type: string
+      nullable: true
+      maxLength: 255
+      description: Whether the employee opted out of SMS through the web app or SMS.
+      example: WEB_APP
+    is_enabled:
+      allOf:
+        - $ref: ./fields.yaml#/is_enabled
+      description: Whether the employee is enabled in the organisation.
+    has_accepted_invite:
+      $ref: ./fields.yaml#/has_accepted_invite
+    delegatees:
+      type: array
+      nullable: true
+      items:
+        $ref: ./fields.yaml#/delegatees
+      description: List of users who are delegatees for this employee.
+
+
 employees_upload_in:
   type: object
   properties: