# Weel API The Weel API 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. Version: v1 ## Servers ``` https://public.letsweel.com ``` ## Security ### BearerAuth Type: http Scheme: bearer ## Download OpenAPI description [Weel API](https://developer.letsweel.com/_bundle/openapi.yaml) ## Invites 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. ### List invites - [GET /v1/businesses/{client_id}/invites](https://developer.letsweel.com/openapi/invites/listinvites.md): Returns a paginated list of invites for the given business. Includes both pending and accepted invites; excludes cancelled invites. ### Create invite - [POST /v1/businesses/{client_id}/invites](https://developer.letsweel.com/openapi/invites/createinvite.md): Creates and sends an invite to the given email address. Returns the created invite, including its ID for use in the cancel endpoint. ### Cancel invite - [DELETE /v1/businesses/{client_id}/invites/{invite_id}](https://developer.letsweel.com/openapi/invites/cancelinvite.md): Cancels a pending invite. Returns 400 if the invite has already been accepted. ## Users This group of endpoints allows you to retrieve and manage user data, including listing users and fetching individual user details. ### List users - [GET /v1/businesses/{client_id}/users](https://developer.letsweel.com/openapi/users/listusers.md): This endpoint allows you to retrieve a list of users for a given business. ### Get user - [GET /v1/businesses/{client_id}/users/{user_id}](https://developer.letsweel.com/openapi/users/getuser.md): This endpoint allows you to retrieve a user by their ID. ### Update user - [PATCH /v1/businesses/{client_id}/users/{user_id}](https://developer.letsweel.com/openapi/users/updateuser.md): Update role, payment types, and/or delegation settings for an active employee. All fields in the request body are optional. ### Delete user - [DELETE /v1/businesses/{client_id}/users/{user_id}](https://developer.letsweel.com/openapi/users/deleteuser.md): Deletes an active employee. ### List budget members by user ID - [GET /v1/businesses/{client_id}/users/{user_id}/budget-members](https://developer.letsweel.com/openapi/users/listbudgetmembersbyuser.md): This endpoint allows you to retrieve budget members by their user ID. ## Roles This group of endpoints allows you to retrieve the roles available within a business and the permissions assigned to each role. ### List roles - [GET /v1/businesses/{client_id}/roles](https://developer.letsweel.com/openapi/roles/listroles.md): Returns the available roles that can be assigned to users within a business. ## Transactions This group of endpoints allows you to retrieve and manage transaction data, including listing transactions with various filters and fetching individual transaction details. ### List transactions - [GET /v2/businesses/{client_id}/transactions](https://developer.letsweel.com/openapi/transactions/listtransactions.md): This endpoint allows you to retrieve a list of transactions for a given business. You can filter the transactions by date range, status, and expense completion status. ### Get transaction - [GET /v2/businesses/{client_id}/transactions/{transaction_id}](https://developer.letsweel.com/openapi/transactions/gettransaction.md) ## Budgets 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) ### List budgets - [GET /v1/businesses/{client_id}/budgets](https://developer.letsweel.com/openapi/budgets/listbudgets.md) ### Create a budget - [POST /v1/businesses/{client_id}/budgets](https://developer.letsweel.com/openapi/budgets/createbudget.md): Creates a budget with the given configuration, initial members, and owners. All top-level configuration fields are required — no silent defaults. ### Get budget - [GET /v1/businesses/{client_id}/budgets/{budget_id}](https://developer.letsweel.com/openapi/budgets/getbudget.md) ### Update a budget - [PATCH /v1/businesses/{client_id}/budgets/{budget_id}](https://developer.letsweel.com/openapi/budgets/updatebudget.md): Updates a budget's top-level configuration. To change members or owners, use their respective endpoints — budget members and budget owners. ### Delete a budget - [DELETE /v1/businesses/{client_id}/budgets/{budget_id}](https://developer.letsweel.com/openapi/budgets/deletebudget.md): Deletes a budget. Cascades to members and owners. ## Budget Members This group of endpoints allows you to retrieve and manage budget member data, including listing budget members and fetching individual budget member details. ### List budget members - [GET /v1/businesses/{client_id}/budgets/{budget_id}/members](https://developer.letsweel.com/openapi/budget-members/listbudgetmembers.md): A budget member is a user who has been invited to a budget. ### Add budget member - [POST /v1/businesses/{client_id}/budgets/{budget_id}/members](https://developer.letsweel.com/openapi/budget-members/createbudgetmember.md): Adds a user (or pending invite) as a member of the budget. Provide exactly one of user or invite. If an invite has already been accepted, the response will contain user rather than invite. Side effect: On budgets with per-member limits, adding a member increases the budget's total limit and available amount by the new member's reset_amount. Re-fetch the budget if you need the updated totals. Shared-pot budgets are unaffected. ### Get budget member - [GET /v1/businesses/{client_id}/budgets/{budget_id}/members/{budget_member_id}](https://developer.letsweel.com/openapi/budget-members/getbudgetmember.md) ### Update budget member - [PATCH /v1/businesses/{client_id}/budgets/{budget_id}/members/{budget_member_id}](https://developer.letsweel.com/openapi/budget-members/updatebudgetmember.md): Updates a budget member's reset_amount. Only valid when the budget has has_member_limits=true and reset_period is not NEVER. Side effect: The budget's total limit changes by the difference between the old and new reset_amount. The budget's available amount is not touched — use topups to change live balances. ### Remove budget member - [DELETE /v1/businesses/{client_id}/budgets/{budget_id}/members/{budget_member_id}](https://developer.letsweel.com/openapi/budget-members/deletebudgetmember.md): Deletes the budget member. If the member has an associated card, the card is revoked asynchronously. A budget must retain at least one member. Side effect: On budgets with per-member limits, removing a member reduces the budget's total limit and available amount by the member's share. ## Budget Owners 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. ### List budget owners - [GET /v1/businesses/{client_id}/budgets/{budget_id}/owners](https://developer.letsweel.com/openapi/budget-owners/listbudgetowners.md): Lists owners of the budget. ### Add budget owner - [POST /v1/businesses/{client_id}/budgets/{budget_id}/owners](https://developer.letsweel.com/openapi/budget-owners/createbudgetowner.md): Adds a user (or pending invite) as an owner of the budget. Provide exactly one of user or invite. If an invite has already been accepted, the response will contain user rather than invite. If the same user or invite was previously removed from this budget, the original record is reinstated rather than a new one created — the returned id will match the original owner's id. ### Remove budget owner - [DELETE /v1/businesses/{client_id}/budgets/{budget_id}/owners/{budget_owner_id}](https://developer.letsweel.com/openapi/budget-owners/deletebudgetowner.md): Removes the owner from the budget. A budget must retain at least one active owner. ## Budget Topups 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) ### List budget topups - [GET /v1/businesses/{client_id}/budgets/{budget_id}/topups](https://developer.letsweel.com/openapi/budget-topups/listbudgettopups.md): List the topups for a budget. ### Create budget topup - [POST /v1/businesses/{client_id}/budgets/{budget_id}/topups](https://developer.letsweel.com/openapi/budget-topups/createbudgettopup.md): Increase or decrease the available amount of a budget. Only permitted when has_member_limits is false for the budget. ### List budget member topups - [GET /v1/businesses/{client_id}/budgets/{budget_id}/members/{budget_member_id}/topups](https://developer.letsweel.com/openapi/budget-topups/listbudgetmembertopups.md): List the topups for a budget member. ### Create budget member topup - [POST /v1/businesses/{client_id}/budgets/{budget_id}/members/{budget_member_id}/topups](https://developer.letsweel.com/openapi/budget-topups/createbudgetmembertopup.md): Increase or decrease the available amount of a budget member. Only permitted when has_member_limits is true for the budget. ## Statements This group of endpoints allows you to retrieve a list of balances for the required period for a given business. ### List statements - [GET /v1/businesses/{client_id}/statements](https://developer.letsweel.com/openapi/statements/liststatements.md): This endpoint allows you to retrieve a list of balances for the required period for a given business. ### Get account balances - [GET /v1/businesses/{client_id}/balance](https://developer.letsweel.com/openapi/statements/listbalances.md): Retrieve real-time account balances for all currencies associated with your business. This endpoint returns the current balance for each currency wallet associated with your business account. ## Custom Fields 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. ### List custom fields - [GET /v1/businesses/{client_id}/custom-fields](https://developer.letsweel.com/openapi/custom-fields/listcustomfields.md): Returns a paginated list of custom fields for the given business. ### Create a custom field - [POST /v1/businesses/{client_id}/custom-fields](https://developer.letsweel.com/openapi/custom-fields/createcustomfield.md): Creates a new custom field for the given business. The created_by value will be set to PUBLIC_API. ### Get a custom field - [GET /v1/businesses/{client_id}/custom-fields/{custom_field_id}](https://developer.letsweel.com/openapi/custom-fields/getcustomfield.md): Returns a single custom field by ID. ### Update a custom field - [PATCH /v1/businesses/{client_id}/custom-fields/{custom_field_id}](https://developer.letsweel.com/openapi/custom-fields/updatecustomfield.md): Partially updates a custom field. Restrictions for accounting integration fields (created by Xero, MYOB, QuickBooks, NetSuite, or Business Central): the name field cannot be changed. Only budget_setting can be updated. ### Delete a custom field - [DELETE /v1/businesses/{client_id}/custom-fields/{custom_field_id}](https://developer.letsweel.com/openapi/custom-fields/deletecustomfield.md): Deletes a custom field. This also removes all associated options and budget links. ## Custom Field Options 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. ### List custom field options - [GET /v1/businesses/{client_id}/custom-fields/{custom_field_id}/options](https://developer.letsweel.com/openapi/custom-field-options/listcustomfieldoptions.md): Returns a paginated list of all options for the given custom field, including disabled ones. ### Create a custom field option - [POST /v1/businesses/{client_id}/custom-fields/{custom_field_id}/options](https://developer.letsweel.com/openapi/custom-field-options/createcustomfieldoption.md): Adds a new option to a LIST type custom field. Not permitted for FREE_TEXT custom fields or custom fields created by accounting integrations. ### Update a custom field option - [PATCH /v1/businesses/{client_id}/custom-fields/{custom_field_id}/options/{option_id}](https://developer.letsweel.com/openapi/custom-field-options/updatecustomfieldoption.md): Partially updates a custom field option. Accounting integration fields (Xero, MYOB, QuickBooks, NetSuite, Business Central): only enabled can be changed. The text field cannot be modified. Non-accounting-integration fields (MANUAL, PUBLIC_API): only text can be changed. The enabled field cannot be modified — delete and recreate options instead. ### Delete a custom field option - [DELETE /v1/businesses/{client_id}/custom-fields/{custom_field_id}/options/{option_id}](https://developer.letsweel.com/openapi/custom-field-options/deletecustomfieldoption.md): Permanently deletes a custom field option. Not permitted for options belonging to custom fields created by accounting integrations. ## Custom Field Budgets This group of endpoints allows you to link custom fields to budgets, controlling which budgets have a custom field assigned. ### List budgets linked to a custom field - [GET /v1/businesses/{client_id}/custom-fields/{custom_field_id}/budgets](https://developer.letsweel.com/openapi/custom-field-budgets/listcustomfieldbudgets.md): Returns a paginated list of budgets that have this custom field assigned. ### Link a budget to a custom field - [POST /v1/businesses/{client_id}/custom-fields/{custom_field_id}/budgets](https://developer.letsweel.com/openapi/custom-field-budgets/linkcustomfieldbudget.md): Assigns a custom field to a budget. The budget must belong to the same business. Only permitted when the custom field's budget_setting is SOME. ### Unlink a budget from a custom field - [DELETE /v1/businesses/{client_id}/custom-fields/{custom_field_id}/budgets/{budget_id}](https://developer.letsweel.com/openapi/custom-field-budgets/unlinkcustomfieldbudget.md): Removes the link between a custom field and a budget. ## Accounting Codes 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. ### List accounting codes - [GET /v1/businesses/{client_id}/accounting-codes](https://developer.letsweel.com/openapi/accounting-codes/listaccountingcodes.md): Returns a paginated list of GL codes for the given business. ### Create or update an accounting code - [POST /v1/businesses/{client_id}/accounting-codes](https://developer.letsweel.com/openapi/accounting-codes/upsertaccountingcode.md): Creates or updates a GL code for the business (upsert by code). - If a GL code with the given code already exists, its name is updated. - If a previously soft-deleted GL code with that code exists, it is restored. - Otherwise a new record is created. Only available for businesses with a manual integration or no integration. If no integration exists, a manual integration is automatically created. Returns 400 if the business has a connected accounting provider (Xero, MYOB, NetSuite, QuickBooks, Business Central). ### Delete an accounting code - [DELETE /v1/businesses/{client_id}/accounting-codes/{accounting_code_id}](https://developer.letsweel.com/openapi/accounting-codes/deleteaccountingcode.md): Soft-deletes a GL code. Only available for businesses with a manual integration. Any category mapped to this GL code will have its mapping cleared. Business admins and accountants will receive an ACCOUNTING_CODE_DELETED notification. ## Categories 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. ### List categories - [GET /v1/businesses/{client_id}/categories](https://developer.letsweel.com/openapi/categories/listcategories.md): Returns a paginated list of expense categories for the given business. ### Create a category - [POST /v1/businesses/{client_id}/categories](https://developer.letsweel.com/openapi/categories/createcategory.md): Creates a new custom category (custom: true) for the business. The name must be unique within the business. ### Update a category - [PATCH /v1/businesses/{client_id}/categories/{category_id}](https://developer.letsweel.com/openapi/categories/updatecategory.md): Updates an existing category. Accepted fields depend on the category type: - Custom categories (custom: true): name and accounting_code_id are mutable; enabled returns 400. - System categories (custom: false): enabled and accounting_code_id are mutable; name returns 400. ### Delete a category - [DELETE /v1/businesses/{client_id}/categories/{category_id}](https://developer.letsweel.com/openapi/categories/deletecategory.md): Soft-deletes a custom category. Returns 400 if the category is system-defined (custom: false).