/ Guides / Budgets / Manage budgets / View budgets

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.

Sample requestRequest structure
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/budgets?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/budgets?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that you want to retrieve budgets for.

Allowable values:
An existing accountId
limit
integer		 The maximum number of results to return. By default, this is set to 100.

Allowable values:
[ 1 .. 1000 ]
offset
integer		 The number of results to skip. By default, this is set to 0.

Allowable values:
A valid integer
budgetId
array of strings (uuid)		 The budget(s) to return. You can use this to filter results to specific budgets only.

Allowable values:
A comma-separated list of valid budgetIds
include
array of any		 Optional embeds to include in the results.

Allowable values:
balance deprecated, budgetHierarchy, settlementDetails
search
string		 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
type
string (enum)		 The type of budget to filter results by.

Allowable values:
accountBalance, shared, individual
currencyCode
string		 The currency code to filter results by, in ISO-4217 forma

Allowable values:<br /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.

Sample responseResponse structure
Copy
Copied
{
  "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"
        }
      ]
    }
  ]
}
Copy
Copied
{
  "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"
        }
      ]
    }
  ]
}

For more detailed information about this request and its response, see the API reference.

Retrieve a budget's details

Get/v2/budgets/{budgetId}

Request

Use this request to get details about a given budget, based on its id.

Sample requestRequest structure
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/budgets/b489ea2c-0dd1-4fb1-b345-de5a596a5527?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
Copy
Copied
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.

Path parameters

Parameter Description
budgetId
string
required		 The ID of the budget you want to retrieve details for.

Allowable values:
An existing budgetId (<= 36 characters)

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that this budget belongs to.

Allowable values:
An existing accountId
include
array of any		 Optional embeds to include in the results.

Allowable values:
children, balance deprecated, details deprecated, detailsActive, budgetHierarchy, settlementDetails
currencyCode
string		 The currency code to filter results by, in ISO-4217 forma

Allowable values:<br /3 characters

Response

If your request is successful, you'll receive a 200 response containing details about the budget.

Sample responseResponse structure
Copy
Copied
{
  "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"
    }
  ]
}
Copy
Copied
{
  "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"
    }
  ]
}

For more detailed information about this request and its response, see the API reference.

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.

Sample requestRequest structure
Copy
Copied
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'
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/budgets/{budgetId}?accountId={accountId}&include=settlementDetails' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Path parameters

Parameter Description
budgetId
string
required		 The ID of the budget you want to retrieve settlement details for.

Allowable values:
An existing budgetId (<= 36 characters)

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that this budget belongs to.

Allowable values:
An existing accountId
include
array of any		 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
currencyCode
string		 The currency code to filter results by, in ISO-4217 forma

Allowable values:<br /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.

Sample responseResponse structure
Copy
Copied
{
  "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
  }
}
Copy
Copied
{
  "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.