openapi: 3.2.0
info:
  title: Weel Open Users API
  version: v1
  termsOfService: https://letsweel.com/terms/
  contact:
    name: Contact our support
    email: help@letsweel.com
    url: https://help.letsweel.com
  description: 'The Weel OpenAPI empowers businesses with seamless expense management and real-time insights. Our platform makes it easy to integrate and automate expense workflows, manage receipts, and keep track of spending across your organization.

    '
servers:
- url: https://public.letsweel.com
security:
- BearerAuth: []
tags:
- name: Users
  description: This group of endpoints allows you to retrieve and manage user data, including listing users and fetching individual user details.
paths:
  /v1/businesses/{client_id}/users:
    get:
      operationId: listUsers
      description: This endpoint allows you to retrieve a list of users for a given business.
      tags:
      - Users
      summary: List users
      parameters:
      - $ref: '#/components/parameters/PaginationOffset'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/ClientId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - BearerAuth: []
  /v1/businesses/{client_id}/users/{user_id}:
    get:
      operationId: getUser
      description: This endpoint allows you to retrieve a user by their ID.
      tags:
      - Users
      summary: Get user
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - BearerAuth: []
    patch:
      operationId: updateUser
      description: 'Update role, payment types, and/or delegation settings for an active employee.

        All fields in the request body are optional.

        '
      tags:
      - Users
      summary: Update user
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - BearerAuth: []
    delete:
      operationId: deleteUser
      description: Deletes an active employee.
      tags:
      - Users
      summary: Delete user
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/UserId'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '503':
          description: Service Unavailable
      security:
      - BearerAuth: []
  /v1/businesses/{client_id}/users/{user_id}/budget-members:
    get:
      operationId: listBudgetMembersByUser
      description: This endpoint allows you to retrieve budget members by their user ID.
      tags:
      - Users
      summary: List budget members by user ID
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBudgetMemberListResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
      - BearerAuth: []
components:
  schemas:
    UserListResponse:
      type: object
      properties:
        count:
          type: integer
          description: The total number of users that match the query.
          example: 100
        next:
          type: string
          description: The URL to the next page of users.
          example: offset=50&limit=50
        previous:
          type: string
          description: The URL to the previous page of users.
          example: offset=0&limit=50
        results:
          type: array
          items:
            $ref: '#/components/schemas/User'
    UserBudgetMemberListResponse:
      type: object
      properties:
        count:
          type: integer
          description: The total number of budget members for the user.
          example: 100
        next:
          type: string
          description: The URL to the next page of budget members.
          example: offset=50&limit=50
        previous:
          type: string
          description: The URL to the previous page of budget members.
          example: offset=0&limit=50
        results:
          type: array
          items:
            $ref: '#/components/schemas/UserBudgetMember'
    PaymentType:
      type: string
      enum:
      - bills
      - cards
      - reimbursements
    UserBudget:
      type: object
      properties:
        id:
          type: string
          description: The ID of the budget.
          example: e33b7c61-5124-4ba0-b238-e4c573133715
        name:
          type: string
          description: The name of the budget.
          example: Sales Team
        budget_type:
          type: string
          description: The type of budget.
          enum:
          - BUDGET
          - SUBSCRIPTION
          example: BUDGET
    UserBudgetMember:
      type: object
      properties:
        id:
          type: string
          description: The ID of the budget member.
          example: e33b7c61-5124-4ba0-b238-e4c573133715
        budget:
          description: The budget for the budget member.
          $ref: '#/components/schemas/UserBudget'
        available_amount:
          type: number
          description: The available amount of the budget member.
          example: 800
        spent_amount:
          type: number
          description: The amount of the budget that has been spent by the budget member.
          example: 200
        reset_amount:
          type: number
          description: The reset amount of the budget member.
          example: 1000
        is_deleted:
          type: boolean
          description: Whether the budget member is deleted.
          example: false
        created:
          type: string
          format: date-time
          description: The date and time when the budget member was created in UTC.
          example: '2024-01-01T00:00:00Z'
        updated:
          type: string
          format: date-time
          description: The date and time when the budget member was last updated in UTC.
          example: '2024-01-01T00:00:00Z'
    User:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the user.
          example: 123
        first_name:
          type: string
          description: The first name of the user.
          example: John
        last_name:
          type: string
          description: The last name of the user.
          example: Doe
        name:
          type: string
          description: The full name of the user or the display name if the user has set one.
          example: John Doe
        email:
          type: string
          format: email
          description: The email of the user.
          example: john.doe@example.com
        role:
          type: string
          description: The role of the user.
          example: Team Member
        role_id:
          type: string
          format: uuid
          description: The ID of the user's role.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        is_deleted:
          type: boolean
          description: Whether the user is deleted.
          example: false
        created:
          type: string
          format: date-time
          description: The date and time when the user was created in UTC.
          example: '2024-01-01T00:00:00Z'
        updated:
          type: string
          format: date-time
          description: The date and time when the user was last updated in UTC.
          example: '2024-01-01T00:00:00Z'
        payment_types:
          type: array
          description: The payment types the user can transact with.
          items:
            $ref: '#/components/schemas/PaymentType'
          example:
          - cards
        out_of_office_mode:
          type: boolean
          description: Whether the user is out of office.
          example: true
        out_of_office_start_date:
          type:
          - string
          - 'null'
          format: date
          description: First day of the out-of-office period (inclusive).
          example: '2026-06-01'
        out_of_office_end_date:
          type:
          - string
          - 'null'
          format: date
          description: Last day of the out-of-office period (inclusive).
          example: '2026-06-15'
        delegate_approver:
          type:
          - integer
          - 'null'
          description: The user ID to delegate approvals to while out of office.
          example: 789
        expense_delegate:
          type:
          - array
          - 'null'
          items:
            type: integer
          description: The user IDs of this user's expense assistants (who can act on their expenses). Null if the business does not have the expense assistant feature.
          example:
          - 456
          - 789
    UserUpdate:
      type: object
      description: Fields that may be updated on an active employee. All optional.
      properties:
        role_id:
          type: string
          format: uuid
          description: The role to assign to the user. Must belong to the same business.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        payment_types:
          type: array
          description: The payment types the user can transact with.
          items:
            $ref: '#/components/schemas/PaymentType'
          example:
          - cards
        out_of_office_mode:
          type: boolean
          description: Whether the user is out of office. When true, both start and end dates are required.
          example: true
        out_of_office_start_date:
          type: string
          format: date
          description: First day of the out-of-office period (inclusive).
          example: '2026-06-01'
        out_of_office_end_date:
          type: string
          format: date
          description: Last day of the out-of-office period (inclusive). Must be on or after the start date.
          example: '2026-06-15'
        delegate_approver:
          type:
          - integer
          - 'null'
          description: The user ID to delegate approvals to while out of office. Must belong to the same business and have no overlapping out-of-office period.
          example: 789
        expense_delegate:
          type: array
          items:
            type: integer
          description: Replaces the user's full set of expense assistants with these user IDs. A user can have at most 3 expense assistants. Each ID must belong to the same business, must be a different user (a user cannot be their own expense assistant), and must not be repeated. Expense assistants cannot be chained. A user who is themselves an expense assistant cannot be given assistants, and a user who already has assistants cannot be assigned as one. Omit this field to leave the current assistants unchanged, or send an empty array to remove them all.
          example:
          - 456
          - 789
  parameters:
    PaginationOffset:
      name: offset
      in: query
      description: Offset to retrieve items from.
      schema:
        type: integer
        default: 0
        example: 50
    ClientId:
      name: client_id
      in: path
      description: The ID of the business.
      required: true
      schema:
        type: integer
        example: 123
    PaginationLimit:
      name: limit
      in: query
      description: Number of items per page.
      schema:
        type: integer
        default: 50
        maximum: 500
        example: 50
    UserId:
      name: user_id
      in: path
      description: The ID of the user.
      required: true
      schema:
        type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Users
  tags:
  - Invites
  - Users
  - Roles
- name: Transactions
  tags:
  - Transactions
- name: Budgets
  tags:
  - Budgets
  - Budget Members
  - Budget Owners
  - Budget Topups
- name: Statements
  tags:
  - Statements
- name: Custom Fields
  tags:
  - Custom Fields
  - Custom Field Options
  - Custom Field Budgets
- name: Chart of Accounts
  tags:
  - Accounting Codes
  - Categories