> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equalsmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.
# View budgets
> View a list of budgets on an account, view details about a given budget, or view settlement details for a given budget.
## List all budgets
**GET** `/v2/budgets`
### Request
Use this request to retrieve a list of budgets for a given account, based on its `id`.
```bash Sample request theme={null}
curl -i -X GET \
'https://api.equalsmoney.com/v2/budgets?accountId=F12345' \
-H 'Authorization: ApiKey YOUR_API_KEY_HERE'
```
```bash Request structure theme={null}
curl -i -X GET \
'https://api.equalsmoney.com/v2/budgets?accountId={accountId}' \
-H 'Authorization: ApiKey YOUR_API_KEY_HERE'
```
#### Query parameters
The ID of the account that you want to retrieve budgets for.
Allowable values: An existing `accountId`
The maximum number of results to return. By default, this is set to `100`.
Allowable values: `[ 1 .. 1000 ]`
The number of results to skip. By default, this is set to `0`.
Allowable values: A valid integer
The budget(s) to return. You can use this to filter results to specific budgets only.
Allowable values: A comma-separated list of valid `budgetId`s
Optional embeds to include in the results.
Allowable values: `balance` deprecated, `budgetHierarchy`, `settlementDetails`
The term(s) to search for. You can use this to filter the results. For example, `Jane+Doe` to return only budgets associated with Jane Doe in some way.
Allowable values: A valid string
The type of budget to filter results by.
Allowable values: `accountBalance`, `shared`, `individual`
The currency code to filter results by, in ISO-4217 format.
Allowable values: 3 characters
### Response
If your request is successful, you'll receive a `200` response containing details about your budgets, such as their `id`. You'll need this in order to transfer funds between budgets or send outbound payments.
```json Sample response theme={null}
{
"count": 2,
"limit": 100,
"offset": 0,
"rows": [
{
"id": "f5b20908-2853-442a-960f-b23b6dcd4c39",
"accountId": "F12345",
"parentId": "5f587ee0-8a27-4cba-b586-b511b9c13033",
"boxId": "e9b7b39a-9108-46fa-882b-b09bad71ac38",
"name": "Test Budget",
"type": "individual",
"status": "active",
"allowCurrencyAlignment": false,
"createdAt": "2024-01-04T17:17:47.000Z",
"updatedAt": "2024-01-04T17:17:47.000Z",
"feature": [
{
"id": "b44b0da9-a431-44d2-9684-1049fa2e1f9e",
"budgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39",
"payments": true,
"budgetCards": false,
"peopleCards": false,
"forwardDeposits": false,
"createdAt": "2024-01-04T17:17:47.000Z",
"updatedAt": "2024-01-04T17:17:47.000Z",
"BudgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39"
}
],
"currency": [
{
"createdAt": "2024-01-04T17:17:47Z",
"updatedAt": "2024-01-04T17:17:47Z",
"id": "03416e62-a103-45f0-b6e2-8cb00b824326",
"budgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39",
"boxCurrencyId": null,
"currencyCode": "USD",
"local": "unique",
"international": "unique",
"BudgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39"
}
],
"balance": [
{
"currency": "USD",
"pendingBalance": 0,
"ledgerAndAllocatedBalance": 0,
"id": "8af2877b-d010-495b-b648-e1f113cf3984",
"budgetId": "140111b6-2ff9-498a-a9ca-26ee324dfa2f",
"currencyCode": "USD",
"ledgerBalance": 0,
"availableBalance": 0,
"lastUpdatedSequentialId": 0,
"createdAt": "2024-01-08T10:40:43.000Z",
"updatedAt": "2024-01-09T11:01:46.000Z",
"BudgetId": "140111b6-2ff9-498a-a9ca-26ee324dfa2f"
}
]
},
{
"id": "da715210-5c8d-4766-836a-bb1ff0080a8f",
"accountId": "F12345",
"parentId": null,
"boxId": "0726cf43-a5c7-41c0-8ed6-65e6256e96e8",
"name": "Account balance",
"type": "accountBalance",
"status": "active",
"allowCurrencyAlignment": false,
"createdAt": "2023-10-05T09:18:03.000Z",
"updatedAt": "2023-10-05T09:18:03.000Z",
"feature": [
{
"id": "996e0b75-f1b8-4f50-a1af-5bc245d42a04",
"budgetId": "da715210-5c8d-4766-836a-bb1ff0080a8f",
"payments": true,
"budgetCards": false,
"peopleCards": false,
"forwardDeposits": false,
"createdAt": "2023-10-05T09:18:03.000Z",
"updatedAt": "2023-10-05T09:18:07.000Z",
"BudgetId": "da715210-5c8d-4766-836a-bb1ff0080a8f"
}
],
"currency": [
{
"createdAt": "2023-10-05T09:18:03Z",
"updatedAt": "2023-10-05T09:18:03Z",
"id": "167f054e-5f75-44ac-9d7d-7c37fccae677",
"budgetId": "da715210-5c8d-4766-836a-bb1ff0080a8f",
"boxCurrencyId": null,
"currencyCode": "USD",
"local": "unique",
"international": "unique",
"BudgetId": "da715210-5c8d-4766-836a-bb1ff0080a8f"
}
],
"balance": [
{
"currency": "USD",
"pendingBalance": 0,
"ledgerAndAllocatedBalance": 0,
"id": "8af2877b-d010-495b-b648-e1f113cf3984",
"budgetId": "140111b6-2ff9-498a-a9ca-26ee324dfa2f",
"currencyCode": "USD",
"ledgerBalance": 0,
"availableBalance": 0,
"lastUpdatedSequentialId": 0,
"createdAt": "2024-01-08T10:40:43.000Z",
"updatedAt": "2024-01-09T11:01:46.000Z",
"BudgetId": "140111b6-2ff9-498a-a9ca-26ee324dfa2f"
}
]
}
]
}
```
```json Response structure theme={null}
{
"count": integer,
"limit": integer,
"offset": integer,
"rows": [
{
"id": "string",
"accountId": "string",
"parentId": "string",
"boxId": "string",
"name": "string",
"type": "string",
"status": "string",
"allowCurrencyAlignment": boolean,
"createdAt": "string",
"updatedAt": "string",
"feature": [
{
"id": "string",
"budgetId": "string",
"payments": boolean,
"budgetCards": boolean,
"peopleCards": boolean,
"forwardDeposits": boolean,
"createdAt": "string",
"updatedAt": "string",
"BudgetId": "string",
}
],
"currency": [
{
"createdAt": "string",
"updatedAt": "string",
"id": "string",
"budgetId": "string",
"boxCurrencyId": null,
"currencyCode": "string",
"local": "string",
"international": "string",
"BudgetId": "string"
}
],
"balance": [
{
"currency": "string",
"pendingBalance": number,
"ledgerAndAllocatedBalance": number,
"id": "string",
"budgetId": "string",
"currencyCode": "string",
"ledgerBalance": number,
"availableBalance": number,
"lastUpdatedSequentialId": number,
"createdAt": "string",
"updatedAt": "string",
"BudgetId": "string"
}
]
}
]
}
```
### Error responses
If your request is unsuccessful, you'll receive one of the following error responses.
```json 400 — Missing accountId theme={null}
{
"path": "/v2/budgets",
"message": "request/query must have required property 'accountId'"
}
```
For more detailed information about this request and its response, [see the API reference](/api-reference/transaction-activity/list-all-transaction-activity).
## Retrieve a budget's details
**GET** `/v2/budgets/{budgetId}`
### Request
Use this request to get details about a given budget, based on its `id`.
```bash Sample request theme={null}
curl -i -X GET \
'https://api.equalsmoney.com/v2/budgets/b489ea2c-0dd1-4fb1-b345-de5a596a5527?accountId=F12345' \
-H 'Authorization: ApiKey YOUR_API_KEY_HERE'
```
```bash Request structure theme={null}
curl -i -X GET \
'https://api.equalsmoney.com/v2/budgets/{budgetId}?accountId={accountId}' \
-H 'Authorization: ApiKey YOUR_API_KEY_HERE'
```
You can use the optional `include` parameter to return additional information such as the budget hierarchy or settlement details.
The `children` include option is only available on this endpoint — it is not supported when [listing all budgets](#list-all-budgets).
#### Path parameters
The ID of the account that this budget belongs to.
Allowable values: An existing `accountId`
Optional embeds to include in the results.
Allowable values: `children`, `balance` deprecated, `details` deprecated, `detailsActive`, `budgetHierarchy`, `settlementDetails`
The currency code to filter results by, in ISO-4217 format.
Allowable values: 3 characters
### Response
If your request is successful, you'll receive a `200` response containing details about the budget.
```json Sample response theme={null}
{
"id": "f5b20908-2853-442a-960f-b23b6dcd4c39",
"accountId": "F12345",
"parentId": "5f587ee0-8a27-4cba-b586-b511b9c13033",
"boxId": "e9b7b39a-9108-46fa-882b-b09bad71ac38",
"name": "Test Budget",
"type": "individual",
"status": "active",
"allowCurrencyAlignment": false,
"createdAt": "2024-01-04T17:17:47.000Z",
"updatedAt": "2024-01-04T17:17:47.000Z",
"feature": [
{
"id": "b44b0da9-a431-44d2-9684-1049fa2e1f9e",
"budgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39",
"payments": true,
"budgetCards": false,
"peopleCards": false,
"forwardDeposits": false,
"createdAt": "2024-01-04T17:17:47.000Z",
"updatedAt": "2024-01-04T17:17:47.000Z",
"BudgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39"
}
],
"currency": [
{
"createdAt": "2024-01-04T17:17:47Z",
"updatedAt": "2024-01-04T17:17:47Z",
"id": "03416e62-a103-45f0-b6e2-8cb00b824326",
"budgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39",
"boxCurrencyId": null,
"currencyCode": "USD",
"local": "unique",
"international": "unique",
"BudgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39"
}
],
"balance": [
{
"currency": "GBP",
"pendingBalance": 0,
"ledgerAndAllocatedBalance": 0,
"id": "c92064a5-48b4-42f4-923f-eca87a97f77b",
"budgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39",
"currencyCode": "GBP",
"ledgerBalance": 0,
"availableBalance": 0,
"lastUpdatedSequentialId": 0,
"createdAt": "2024-01-05T13:44:30.000Z",
"updatedAt": "2024-01-05T13:44:30.000Z",
"BudgetId": "f5b20908-2853-442a-960f-b23b6dcd4c39"
}
]
}
```
```json Response structure theme={null}
{
"id": "string",
"accountId": "string",
"parentId": "string",
"boxId": "string",
"name": "string",
"type": "string",
"status": "string",
"allowCurrencyAlignment": boolean,
"createdAt": "string",
"updatedAt": "string",
"feature": [
{
"id": "string",
"budgetId": "string",
"payments": boolean,
"budgetCards": boolean,
"peopleCards": boolean,
"forwardDeposits": boolean,
"createdAt": "string",
"updatedAt": "string",
"BudgetId": "string"
}
],
"currency": [
{
"createdAt": "string",
"updatedAt": "string",
"id": "string",
"budgetId": "string",
"boxCurrencyId": null,
"currencyCode": "string",
"local": "string",
"international": "string",
"BudgetId": "string"
}
],
"balance": [
{
"currency": "string",
"pendingBalance": number,
"ledgerAndAllocatedBalance": number,
"id": "string",
"budgetId": "string",
"currencyCode": "string",
"ledgerBalance": number,
"availableBalance": number,
"lastUpdatedSequentialId": number,
"createdAt": "string",
"updatedAt": "string",
"BudgetId": "string"
}
]
}
```
### Error responses
If your request is unsuccessful, you'll receive one of the following error responses.
```json 404 — Budget not found theme={null}
{
"path": "/v2/budgets/b489ea2c-0dd1-4fb1-b345-de5a596a5527",
"message": "budget not found"
}
```
For more detailed information about this request and its response, [see the API reference](/api-reference/budgets/retrieve-budget-details).
## Get settlement details
**GET** `/v2/budgets/{budgetId}/?accountId={accountId}&include=settlementDetails`
### Request
Use this request to retrieve settlement details for a given budget. These details can be used to send and transfer funds from an external account.
```bash Sample request theme={null}
curl -i -X GET \
'https://api.equalsmoney.com/v2/budgets/b489ea2c-0dd1-4fb1-b345-de5a596a5527?accountId=F12345&include=settlementDetails' \
-H 'Authorization: ApiKey YOUR_API_KEY_HERE'
```
```bash Request structure theme={null}
curl -i -X GET \
'https://api.equalsmoney.com/v2/budgets/{budgetId}?accountId={accountId}&include=settlementDetails' \
-H 'Authorization: ApiKey YOUR_API_KEY_HERE'
```
#### Path parameters
The ID of the account that this budget belongs to.
Allowable values: An existing `accountId`
Optional embeds to include in the results. To get settlement details in your response, you'll need to use `include=settlementDetails`.
Allowable values: `children`, `balance` deprecated, `details` deprecated, `detailsActive`, `budgetHierarchy`, `settlementDetails`
The currency code to filter results by, in ISO-4217 format.
Allowable values: 3 characters
### Response
If your request is successful, you'll receive a `200` response containing details about the budget. You can use the settlement details included in this response to perform a bank transfer from an external account.
The `currency.local` and `currency.international` enums provide additional information about your settlement details:
* `unique` means the settlement details returned are unique for your budget
* `shared` means that the settlement details are a pooled account that will need to be matched to your budget via a reference
* `any` means that we check for available unique details for the currency and the region and if available, we return that. If not, we fall back to shared details that are available for that currency in that region for your account configuration.
Use the `currencyDetails.local` object for domestic payments inside the currency's domestic region. The `accountIdentifier` represents an account number, for example an account number for FPS in the UK or an IBAN for SEPA in Europe. The `bankIdentifier` identifies the bank itself, for example a sort code in the UK or a routing number in the US.
Use the `currencyDetails.international` object when paying the currency outside of its domestic region, i.e., for global payments via SWIFT. The `accountIdentifier` represents an IBAN and the `bankIdentifier` represents a BIC.
```json Sample response theme={null}
{
"id": "5f587ee0-8a27-4cba-b586-b511b9c13033",
"accountId": "F12345",
"parentId": null,
"boxId": "e2386fcb-3e78-40f7-8a13-ee17acc0b8fa",
"name": "Account balance",
"type": "accountBalance",
"status": "active",
"allowCurrencyAlignment": false,
"createdAt": "2023-10-02T10:29:46.000Z",
"updatedAt": "2023-10-02T10:29:46.000Z",
"feature": [
{
"id": "0c92f865-f59c-4240-886b-1c054641e805",
"budgetId": "5f587ee0-8a27-4cba-b586-b511b9c13033",
"payments": true,
"budgetCards": false,
"peopleCards": false,
"forwardDeposits": false,
"createdAt": "2023-10-02T10:29:46.000Z",
"updatedAt": "2023-10-02T10:29:50.000Z",
"BudgetId": "5f587ee0-8a27-4cba-b586-b511b9c13033"
}
],
"currency": [
{
"createdAt": "2023-10-02T10:29:46Z",
"updatedAt": "2023-10-02T10:29:46Z",
"id": "3f4aec89-1008-4cab-8a1a-164e58022fb9",
"budgetId": "5f587ee0-8a27-4cba-b586-b511b9c13033",
"boxCurrencyId": null,
"currencyCode": "GBP",
"local": "unique",
"international": "unique",
"BudgetId": "5f587ee0-8a27-4cba-b586-b511b9c13033"
}
],
"balance": [
{
"currency": "GBP",
"pendingBalance": 0,
"ledgerAndAllocatedBalance": 0,
"id": "8af2877b-d010-495b-b648-e1f113cf3984",
"budgetId": "140111b6-2ff9-498a-a9ca-26ee324dfa2f",
"currencyCode": "GBP",
"ledgerBalance": 0,
"availableBalance": 0,
"lastUpdatedSequentialId": 0,
"createdAt": "2024-01-08T10:40:43.000Z",
"updatedAt": "2024-01-09T11:01:46.000Z",
"BudgetId": "140111b6-2ff9-498a-a9ca-26ee324dfa2f"
}
],
"settlementDetails": {
"currencyDetails": [
{
"currencyCode": "GBP",
"local": {
"accountIdentifier": "31510604",
"bankIdentifier": "10-00-00",
"payeeName": "ACME II",
"bankName": "Brilliant Bank",
"bankAddress": {
"addressLine1": "41 Middle Street",
"addressLine2": "",
"addressLine3": "",
"city": "Enfield",
"postcode": "EN13JY",
"country": "United Kingdom"
}
},
"international": {
"accountIdentifier": "GB24BKEN10000031510604",
"bankIdentifier": "QBLCCCCV",
"payeeName": "ACME II",
"bankName": "Brilliant Bank",
"bankAddress": {
"addressLine1": "41 Middle Street",
"addressLine2": "",
"addressLine3": "",
"city": "Enfield",
"postcode": "EN13JY",
"country": "United Kingdom"
}
}
},
{
"currencyCode": "EUR",
"local": {
"accountIdentifier": "GB27BOFI90212729823529",
"bankIdentifier": "QBLCCCCV",
"payeeName": "ACME II",
"bankName": "Brilliant Bank",
"bankAddress": {
"addressLine1": "41 Middle Street",
"addressLine2": "",
"addressLine3": "",
"city": "Enfield",
"postcode": "EN13JY",
"country": "United Kingdom"
}
},
"international": {
"accountIdentifier": "GB27BOFI90212729823529",
"bankIdentifier": "QBLCCCCV",
"payeeName": "ACME II",
"bankName": "Brilliant Bank",
"bankAddress": {
"addressLine1": "41 Middle Street",
"addressLine2": "",
"addressLine3": "",
"city": "Enfield",
"postcode": "EN13JY",
"country": "United Kingdom"
}
}
},
{
"currencyCode": "USD",
"local": {
"accountIdentifier": "0299007006",
"bankIdentifier": "026012356",
"payeeName": "ACME II",
"bankName": "Brilliant Bank",
"bankAddress": {
"addressLine1": "123 Park Ave",
"addressLine2": "",
"addressLine3": "",
"city": "New York",
"postcode": "NY 10016",
"country": "United Kingdom"
}
},
"international": {
"accountIdentifier": "GB17BOFS80055100813796",
"bankIdentifier": "QBLCCCCV",
"payeeName": "ACME II",
"bankName": "Brilliant Bank",
"bankAddress": {
"addressLine1": "41 Middle Street",
"addressLine2": "",
"addressLine3": "",
"city": "Enfield",
"postcode": "EN13JY",
"country": "United Kingdom"
}
}
}
],
"balanceReference": null
}
}
```
```json Response structure theme={null}
{
"id": "string",
"accountId": "string",
"parentId": null,
"boxId": "string",
"name": "string",
"type": "string",
"status": "string",
"allowCurrencyAlignment": boolean,
"createdAt": "string",
"updatedAt": "string",
"feature": [
{
"id": "string",
"budgetId": "string",
"payments": boolean,
"budgetCards": boolean,
"peopleCards": boolean,
"forwardDeposits": boolean,
"createdAt": "string",
"updatedAt": "string",
"BudgetId": "string"
}
],
"currency": [
{
"createdAt": "string",
"updatedAt": "string",
"id": "string",
"budgetId": "string",
"boxCurrencyId": null,
"currencyCode": "string",
"local": "string",
"international": "string",
"BudgetId": "string"
}
],
"balance": [
{
"currency": "string",
"pendingBalance": number,
"ledgerAndAllocatedBalance": number,
"id": "string",
"budgetId": "string",
"currencyCode": "string",
"ledgerBalance": number,
"availableBalance": number,
"lastUpdatedSequentialId": number,
"createdAt": "string",
"updatedAt": "string",
"BudgetId": "string"
}
],
"settlementDetails": {
"currencyDetails": [
{
"currencyCode": "string",
"local": {
"accountIdentifier": "string",
"bankIdentifier": "string",
"payeeName": "string",
"bankName": "string",
"bankAddress": {
"addressLine1": "string",
"addressLine2": "string",
"addressLine3": "string",
"city": "string",
"postcode": "string",
"country": "string"
}
},
"international": {
"accountIdentifier": "string",
"bankIdentifier": "string",
"payeeName": "string",
"bankName": "string",
"bankAddress": {
"addressLine1": "string",
"addressLine2": "string",
"addressLine3": "string",
"city": "string",
"postcode": "string",
"country": "string"
}
}
},
{
"currencyCode": "string",
"local": {
"accountIdentifier": "string",
"bankIdentifier": "string",
"payeeName": "string",
"bankName": "string",
"bankAddress": {
"addressLine1": "string",
"addressLine2": "string",
"addressLine3": "string",
"city": "string",
"postcode": "string",
"country": "string"
}
},
"international": {
"accountIdentifier": "string",
"bankIdentifier": "string",
"payeeName": "string",
"bankName": "string",
"bankAddress": {
"addressLine1": "string",
"addressLine2": "string",
"addressLine3": "string",
"city": "string",
"postcode": "string",
"country": "string"
}
}
},
{
"currencyCode": "string",
"local": {
"accountIdentifier": "string",
"bankIdentifier": "string",
"payeeName": "string",
"bankName": "string",
"bankAddress": {
"addressLine1": "string",
"addressLine2": "string",
"addressLine3": "string",
"city": "string",
"postcode": "string",
"country": "string"
}
},
"international": {
"accountIdentifier": "string",
"bankIdentifier": "string",
"payeeName": "string",
"bankName": "string",
"bankAddress": {
"addressLine1": "string",
"addressLine2": "string",
"addressLine3": "string",
"city": "string",
"postcode": "string",
"country": "string"
}
}
}
],
"balanceReference": null
}
}
```
For more detailed information about this request and its response, [see the API reference](/api-reference/budgets/retrieve-budget-details).