Weel Open API

openapi: 3.1.0
info:
  title: Weel OpenAPI
  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: []
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
tags:
  - name: Transactions
    description: >-
      This group of endpoints allows you to retrieve and manage transaction
      data, including listing transactions with various filters and fetching
      individual transaction details.
  - name: Users
    description: >-
      This group of endpoints allows you to retrieve and manage user data,
      including listing users and fetching individual user details.
  - name: Invites
    description: >-
      This group of endpoints allows you to create, list, and cancel pending
      user invitations. An invite exists until the recipient accepts it, at
      which point they appear as a user in the Users endpoints.
  - name: Roles
    description: >-
      This group of endpoints allows you to retrieve the roles available within
      a business and the permissions assigned to each role.
  - name: Budgets
    description: >
      This group of endpoints allows you to retrieve and manage budget data,
      including listing budgets and fetching individual budget details.


      Budgets are organised in a hierarchy where a budget can have multiple
      members. Each member is associated with a user. Funds can be allocated at
      the budget level or at the member level, using the flag
      `has_member_limits`.


      ![Budget Hierachy](assets/budget-hierarchy.png)
  - name: Budget Members
    description: >-
      This group of endpoints allows you to retrieve and manage budget member
      data, including listing budget members and fetching individual budget
      member details.
  - name: Budget Owners
    description: >
      This group of endpoints allows you to retrieve and manage budget owners. A
      budget owner is a user (or pending invite) who can approve spend, top up,
      and otherwise manage the budget.


      A budget must always have at least one active owner — deleting the last
      remaining owner is not permitted. Adding an owner who was previously
      removed will reinstate the original record rather than create a duplicate.
  - name: Budget Topups
    description: >
      This group of endpoints allows you to retrieve and create budget topups.
      Topups are used to increase or decrease the available amount of a budget
      or budget member.


      Topups will be automatically approved, unless a Workflow or Policy has
      been configured in Weel for that requires approval for budget topups.


      There are two types of topups:
        - Budget topups are used to increase or decrease the available amount of a budget. This is only permitted when `has_member_limits` is `false` for the budget.
        - Budget member topups are used to increase or decrease the available amount of a budget member. This is only permitted when `has_member_limits` is `true` for the budget.

      `has_member_limits` is set to `true` when this toggle is enabled in the
      budget creation form.
        ![Has Member Limits is true](assets/has-member-limits-true.png)
  - name: Statements
    description: >-
      This group of endpoints allows you to retrieve a list of balances for the
      required period for a given business.
  - name: Custom Fields
    description: >
      This group of endpoints allows you to create and manage custom fields
      (dimensions/cost centres) for your business.


      Custom fields can be of type `LIST` (with predefined options) or
      `FREE_TEXT`. Custom fields created via the Public API have a `created_by`
      value of `PUBLIC_API`.


      Custom fields created by accounting integrations (Xero, MYOB, QuickBooks,
      NetSuite, Business Central) have restrictions: their name and type cannot
      be modified via the Public API.
  - name: Custom Field Options
    description: >-
      This group of endpoints allows you to manage the list options for a `LIST`
      type custom field. Options created via the Public API can be disabled or
      deleted.
  - name: Custom Field Budgets
    description: >-
      This group of endpoints allows you to link custom fields to budgets,
      controlling which budgets have a custom field assigned.
  - name: Accounting Codes
    description: >
      This group of endpoints allows you to manage GL codes (accounting codes)
      for your business.


      GL codes are used to classify expenses for bookkeeping export. Businesses
      with a connected accounting integration (Xero, MYOB, NetSuite, QuickBooks,
      Business Central) cannot create or delete GL codes via the API — those are
      managed by the integration sync. Businesses with a manual integration or
      no integration can freely create, update, and delete GL codes. A manual
      integration is automatically created on the first POST if none exists.
  - name: Categories
    description: >
      This group of endpoints allow you to manage expense categories for your
      business.


      Categories classify transactions. System-defined categories (`custom:
      false`) can only have their `enabled` state toggled. Custom categories
      (`custom: true`) can have their `name` updated and can be deleted.
  - name: Tax Rates
    description: >
      This group of endpoints allows you to retrieve the tax rates configured
      for your business. Tax rates are read-only via the Public API.


      For businesses with a connected accounting integration (Xero, MYOB,
      NetSuite, QuickBooks, Business Central), the tax rates synced from that
      integration are returned. Businesses without a connected integration get
      their own manually configured tax rates.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  parameters:
    PaginationOffset:
      name: offset
      in: query
      description: Offset to retrieve items from.
      schema:
        type: integer
        default: 0
        example: 50
    PaginationLimit:
      name: limit
      in: query
      description: Number of items per page.
      schema:
        type: integer
        default: 50
        maximum: 500
        example: 50
    ClientId:
      name: client_id
      in: path
      description: The ID of the business.
      required: true
      schema:
        type: integer
        example: 123
    IsDeleted:
      name: is_deleted
      in: query
      description: Whether the resource is deleted.
      schema:
        type: boolean
        example: false
    TransactionId:
      name: transaction_id
      in: path
      description: The ID of the transaction.
      required: true
      schema:
        type: string
    UserId:
      name: user_id
      in: path
      description: The ID of the user.
      required: true
      schema:
        type: integer
    BudgetId:
      name: budget_id
      in: path
      description: The ID of the budget.
      required: true
      schema:
        type: string
    BudgetMemberId:
      name: budget_member_id
      in: path
      description: The ID of the budget member.
      required: true
      schema:
        type: integer
    BudgetOwnerId:
      name: budget_owner_id
      in: path
      description: The ID of the budget owner.
      required: true
      schema:
        type: string
    CustomFieldId:
      name: custom_field_id
      in: path
      description: The ID of the custom field.
      required: true
      schema:
        type: string
        format: uuid
        example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    CustomFieldOptionId:
      name: option_id
      in: path
      description: The ID of the custom field option.
      required: true
      schema:
        type: string
        format: uuid
        example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    InviteId:
      name: invite_id
      in: path
      description: The ID of the invite.
      required: true
      schema:
        type: integer
    AccountingCodeId:
      name: accounting_code_id
      in: path
      description: The ID of the accounting code (GL code).
      required: true
      schema:
        type: string
        format: uuid
        example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    CategoryId:
      name: category_id
      in: path
      description: The ID of the category.
      required: true
      schema:
        type: string
        format: uuid
        example: 7cb19e45-1234-5678-abcd-ef9876543210
    TaxRateId:
      name: tax_rate_id
      in: path
      description: The ID of the tax rate.
      required: true
      schema:
        type: string
        format: uuid
        example: e33b7c61-5124-4ba0-b238-e4c573133715
  schemas:
    StatementListResponse:
      type: object
      properties:
        count:
          type: integer
          description: The total number of daily balance records for the given period.
          example: 100
        next:
          type: string
          description: The URL to the next page of daily balance records.
          example: offset=50&limit=50
        previous:
          type: string
          description: The URL to the previous page of daily balance records.
          example: offset=0&limit=50
        start_date:
          type: string
          format: date
          description: The start date for this statement in UTC.
          example: '2024-01-01'
        end_date:
          type: string
          format: date
          description: The end date for this statement in UTC.
          example: '2024-01-31'
        currency:
          type: string
          description: The currency of the statement.
          example: AUD
        opening_balance:
          type: number
          description: The opening balance of the statement.
          example: 1000
        closing_balance:
          type: number
          description: The closing balance of the statement.
          example: 1000
        daily_balances:
          type: array
          items:
            $ref: '#/components/schemas/DailyBalance'
    DailyBalance:
      type: object
      properties:
        date:
          type: string
          format: date
          description: The date of the daily balance.
          example: '2024-01-01'
        opening_balance:
          type: number
          description: The opening balance of this date.
          example: 1000
        closing_balance:
          type: number
          description: The closing balance of this date.
          example: 1000
        id:
          type: string
          description: The ID of the daily balance.
          example: e33b7c61-5124-4ba0-b238-e4c573133715
        created:
          type: string
          format: date-time
          description: The date and time when the balance was generated in UTC.
          example: '2024-01-01T00:00:00Z'
        updated:
          type: string
          format: date-time
          description: The date and time when the balance was last updated in UTC.
          example: '2024-01-01T00:00:00Z'
    TransactionListResponse:
      type: object
      properties:
        count:
          type: integer
          description: The total number of transactions that match the query.
          example: 100
        next:
          type: string
          description: The URL to the next page of transactions.
          example: offset=50&limit=50
        previous:
          type: string
          description: The URL to the previous page of transactions.
          example: offset=0&limit=50
        results:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
    Transaction:
      type: object
      properties:
        id:
          type: string
          description: The ID of the transaction.
          example: e33b7c61-5124-4ba0-b238-e4c573133715
        cleared_date:
          type:
            - string
            - 'null'
          format: date-time
          description: The date the transaction was cleared in UTC.
          example: '2024-01-01T00:00:00Z'
        auth_date:
          type: string
          format: date-time
          description: The date the transaction was authorised in UTC.
          example: '2024-01-01T00:00:00Z'
        merchant_name:
          type: string
          description: The name of the merchant.
          example: Bunnings Warehouse
        attendees:
          type: array
          description: The names of the attendees of the transaction.
          items:
            type: string
            description: The name of the attendee.
            example: Jane Doe
        budget:
          $ref: '#/components/schemas/TransactionBudget'
          description: The budget associated with the transaction.
        currency:
          type: string
          description: The currency of the transaction.
          example: AUD
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValue'
        fx_amount:
          type: number
          description: The foreign currency amount of the transaction.
          example: 100
        amount:
          type: number
          description: >-
            The amount of the transaction in AUD (positive for credits, negative
            for debits).
          example: -100
        gst:
          type: number
          description: The GST amount of the transaction.
          example: 9.09
        expense_status:
          type: string
          description: The expense completion status of the transaction.
          enum:
            - COMPLETE
            - INCOMPLETE_EXPENSE
          example: COMPLETE
        status:
          type: string
          description: The status of the transaction.
          enum:
            - CLEARED
            - AUTHED
          example: CLEARED
        transaction_type:
          type: string
          description: The type of transaction.
          enum:
            - CARD_TRANSACTION
            - CHARGE
            - DEPOSIT_DIRECT_CREDIT
            - DEPOSIT_DIRECT_DEBIT
            - BILL
            - REIMBURSEMENT
            - EXTERNAL_TRANSFER
            - MANUAL_TRANSFER
            - CREDIT
          example: CARD_TRANSACTION
        user:
          description: The user who made the transaction.
          $ref: '#/components/schemas/SubUser'
        line_items:
          type: array
          description: The line items of the transaction.
          items:
            $ref: '#/components/schemas/LineItem'
        receipt_urls:
          type: array
          description: The URLs of the receipts for the transaction.
          items:
            type: string
            example: >-
              https://divipay-user-production.s3.amazonaws.com/123/68eae8f6-cb90-4403-ba76-a2cc12c3979j.png
        created:
          type: string
          format: date-time
          description: The date and time when the transaction was created in UTC.
          example: '2024-01-01T00:00:00Z'
        updated:
          type: string
          format: date-time
          description: The date and time when the transaction was last updated in UTC.
          example: '2024-01-01T00:00:00Z'
    TransactionBudget:
      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
    LineItem:
      type: object
      properties:
        id:
          type: string
          description: The ID of the line item.
          example: e33b7c61-5124-4ba0-b238-e4c573133715
        amount:
          type: number
          description: The amount of the line item in AUD.
          example: 100
        gst_amount:
          type: number
          description: >
            The GST amount of the line item. When a `tax_rate` is applied to the
            line item, this is derived from `tax_rate.rate`.
          example: 9.09
        tax_rate:
          $ref: '#/components/schemas/TaxRate'
          description: >
            The tax rate applied to the line item. This property has three
            states: it is absent when itemised tax rates are not enabled for the
            business; it is a `TaxRate` object when a tax rate could be resolved
            for the line item; and it is `null` when itemised tax rates are
            enabled for the business but a tax rate could not be resolved for
            the line item.
        category:
          $ref: '#/components/schemas/LineItemCategory'
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValue'
        description:
          type: string
          description: The description of the line item.
          example: Building supplies
    TaxRate:
      type:
        - object
        - 'null'
      description: >
        A tax rate applied to a line item. May be `null` when itemised tax rates
        are enabled for the business but a rate could not be resolved.
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the tax rate.
          example: e33b7c61-5124-4ba0-b238-e4c573133715
        name:
          type: string
          description: The name of the tax rate.
          example: GST
        rate:
          type: number
          description: The tax rate as a decimal fraction.
          example: 0.1
        code:
          type:
            - string
            - 'null'
          description: The tax rate code.
          example: GST
        is_default_for:
          type: string
          description: Which transaction types the tax rate is the default for.
          enum:
            - DOMESTIC
            - INTERNATIONAL
            - BOTH
            - NONE
          example: DOMESTIC
        is_enabled:
          type: boolean
          description: Whether the tax rate is enabled.
          example: true
        source:
          type: string
          description: The source of the tax rate.
          enum:
            - WEEL
            - MANUAL
            - ASP
          example: WEEL
    CustomFieldValue:
      type: object
      properties:
        field_name:
          type: string
          description: The name of the custom field.
          example: Project
        entry_text:
          type: string
          description: The text value of the custom field.
          example: Project 1
    InviteListResponse:
      type: object
      properties:
        count:
          type: integer
          description: The total number of invites that match the query.
          example: 10
        next:
          type:
            - string
            - 'null'
          description: The URL to the next page of invites.
          example: offset=50&limit=50
        previous:
          type:
            - string
            - 'null'
          description: The URL to the previous page of invites.
          example: null
        results:
          type: array
          items:
            $ref: '#/components/schemas/Invite'
    PaymentType:
      type: string
      enum:
        - bills
        - cards
        - reimbursements
    Invite:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the invite.
          example: 99
        email:
          type: string
          format: email
          description: The email address the invite was sent to.
          example: jane.doe@example.com
        role_id:
          type: string
          format: uuid
          description: The ID of the role assigned to the invitee.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        role:
          type: string
          description: The name of the role assigned to the invitee.
          example: Team Member
        payment_types:
          type: array
          items:
            $ref: '#/components/schemas/PaymentType'
          description: The payment types the invitee will have access to.
          example:
            - cards
            - reimbursements
        used:
          type: boolean
          description: Whether the invite has been accepted.
          example: false
        created:
          type: string
          format: date-time
          description: The date and time the invite was created in UTC.
          example: '2026-05-01T00:00:00Z'
        updated:
          type: string
          format: date-time
          description: The date and time the invite was last updated in UTC.
          example: '2026-05-01T00:00:00Z'
    InviteCreateRequest:
      type: object
      required:
        - email
        - role_id
        - payment_types
      properties:
        email:
          type: string
          format: email
          description: The email address to send the invite to.
          example: jane.doe@example.com
        role_id:
          type: string
          format: uuid
          description: >-
            The ID of the role to assign to the invitee. Must belong to the
            business.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        payment_types:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PaymentType'
          description: >-
            The payment types the invitee will have access to. Must be a
            non-empty list.
          example:
            - cards
            - reimbursements
    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'
    RoleListResponse:
      type: object
      properties:
        count:
          type: integer
          description: The total number of roles for the business.
          example: 5
        next:
          type: string
          description: The URL to the next page of roles.
          example: offset=50&limit=50
        previous:
          type: string
          description: The URL to the previous page of roles.
          example: offset=0&limit=50
        results:
          type: array
          items:
            $ref: '#/components/schemas/Role'
    Role:
      type: object
      required:
        - id
        - name
        - is_deletable
        - permissions
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the role.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: The name of the role.
          example: Team Member
        is_deletable:
          type: boolean
          description: Whether the role can be deleted.
          example: false
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
    Permission:
      type: object
      required:
        - resource
        - action
      properties:
        resource:
          type: string
          description: The resource the action applies to.
          example: transactions
        action:
          type: string
          description: The action permitted on the resource.
          enum:
            - create
            - read
            - update
            - delete
          example: read
    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
    SubUser:
      type:
        - object
        - 'null'
      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
    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'
    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:
     

# --- truncated at 32 KB (114 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/weel/refs/heads/main/openapi/weel-openapi.yml