---
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# UUIDs in Spend & Expense API

BILL is introducing UUIDs in the Spend & Expense API. Each ID value that uniquely identifies an entity in Spend & Expense (such as a budget, transaction, or user) now follows the UUID4 format.

UUID v4 (or UUID4) is a randomly-generated 128-bit identifier and is highly secure. The introduction of UUIDs in the Spend & Expense API is another measure taken by BILL for further improving its security standards.

## Spend & Expense webhook notifications

When BILL sends notifications for the `spend.transactions.updated` event, each ID in the notification payload is a UUID value. For example, `uuid` is the UUID of the transaction, and `userUuid` is the UUID of the user that created the transaction.

See [Spend & Expense transaction notification payloads](https://developer.bill.com/docs/spend-expense-transaction-notification-payloads) for more information.

> ❗️ IMPORTANT
>
> While the `spend.transactions.updated` notification payload includes only `uuid` values and no `id` values, the Spend & Expense API responses continue to present both `uuid` and `id` values.
>
> **In the future, the Spend & Expense`id` values will deprecated. We will share more information when we have a timeline for this deprecation.**

## GET operations

Let's use the example of budgets to understand the impact of introducing UUIDs on the Spend & Expense GET operations.

When you get details about a budget with `GET /v3/spend/budgets/{budgetId}`, you currently set the budget `id` in your API request. Moving forward, you can set the budget `uuid` as another method for getting details about a budget.

## GET response fields

For each existing Spend & Expense API object, BILL has generated a `uuid` value for each `id` value. In the `GET /v3/spend/budgets/{budgetId}`  response example, both the `uuid` and `id` values are available to uniquely identify the budget.

Similarly, for fields with an `id` suffix, we now have the same field with the `uuid` suffix to present the UUID value. For example, for the `parentBudgetId` field in the API response for a budget, we now have a additional `parentBudgetUuid` field to present the UUID of the parent budget.

```json UUIDs in a /v3/spend/budgets response
{
    "id": "QnVkZ2V0OjUyOTg2MQ==",
    "uuid": "bgt_mur9ttm5tt0m97tjj287s744t4",   // NEW UUID VALUE
    "name": "Happy Music Supplies monthly spending budget",
    "retired": false,
    "startDate": "2025-12-15",
    "recurringInterval": "MONTHLY",
    "timezone": "US/Eastern",
    "autoAddUsers": false,
    "receiptRequired": true,
    "carryOver": false,
    "budgetGroup": false,
    "parentBudgetId": "{parent_budget_id}",
    "parentBudgetUuid": "{parent_budget_uuid}",   // NEW UUID VALUE
    "shareFunds": "SHARE_MANUALLY",
    "recurringLimit": 200.00,
    "limitlessOverspend": false,
    "currentPeriod": {
        "startDate": "2025-12-01",
        "endDate": "2026-01-01",
        "limit": 200.00,
        "overspendBuffer": 0.00,
        "assigned": 0.00,
        "spent": {
            "cleared": 0.00,
            "pending": 0.00,
            "total": 0.00
        }
    },
    "default": false
}
```

## POST, PATCH, PUT, and DELETE operations

Currently, you cannot use UUID values in the Spend & Expense POST, PATCH, PUT or DELETE operations. This feature will be available in the future. We will share more information when this feature is available.